release: 0.12.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.1"
+  ".": "0.12.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 4
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/isaacus%2Fisaacus-ee884a4336559147aacf9a927a540f21e9760f00d2d5588af00fa8a25e2707d9.yml
-openapi_spec_hash: 2ba78bd360942c63a7d08dba791f00d2
-config_hash: a85580968a69d8d6fadf96e5e2d6870e
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/isaacus%2Fisaacus-6705b8e0baa0e4aad69a1c04e9876b352e40e0e5caf21e87e7b2c355e70c4e66.yml
+openapi_spec_hash: 87d3cc80f5ddc5275e8a47d35f1a484e
+config_hash: eb6af7379e9073b3ece2803bfcf65e68

CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.12.0 (2025-12-02)
+
+Full Changelog: [v0.11.1...v0.12.0](https://github.com/isaacus-dev/isaacus-typescript/compare/v0.11.1...v0.12.0)
+
+### Features
+
+* **mcp:** add detail field to docs search tool ([a4a3478](https://github.com/isaacus-dev/isaacus-typescript/commit/a4a3478307e75a7147f2bc3137677327abbeae35))
+* **mcp:** enable optional code execution tool on http mcp servers ([579b63d](https://github.com/isaacus-dev/isaacus-typescript/commit/579b63d0d5a3cde717ac41654d6e708673d0191c))
+* **mcp:** return logs on code tool errors ([f8cc9b0](https://github.com/isaacus-dev/isaacus-typescript/commit/f8cc9b0afc5365abe559f07c85883895ee2f4900))
+
+
+### Bug Fixes
+
+* **mcpb:** pin @anthropic-ai/mcpb version ([fc022b2](https://github.com/isaacus-dev/isaacus-typescript/commit/fc022b2a940c8c3161082faa8c4e5457bdd53957))
+* **mcp:** return tool execution error on api error ([5ae2a33](https://github.com/isaacus-dev/isaacus-typescript/commit/5ae2a33f2dfe5e3f1437e48045c15be34ee9c4e5))
+* **mcp:** return tool execution error on jq failure ([719a2bc](https://github.com/isaacus-dev/isaacus-typescript/commit/719a2bcb3ae336919ed9f63c04c06bf1eb5ad1fd))
+
+
+### Chores
+
+* **client:** fix logger property type ([73a6ad5](https://github.com/isaacus-dev/isaacus-typescript/commit/73a6ad5b2c1a9cd42c061401c47abc51db8510d4))
+* **internal:** codegen related update ([d58f59b](https://github.com/isaacus-dev/isaacus-typescript/commit/d58f59bc6ac418f586698a45d535a68998454cbe))
+* **internal:** codegen related update ([47ef370](https://github.com/isaacus-dev/isaacus-typescript/commit/47ef37027fcc8731651c47ec72db684ae0662e54))
+* **internal:** grammar fix (it's -> its) ([cbeea36](https://github.com/isaacus-dev/isaacus-typescript/commit/cbeea365a8107e894cdeff0d0f7ed6ecfb1e2f2f))
+* mcp code tool explicit error message when missing a run function ([45f0ec4](https://github.com/isaacus-dev/isaacus-typescript/commit/45f0ec4f7cd466097f623a9dde1a0b8e084f9fdc))
+* **mcp:** add friendlier MCP code tool errors on incorrect method invocations ([08e1eac](https://github.com/isaacus-dev/isaacus-typescript/commit/08e1eac13c3581f7c09150de36e8948e8ee94b6e))
+* **mcp:** add line numbers to code tool errors ([51fc353](https://github.com/isaacus-dev/isaacus-typescript/commit/51fc353019df5583769e087b93153d398019a639))
+* **mcp:** clarify http auth error ([39fab03](https://github.com/isaacus-dev/isaacus-typescript/commit/39fab03e07a9d600b627d2146fbe231377a78577))
+* **mcp:** upgrade jq-web ([5f375e8](https://github.com/isaacus-dev/isaacus-typescript/commit/5f375e8eb4353218198c5edd82404e00066a1fff))
+* use structured error when code execution tool errors ([bb4ba8a](https://github.com/isaacus-dev/isaacus-typescript/commit/bb4ba8a1485229cfc60ba38361520b2a9f65b7de))
+
+
+### Documentation
+
+* **mcp:** add a README button for one-click add to Cursor ([afbeeb5](https://github.com/isaacus-dev/isaacus-typescript/commit/afbeeb5b7b662f3144ef2571b7f33b1225daf5df))
+* **mcp:** add a README link to add server to VS Code or Claude Code ([6042a69](https://github.com/isaacus-dev/isaacus-typescript/commit/6042a69bb085d6a0d21b982d448e540fccc6036f))
+* **sdk:** specify example params ([00ec4d8](https://github.com/isaacus-dev/isaacus-typescript/commit/00ec4d8e97a35bc2de73666db6eede82bd618236))
+
 ## 0.11.1 (2025-10-14)
 
 Full Changelog: [v0.11.0...v0.11.1](https://github.com/isaacus-dev/isaacus-typescript/compare/v0.11.0...v0.11.1)

README.md

@@ -29,6 +29,7 @@ const client = new Isaacus({
 const embeddingResponse = await client.embeddings.create({
   model: 'kanon-2-embedder',
   texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'],
+  task: 'retrieval/query',
 });
 
 console.log(embeddingResponse.embeddings);
@@ -49,6 +50,7 @@ const client = new Isaacus({
 const params: Isaacus.EmbeddingCreateParams = {
   model: 'kanon-2-embedder',
   texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'],
+  task: 'retrieval/query',
 };
 const embeddingResponse: Isaacus.EmbeddingResponse = await client.embeddings.create(params);
 ```
@@ -67,6 +69,7 @@ const embeddingResponse = await client.embeddings
   .create({
     model: 'kanon-2-embedder',
     texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'],
+    task: 'retrieval/query',
   })
   .catch(async (err) => {
     if (err instanceof Isaacus.APIError) {
@@ -108,7 +111,7 @@ const client = new Isaacus({
 });
 
 // Or, configure per-request:
-await client.embeddings.create({ model: 'kanon-2-embedder', texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'] }, {
+await client.embeddings.create({ model: 'kanon-2-embedder', texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'], task: 'retrieval/query' }, {
   maxRetries: 5,
 });
 ```
@@ -125,7 +128,7 @@ const client = new Isaacus({
 });
 
 // Override per-request:
-await client.embeddings.create({ model: 'kanon-2-embedder', texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'] }, {
+await client.embeddings.create({ model: 'kanon-2-embedder', texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'], task: 'retrieval/query' }, {
   timeout: 5 * 1000,
 });
 ```
@@ -152,6 +155,7 @@ const response = await client.embeddings
   .create({
     model: 'kanon-2-embedder',
     texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'],
+    task: 'retrieval/query',
   })
   .asResponse();
 console.log(response.headers.get('X-My-Header'));
@@ -161,6 +165,7 @@ const { data: embeddingResponse, response: raw } = await client.embeddings
   .create({
     model: 'kanon-2-embedder',
     texts: ['Are restraints of trade enforceable under English law?', 'What is a non-compete clause?'],
+    task: 'retrieval/query',
   })
   .withResponse();
 console.log(raw.headers.get('X-My-Header'));

package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacus",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "The official TypeScript library for the Isaacus API",
   "author": "Isaacus <support@isaacus.com>",
   "types": "dist/index.d.ts",

packages/mcp-server/README.md

@@ -34,12 +34,36 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
+### Cursor
+
+If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
+in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=isaacus-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImlzYWFjdXMtbWNwIl0sImVudiI6eyJJU0FBQ1VTX0FQSV9LRVkiOiJTZXQgeW91ciBJU0FBQ1VTX0FQSV9LRVkgaGVyZS4ifX0)
+
+### VS Code
+
+If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables
+in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration.
+
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22isaacus-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22isaacus-mcp%22%5D%2C%22env%22%3A%7B%22ISAACUS_API_KEY%22%3A%22Set%20your%20ISAACUS_API_KEY%20here.%22%7D%7D)
+
+### Claude Code
+
+If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
+environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
+
+```
+claude mcp add --transport stdio isaacus_api --env ISAACUS_API_KEY="Your ISAACUS_API_KEY here." -- npx -y isaacus-mcp
+```
+
 ## Exposing endpoints to your MCP Client
 
-There are two ways to expose endpoints as tools in the MCP server:
+There are three ways to expose endpoints as tools in the MCP server:
 
 1. Exposing one tool per endpoint, and filtering as necessary
 2. Exposing a set of tools to dynamically discover and invoke endpoints from the API
+3. Exposing a docs search tool and a code execution tool, allowing the client to write code to be executed against the TypeScript client
 
 ### Filtering endpoints and tools
 
@@ -74,6 +98,18 @@ All of these command-line options can be repeated, combined together, and have c
 
 Use `--list` to see the list of available tools, or see below.
 
+### Code execution
+
+If you specify `--tools=code` to the MCP server, it will expose just two tools:
+
+- `search_docs` - Searches the API documentation and returns a list of markdown results
+- `execute` - Runs code against the TypeScript client
+
+This allows the LLM to implement more complex logic by chaining together many API calls without loading
+intermediary results into its context window.
+
+The code execution itself happens in a Deno sandbox that has network access only to the base URL for the API.
+
 ### Specifying the MCP Client
 
 Different clients have varying abilities to handle arbitrary tools and schemas.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacus-mcp",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "The official MCP Server for the Isaacus API",
   "author": "Isaacus <support@isaacus.com>",
   "types": "dist/index.d.ts",
@@ -36,8 +36,10 @@
     "@valtown/deno-http-worker": "^0.0.21",
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.6/jq-web.tar.gz",
+    "fuse.js": "^7.1.0",
+    "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz",
     "qs": "^6.14.0",
+    "typescript": "5.8.3",
     "yargs": "^17.7.2",
     "zod": "^3.25.20",
     "zod-to-json-schema": "^3.24.5",
@@ -47,7 +49,7 @@
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
-    "@anthropic-ai/mcpb": "^1.1.0",
+    "@anthropic-ai/mcpb": "1.1.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
@@ -64,8 +66,7 @@
     "ts-morph": "^19.0.0",
     "ts-node": "^10.5.0",
     "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
-    "tsconfig-paths": "^4.0.0",
-    "typescript": "5.8.3"
+    "tsconfig-paths": "^4.0.0"
   },
   "imports": {
     "isaacus-mcp": ".",

packages/mcp-server/src/code-tool-types.ts

@@ -11,4 +11,8 @@ export type WorkerSuccess = {
   logLines: string[];
   errLines: string[];
 };
-export type WorkerError = { message: string | undefined };
+export type WorkerError = {
+  message: string | undefined;
+  logLines: string[];
+  errLines: string[];
+};