release: 0.1.0-alpha.31

.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/**'

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.30"
+  ".": "0.1.0-alpha.31"
 }

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.0-alpha.31 (2026-03-17)
+
+Full Changelog: [v0.1.0-alpha.30...v0.1.0-alpha.31](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.30...v0.1.0-alpha.31)
+
+### Chores
+
+* **internal:** bump @modelcontextprotocol/sdk, @hono/node-server, and minimatch ([d5b63e3](https://github.com/Scan-Documents/node-sdk/commit/d5b63e36a5c6bc96d2c485834a09050b7ce61555))
+* **internal:** make generated MCP servers compatible with Cloudflare worker environments ([663e939](https://github.com/Scan-Documents/node-sdk/commit/663e9399aea38becc113376f195b81c46d268b08))
+* **internal:** support x-stainless-mcp-client-envs header in MCP servers ([c5d6196](https://github.com/Scan-Documents/node-sdk/commit/c5d619641e44fd5f14e43aa230d05697342433bd))
+* **internal:** support x-stainless-mcp-client-permissions headers in MCP servers ([8d8479b](https://github.com/Scan-Documents/node-sdk/commit/8d8479b6ba016c97e8ddbb9f25e0947fffdb79de))
+* **internal:** tweak CI branches ([73c3ed7](https://github.com/Scan-Documents/node-sdk/commit/73c3ed73bf25819de55cdbd8c0e327802ac596f4))
+* **internal:** update dependencies to address dependabot vulnerabilities ([03a21da](https://github.com/Scan-Documents/node-sdk/commit/03a21da5bf6c12e562a3f27580e244eb01d4d250))
+* **mcp-server:** improve instructions ([042e4c4](https://github.com/Scan-Documents/node-sdk/commit/042e4c4326c5ad56033fea22d82c1b85a2aefe5e))
+
 ## 0.1.0-alpha.30 (2026-03-08)
 
 Full Changelog: [v0.1.0-alpha.29...v0.1.0-alpha.30](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.29...v0.1.0-alpha.30)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scan-documents",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "The official TypeScript library for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
@@ -50,6 +50,17 @@
     "typescript": "5.8.3",
     "typescript-eslint": "8.31.1"
   },
+  "overrides": {
+    "minimatch": "^9.0.5"
+  },
+  "pnpm": {
+    "overrides": {
+      "minimatch": "^9.0.5"
+    }
+  },
+  "resolutions": {
+    "minimatch": "^9.0.5"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.mjs",

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "scan-documents-mcp",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "The official MCP Server for the Scan Documents API",
   "author": {
     "name": "Scan Documents",

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scan-documents-mcp",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "The official MCP Server for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
@@ -26,13 +26,16 @@
     "format": "prettier --write --cache --cache-strategy metadata . !dist",
     "prepare": "npm run build",
     "tsn": "ts-node -r tsconfig-paths/register",
-    "lint": "eslint --ext ts,js .",
-    "fix": "eslint --fix --ext ts,js ."
+    "lint": "eslint .",
+    "fix": "eslint --fix ."
   },
   "dependencies": {
     "scan-documents": "file:../../dist/",
+    "ajv": "^8.18.0",
     "@cloudflare/cabidela": "^0.2.4",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@hono/node-server": "^1.19.10",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "hono": "^4.12.4",
     "@valtown/deno-http-worker": "^0.0.21",
     "cookie-parser": "^1.4.6",
     "cors": "^2.8.5",
@@ -62,9 +65,9 @@
     "@types/yargs": "^17.0.8",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
-    "eslint": "^8.49.0",
-    "eslint-plugin-prettier": "^5.0.1",
-    "eslint-plugin-unused-imports": "^3.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-prettier": "^5.4.1",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "jest": "^29.4.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.1.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,
@@ -147,19 +142,23 @@ const remoteStainlessHandler = async ({
 
   const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
 
+  const localClientEnvs = {
+    SCAN_DOCUMENTS_API_KEY: requireValue(
+      readEnv('SCAN_DOCUMENTS_API_KEY') ?? client.apiKey,
+      'set SCAN_DOCUMENTS_API_KEY environment variable or provide apiKey client option',
+    ),
+    SCAN_DOCUMENTS_BASE_URL: readEnv('SCAN_DOCUMENTS_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({
-        SCAN_DOCUMENTS_API_KEY: requireValue(
-          readEnv('SCAN_DOCUMENTS_API_KEY') ?? client.apiKey,
-          'set SCAN_DOCUMENTS_API_KEY environment variable or provide apiKey client option',
-        ),
-        SCAN_DOCUMENTS_BASE_URL: readEnv('SCAN_DOCUMENTS_BASE_URL') ?? client.baseURL ?? undefined,
-      }),
+      'x-stainless-mcp-client-envs': JSON.stringify(mergedClientEnvs),
     },
     body: JSON.stringify({
       project_name: 'scan-documents',
@@ -202,6 +201,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 };
@@ -263,6 +269,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 },
     },
   });
 
@@ -272,13 +281,17 @@ const localDenoHandler = async ({
         reject(new Error(`Worker exited with code ${exitCode}`));
       });
 
-      const opts: ClientOptions = {
-        baseURL: client.baseURL,
-        apiKey: client.apiKey,
-        defaultHeaders: {
-          'X-Stainless-MCP': 'true',
-        },
-      };
+      // Strip null/undefined values so that the worker SDK client can fall back to
+      // reading from environment variables (including any upstreamClientEnvs).
+      const opts: ClientOptions = Object.fromEntries(
+        Object.entries({
+          baseURL: client.baseURL,
+          apiKey: client.apiKey,
+          defaultHeaders: {
+            'X-Stainless-MCP': 'true',
+          },
+        }).filter(([_, v]) => v != null),
+      ) as ClientOptions;
 
       const req = worker.request(
         'http://localhost',

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

@@ -13,7 +13,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'search_docs',
-  description: 'Search for documentation for how to use the client to interact with the API.',
+  description:
+    'Search SDK documentation to find methods, parameters, and usage examples for interacting with the API. Use this before writing code when you need to discover the right approach.',
   inputSchema: {
     type: 'object',
     properties: {

packages/mcp-server/src/http.ts

@@ -27,14 +27,56 @@ const newServer = async ({
 
   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 +114,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)) {

packages/mcp-server/src/instructions.ts

@@ -12,29 +12,24 @@ interface InstructionsCacheEntry {
 
 const instructionsCache = new Map<string, InstructionsCacheEntry>();
 
-// Periodically evict stale entries so the cache doesn't grow unboundedly.
-const _cacheCleanupInterval = setInterval(() => {
-  const now = Date.now();
-  for (const [key, entry] of instructionsCache) {
-    if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) {
-      instructionsCache.delete(key);
-    }
-  }
-}, INSTRUCTIONS_CACHE_TTL_MS);
-
-// Don't keep the process alive just for cleanup.
-_cacheCleanupInterval.unref();
-
 export async function getInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  const now = Date.now();
   const cacheKey = stainlessApiKey ?? '';
   const cached = instructionsCache.get(cacheKey);
 
-  if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
+  if (cached && now - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
     return cached.fetchedInstructions;
   }
 
+  // Evict stale entries so the cache doesn't grow unboundedly.
+  for (const [key, entry] of instructionsCache) {
+    if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) {
+      instructionsCache.delete(key);
+    }
+  }
+
   const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
-  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now });
   return fetchedInstructions;
 }
 
@@ -55,21 +50,11 @@ async function fetchLatestInstructions(stainlessApiKey: string | undefined): Pro
       'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
     );
 
-    instructions = `
-      This is the scan-documents MCP server. You will use Code Mode to help the user perform
-      actions. You can use search_docs tool to learn about how to take action with this server. Then,
-      you will write TypeScript code using the execute tool take action. It is CRITICAL that you be
-      thoughtful and deliberate when executing code. Always try to entirely solve the problem in code
-      block: it can be as long as you need to get the job done!
-    `;
+    instructions =
+      '\n  This is the scan-documents MCP server.\n\n  Available tools:\n  - search_docs: Search SDK documentation to find the right methods and parameters.\n  - execute: Run TypeScript code against a pre-authenticated SDK client. Define an async run(client) function.\n\n  Workflow:\n  - If unsure about the API, call search_docs first.\n  - Write complete solutions in a single execute call when possible. For large datasets, use API filters to narrow results or paginate within a single execute block.\n  - If execute returns an error, read the error and fix your code rather than retrying the same approach.\n  - Variables do not persist between execute calls. Return or log all data you need.\n  - Individual HTTP requests to the API have a 30-second timeout. If a request times out, try a smaller query or add filters.\n  - Code execution has a total timeout of approximately 5 minutes. If your code times out, simplify it or break it into smaller steps.\n  ';
   }
 
   instructions ??= ((await response.json()) as { instructions: string }).instructions;
-  instructions = `
-    If needed, you can get the current time by executing Date.now().
-
-    ${instructions}
-  `;
 
   return instructions;
 }

packages/mcp-server/src/server.ts

@@ -20,7 +20,7 @@ export const newMcpServer = async (stainlessApiKey: string | undefined) =>
   new McpServer(
     {
       name: 'scan_documents_api',
-      version: '0.1.0-alpha.30',
+      version: '0.1.0-alpha.31',
     },
     {
       instructions: await getInstructions(stainlessApiKey),
@@ -37,6 +37,7 @@ export async function initMcpServer(params: {
   clientOptions?: ClientOptions;
   mcpOptions?: McpOptions;
   stainlessApiKey?: string | undefined;
+  upstreamClientEnvs?: Record<string, string> | undefined;
 }) {
   const server = params.server instanceof McpServer ? params.server.server : params.server;
 
@@ -118,6 +119,7 @@ export async function initMcpServer(params: {
       reqContext: {
         client,
         stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey,
+        upstreamClientEnvs: params.upstreamClientEnvs,
       },
       args,
     });

packages/mcp-server/src/types.ts

@@ -45,6 +45,7 @@ export type ToolCallResult = {
 export type McpRequestContext = {
   client: ScanDocuments;
   stainlessApiKey?: string | undefined;
+  upstreamClientEnvs?: Record<string, string> | undefined;
 };
 
 export type HandlerFunction = ({