release: 0.22.1

.github/workflows/ci.yml

@@ -1,12 +1,14 @@
 name: CI
 on:
   push:
-    branches-ignore:
-      - 'generated'
-      - 'codegen/**'
-      - 'integrated/**'
-      - 'stl-preview-head/**'
-      - 'stl-preview-base/**'
+    branches:
+      - '**'
+      - '!integrated/**'
+      - '!stl-preview-head/**'
+      - '!stl-preview-base/**'
+      - '!generated'
+      - '!codegen/**'
+      - 'codegen/stl/**'
   pull_request:
     branches-ignore:
       - 'stl-preview-head/**'
@@ -17,7 +19,7 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/isaacus-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@v6
 
@@ -36,7 +38,7 @@ jobs:
     timeout-minutes: 5
     name: build
     runs-on: ${{ github.repository == 'stainless-sdks/isaacus-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     permissions:
       contents: read
       id-token: write

.github/workflows/publish-npm.yml

@@ -33,13 +33,14 @@ jobs:
 
       - name: Publish to NPM
         run: |
-          if [ -n "${{ github.event.inputs.path }}" ]; then
-            PATHS_RELEASED='[\"${{ github.event.inputs.path }}\"]'
+          if [ -n "$INPUT_PATH" ]; then
+            PATHS_RELEASED="[\"$INPUT_PATH\"]"
           else
             PATHS_RELEASED='[\".\", \"packages/mcp-server\"]'
           fi
           yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }"
         env:
+          INPUT_PATH: ${{ github.event.inputs.path }}
           NPM_TOKEN: ${{ secrets.ISAACUS_NPM_TOKEN || secrets.NPM_TOKEN }}
 
       - name: Upload MCP Server DXT GitHub release asset

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 node_modules
 yarn-error.log
 codegen.log

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.22.0"
+  ".": "0.22.1"
 }

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.22.1 (2026-03-28)
+
+Full Changelog: [v0.22.0...v0.22.1](https://github.com/isaacus-dev/isaacus-typescript/compare/v0.22.0...v0.22.1)
+
+### Chores
+
+* **ci:** escape input path in publish-npm workflow ([37de3db](https://github.com/isaacus-dev/isaacus-typescript/commit/37de3db4c34147f751a6fa8ae60f8dcc9ad477b7))
+* **ci:** skip lint on metadata-only changes ([03c9e5f](https://github.com/isaacus-dev/isaacus-typescript/commit/03c9e5fc53ddd4c08aa66fd3b93afa067d21e185))
+* **internal:** bump @modelcontextprotocol/sdk, @hono/node-server, and minimatch ([2721387](https://github.com/isaacus-dev/isaacus-typescript/commit/27213877706a51093af4eb15e3ed1eeb71af9e97))
+* **internal:** codegen related update ([dc8c9d9](https://github.com/isaacus-dev/isaacus-typescript/commit/dc8c9d98bbeb42dac7bd9b8166a59097031759e6))
+* **internal:** fix MCP server TS errors that occur with required client options ([c834dba](https://github.com/isaacus-dev/isaacus-typescript/commit/c834dba3466004f1385dabbea908480217988d2b))
+* **internal:** make generated MCP servers compatible with Cloudflare worker environments ([6e1fbb2](https://github.com/isaacus-dev/isaacus-typescript/commit/6e1fbb2ceef03158f8a1b4be24bb30608069faad))
+* **internal:** support custom-instructions-path flag in MCP servers ([9c72691](https://github.com/isaacus-dev/isaacus-typescript/commit/9c726913496aa66da7acac78b5501f95946dcbb2))
+* **internal:** support local docs search in MCP servers ([0f9290d](https://github.com/isaacus-dev/isaacus-typescript/commit/0f9290dac91e2e7c42218e660fb267db751ee19f))
+* **internal:** support x-stainless-mcp-client-envs header in MCP servers ([274f5c2](https://github.com/isaacus-dev/isaacus-typescript/commit/274f5c2620d69c0d97e5933d7b0804b3583570f8))
+* **internal:** support x-stainless-mcp-client-permissions headers in MCP servers ([aba6116](https://github.com/isaacus-dev/isaacus-typescript/commit/aba6116403bede7f968a37e080b8e6ed52893d51))
+* **internal:** tweak CI branches ([b97f70d](https://github.com/isaacus-dev/isaacus-typescript/commit/b97f70db25ccb1a838a92751ae1384d4220e2ac8))
+* **internal:** update gitignore ([971e5bd](https://github.com/isaacus-dev/isaacus-typescript/commit/971e5bd2076c311e7a90b346f9ea9dca013f2760))
+
 ## 0.22.0 (2026-03-11)
 
 Full Changelog: [v0.21.0...v0.22.0](https://github.com/isaacus-dev/isaacus-typescript/compare/v0.21.0...v0.22.0)

package.json

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

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "isaacus-mcp",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "The official MCP Server for the Isaacus API",
   "author": {
     "name": "Isaacus",

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacus-mcp",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "The official MCP Server for the Isaacus API",
   "author": "Isaacus <support@isaacus.com>",
   "types": "dist/index.d.ts",
@@ -41,6 +41,7 @@
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "fuse.js": "^7.1.0",
+    "minisearch": "^7.2.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz",
     "pino": "^10.3.1",
     "pino-http": "^11.0.0",

packages/mcp-server/src/code-tool-paths.cts

@@ -1,3 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export const workerPath = require.resolve('./code-tool-worker.mjs');
+export function getWorkerPath(): string {
+  return require.resolve('./code-tool-worker.mjs');
+}

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

@@ -1,10 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import fs from 'node:fs';
-import path from 'node:path';
-import url from 'node:url';
-import { newDenoHTTPWorker } from '@valtown/deno-http-worker';
-import { workerPath } from './code-tool-paths.cjs';
 import {
   ContentBlock,
   McpRequestContext,
@@ -153,19 +148,23 @@ const remoteStainlessHandler = async ({
 
   const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
 
+  const localClientEnvs = {
+    ISAACUS_API_KEY: requireValue(
+      readEnv('ISAACUS_API_KEY') ?? client.apiKey,
+      'set ISAACUS_API_KEY environment variable or provide apiKey client option',
+    ),
+    ISAACUS_BASE_URL: readEnv('ISAACUS_BASE_URL') ?? client.baseURL ?? undefined,
+  };
+  // Merge any upstream client envs from the request header, with upstream values taking precedence.
+  const mergedClientEnvs = { ...localClientEnvs, ...reqContext.upstreamClientEnvs };
+
   // Setting a Stainless API key authenticates requests to the code tool endpoint.
   const res = await fetch(codeModeEndpoint, {
     method: 'POST',
     headers: {
       ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
       'Content-Type': 'application/json',
-      'x-stainless-mcp-client-envs': JSON.stringify({
-        ISAACUS_API_KEY: requireValue(
-          readEnv('ISAACUS_API_KEY') ?? client.apiKey,
-          'set ISAACUS_API_KEY environment variable or provide apiKey client option',
-        ),
-        ISAACUS_BASE_URL: readEnv('ISAACUS_BASE_URL') ?? client.baseURL ?? undefined,
-      }),
+      'x-stainless-mcp-client-envs': JSON.stringify(mergedClientEnvs),
     },
     body: JSON.stringify({
       project_name: 'isaacus',
@@ -208,6 +207,13 @@ const localDenoHandler = async ({
   reqContext: McpRequestContext;
   args: unknown;
 }): Promise<ToolCallResult> => {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const url = await import('node:url');
+  const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker');
+  const { getWorkerPath } = await import('./code-tool-paths.cjs');
+  const workerPath = getWorkerPath();
+
   const client = reqContext.client;
   const baseURLHostname = new URL(client.baseURL).hostname;
   const { code } = args as { code: string };
@@ -269,6 +275,9 @@ const localDenoHandler = async ({
     printOutput: true,
     spawnOptions: {
       cwd: path.dirname(workerPath),
+      // Merge any upstream client envs into the Deno subprocess environment,
+      // with the upstream env vars taking precedence.
+      env: { ...process.env, ...reqContext.upstreamClientEnvs },
     },
   });
 
@@ -278,13 +287,15 @@ const localDenoHandler = async ({
         reject(new Error(`Worker exited with code ${exitCode}`));
       });
 
-      const opts: ClientOptions = {
-        baseURL: client.baseURL,
-        apiKey: client.apiKey,
+      // Strip null/undefined values so that the worker SDK client can fall back to
+      // reading from environment variables (including any upstreamClientEnvs).
+      const opts = {
+        ...(client.baseURL != null ? { baseURL: client.baseURL } : undefined),
+        ...(client.apiKey != null ? { apiKey: client.apiKey } : undefined),
         defaultHeaders: {
           'X-Stainless-MCP': 'true',
         },
-      };
+      } satisfies Partial<ClientOptions> as ClientOptions;
 
       const req = worker.request(
         'http://localhost',

packages/mcp-server/src/docs-search-tool.ts

@@ -3,6 +3,7 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { Metadata, McpRequestContext, asTextContentResult } from './types';
 import { getLogger } from './logger';
+import type { LocalDocsSearch } from './local-docs-search';
 
 export const metadata: Metadata = {
   resource: 'all',
@@ -43,20 +44,49 @@ export const tool: Tool = {
 const docsSearchURL =
   process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/isaacus/docs/search';
 
-export const handler = async ({
-  reqContext,
-  args,
-}: {
-  reqContext: McpRequestContext;
-  args: Record<string, unknown> | undefined;
-}) => {
+let _localSearch: LocalDocsSearch | undefined;
+
+export function setLocalSearch(search: LocalDocsSearch): void {
+  _localSearch = search;
+}
+
+const SUPPORTED_LANGUAGES = new Set(['http', 'typescript', 'javascript']);
+
+async function searchLocal(args: Record<string, unknown>): Promise<unknown> {
+  if (!_localSearch) {
+    throw new Error('Local search not initialized');
+  }
+
+  const query = (args['query'] as string) ?? '';
+  const language = (args['language'] as string) ?? 'typescript';
+  const detail = (args['detail'] as string) ?? 'verbose';
+
+  if (!SUPPORTED_LANGUAGES.has(language)) {
+    throw new Error(
+      `Local docs search only supports HTTP, TypeScript, and JavaScript. Got language="${language}". ` +
+        `Use --docs-search-mode stainless-api for other languages, or set language to "http", "typescript", or "javascript".`,
+    );
+  }
+
+  return _localSearch.search({
+    query,
+    language,
+    detail,
+    maxResults: 10,
+  }).results;
+}
+
+async function searchRemote(
+  args: Record<string, unknown>,
+  stainlessApiKey: string | undefined,
+): Promise<unknown> {
   const body = args as any;
   const query = new URLSearchParams(body).toString();
 
   const startTime = Date.now();
   const result = await fetch(`${docsSearchURL}?${query}`, {
     headers: {
-      ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
+      ...(stainlessApiKey && { Authorization: stainlessApiKey }),
     },
   });
 
@@ -75,7 +105,7 @@ export const handler = async ({
       'Got error response from docs search tool',
     );
 
-    if (result.status === 404 && !reqContext.stainlessApiKey) {
+    if (result.status === 404 && !stainlessApiKey) {
       throw new Error(
         'Could not find docs for this project. You may need to provide a Stainless API key via the STAINLESS_API_KEY environment variable, the --stainless-api-key flag, or the x-stainless-api-key HTTP header.',
       );
@@ -94,7 +124,23 @@ export const handler = async ({
     },
     'Got docs search result',
   );
-  return asTextContentResult(resultBody);
+  return resultBody;
+}
+
+export const handler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => {
+  const body = args ?? {};
+
+  if (_localSearch) {
+    return asTextContentResult(await searchLocal(body));
+  }
+
+  return asTextContentResult(await searchRemote(body, reqContext.stainlessApiKey));
 };
 
 export default { metadata, tool, handler };

packages/mcp-server/src/http.ts

@@ -23,18 +23,61 @@ const newServer = async ({
   res: express.Response;
 }): Promise<McpServer | null> => {
   const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
-  const server = await newMcpServer(stainlessApiKey);
+  const customInstructionsPath = mcpOptions.customInstructionsPath;
+  const server = await newMcpServer({ stainlessApiKey, customInstructionsPath });
 
   const authOptions = parseClientAuthHeaders(req, false);
 
+  let upstreamClientEnvs: Record<string, string> | undefined;
+  const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs'];
+  if (typeof clientEnvsHeader === 'string') {
+    try {
+      const parsed = JSON.parse(clientEnvsHeader);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        upstreamClientEnvs = parsed;
+      }
+    } catch {
+      // Ignore malformed header
+    }
+  }
+
+  // Parse x-stainless-mcp-client-permissions header to override permission options
+  //
+  // Note: Permissions are best-effort and intended to prevent clients from doing unexpected things;
+  // they're not a hard security boundary, so we allow arbitrary, client-driven overrides.
+  //
+  // See the Stainless MCP documentation for more details.
+  let effectiveMcpOptions = mcpOptions;
+  const clientPermissionsHeader = req.headers['x-stainless-mcp-client-permissions'];
+  if (typeof clientPermissionsHeader === 'string') {
+    try {
+      const parsed = JSON.parse(clientPermissionsHeader);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        effectiveMcpOptions = {
+          ...mcpOptions,
+          ...(typeof parsed.allow_http_gets === 'boolean' && { codeAllowHttpGets: parsed.allow_http_gets }),
+          ...(Array.isArray(parsed.allowed_methods) && { codeAllowedMethods: parsed.allowed_methods }),
+          ...(Array.isArray(parsed.blocked_methods) && { codeBlockedMethods: parsed.blocked_methods }),
+        };
+        getLogger().info(
+          { clientPermissions: parsed },
+          'Overriding code execution permissions from x-stainless-mcp-client-permissions header',
+        );
+      }
+    } catch (error) {
+      getLogger().warn({ error }, 'Failed to parse x-stainless-mcp-client-permissions header');
+    }
+  }
+
   await initMcpServer({
     server: server,
-    mcpOptions: mcpOptions,
+    mcpOptions: effectiveMcpOptions,
     clientOptions: {
       ...clientOptions,
       ...authOptions,
     },
     stainlessApiKey: stainlessApiKey,
+    upstreamClientEnvs,
   });
 
   return server;
@@ -72,7 +115,7 @@ const del = async (req: express.Request, res: express.Response) => {
 };
 
 const redactHeaders = (headers: Record<string, any>) => {
-  const hiddenHeaders = /auth|cookie|key|token/i;
+  const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i;
   const filtered = { ...headers };
   Object.keys(filtered).forEach((key) => {
     if (hiddenHeaders.test(key)) {