cas-parser-node-mcp 1.9.0 → 1.10.1

package/src/code-tool.ts

@@ -1,6 +1,12 @@
 // 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,
   McpTool,
   Metadata,
@@ -11,11 +17,14 @@ import {
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { readEnv, requireValue } from './util';
 import { WorkerInput, WorkerOutput } from './code-tool-types';
+import { getLogger } from './logger';
 import { SdkMethod } from './methods';
+import { McpCodeExecutionMode } from './options';
+import { ClientOptions } from 'cas-parser-node';
 
 const prompt = `Runs JavaScript code to interact with the Cas Parser API.
 
-You are a skilled programmer writing code to interface with the service.
+You are a skilled TypeScript programmer writing code to interface with the service.
 Define an async function named "run" that takes a single parameter of an initialized SDK client and it will be run.
 For example:
 
@@ -31,7 +40,9 @@ You will be returned anything that your function returns, plus the results of an
 Do not add try-catch blocks for single API calls. The tool will handle errors for you.
 Do not add comments unless necessary for generating better code.
 Code will run in a container, and cannot interact with the network outside of the given SDK client.
-Variables will not persist between calls, so make sure to return or log any data you might need later.`;
+Variables will not persist between calls, so make sure to return or log any data you might need later.
+Remember that you are writing TypeScript code, so you need to be careful with your types.
+Always type dynamic key-value stores explicitly as Record<string, YourValueType> instead of {}.`;
 
 /**
  * A tool that runs code against a copy of the SDK.
@@ -40,9 +51,19 @@ Variables will not persist between calls, so make sure to return or log any data
  * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
  * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
  *
- * @param endpoints - The endpoints to include in the list.
+ * @param blockedMethods - The methods to block for code execution. Blocking is done by simple string
+ * matching, so it is not secure against obfuscation. For stronger security, block in the downstream API
+ * with limited API keys.
+ * @param codeExecutionMode - Whether to execute code in a local Deno environment or in a remote
+ * sandbox environment hosted by Stainless.
  */
-export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | undefined }): McpTool {
+export function codeTool({
+  blockedMethods,
+  codeExecutionMode,
+}: {
+  blockedMethods: SdkMethod[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+}): McpTool {
   const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
   const tool: Tool = {
     name: 'execute',
@@ -62,6 +83,9 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
       required: ['code'],
     },
   };
+
+  const logger = getLogger();
+
   const handler = async ({
     reqContext,
     args,
@@ -70,9 +94,6 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
     args: any;
   }): Promise<ToolCallResult> => {
     const code = args.code as string;
-    const intent = args.intent as string | undefined;
-    const client = reqContext.client;
-
     // Do very basic blocking of code that includes forbidden method names.
     //
     // WARNING: This is not secure against obfuscation and other evasion methods. If
@@ -89,51 +110,274 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
       }
     }
 
-    const codeModeEndpoint =
-      readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
-
-    // 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',
-        client_envs: JSON.stringify({
-          CAS_PARSER_API_KEY: requireValue(
-            readEnv('CAS_PARSER_API_KEY') ?? client.apiKey,
-            'set CAS_PARSER_API_KEY environment variable or provide apiKey client option',
-          ),
-          CAS_PARSER_BASE_URL: readEnv('CAS_PARSER_BASE_URL') ?? client.baseURL ?? undefined,
-        }),
+    let result: ToolCallResult;
+    const startTime = Date.now();
+
+    if (codeExecutionMode === 'local') {
+      logger.debug('Executing code in local Deno environment');
+      result = await localDenoHandler({ reqContext, args });
+    } else {
+      logger.debug('Executing code in remote Stainless environment');
+      result = await remoteStainlessHandler({ reqContext, args });
+    }
+
+    logger.info(
+      {
+        codeExecutionMode,
+        durationMs: Date.now() - startTime,
+        isError: result.isError,
+        contentRows: result.content?.length ?? 0,
       },
-      body: JSON.stringify({
-        project_name: 'cas-parser',
-        code,
-        intent,
-        client_opts: {},
-      } satisfies WorkerInput),
-    });
+      'Got code tool execution result',
+    );
+    return result;
+  };
+
+  return { metadata, tool, handler };
+}
 
-    if (!res.ok) {
+const remoteStainlessHandler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: any;
+}): Promise<ToolCallResult> => {
+  const code = args.code as string;
+  const intent = args.intent as string | undefined;
+  const client = reqContext.client;
+
+  const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
+
+  // 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({
+        CAS_PARSER_API_KEY: requireValue(
+          readEnv('CAS_PARSER_API_KEY') ?? client.apiKey,
+          'set CAS_PARSER_API_KEY environment variable or provide apiKey client option',
+        ),
+        CAS_PARSER_BASE_URL: readEnv('CAS_PARSER_BASE_URL') ?? client.baseURL ?? undefined,
+      }),
+    },
+    body: JSON.stringify({
+      project_name: 'cas-parser',
+      code,
+      intent,
+      client_opts: {},
+    } satisfies WorkerInput),
+  });
+
+  if (!res.ok) {
+    if (res.status === 404 && !reqContext.stainlessApiKey) {
       throw new Error(
-        `${res.status}: ${
-          res.statusText
-        } error when trying to contact Code Tool server. Details: ${await res.text()}`,
+        'Could not access code tool 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.',
       );
     }
+    throw new Error(
+      `${res.status}: ${
+        res.statusText
+      } error when trying to contact Code Tool server. Details: ${await res.text()}`,
+    );
+  }
 
-    const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
-    const hasLogs = log_lines.length > 0 || err_lines.length > 0;
-    const output = {
-      result,
-      ...(log_lines.length > 0 && { log_lines }),
-      ...(err_lines.length > 0 && { err_lines }),
-    };
-    if (is_error) {
-      return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
-    }
-    return asTextContentResult(output);
+  const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
+  const hasLogs = log_lines.length > 0 || err_lines.length > 0;
+  const output = {
+    result,
+    ...(log_lines.length > 0 && { log_lines }),
+    ...(err_lines.length > 0 && { err_lines }),
   };
+  if (is_error) {
+    return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
+  }
+  return asTextContentResult(output);
+};
 
-  return { metadata, tool, handler };
-}
+const localDenoHandler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: unknown;
+}): Promise<ToolCallResult> => {
+  const client = reqContext.client;
+  const baseURLHostname = new URL(client.baseURL).hostname;
+  const { code } = args as { code: string };
+
+  let denoPath: string;
+
+  const packageRoot = path.resolve(path.dirname(workerPath), '..');
+  const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules');
+
+  // Check if deno is in PATH
+  const { execSync } = await import('node:child_process');
+  try {
+    execSync('command -v deno', { stdio: 'ignore' });
+    denoPath = 'deno';
+  } catch {
+    try {
+      // Use deno binary in node_modules if it's found
+      const denoNodeModulesPath = path.resolve(packageNodeModulesPath, 'deno', 'bin.cjs');
+      await fs.promises.access(denoNodeModulesPath, fs.constants.X_OK);
+      denoPath = denoNodeModulesPath;
+    } catch {
+      return asErrorResult(
+        'Deno is required for code execution but was not found. ' +
+          'Install it from https://deno.land or run: npm install deno',
+      );
+    }
+  }
+
+  const allowReadPaths = [
+    'code-tool-worker.mjs',
+    `${workerPath.replace(/([\/\\]node_modules)[\/\\].+$/, '$1')}/`,
+    packageRoot,
+  ];
+
+  // Follow symlinks in node_modules to allow read access to workspace-linked packages
+  try {
+    const sdkPkgName = 'cas-parser-node';
+    const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName);
+    const realSdkDir = fs.realpathSync(sdkDir);
+    if (realSdkDir !== sdkDir) {
+      allowReadPaths.push(realSdkDir);
+    }
+  } catch {
+    // Ignore if symlink resolution fails
+  }
+
+  const allowRead = allowReadPaths.join(',');
+
+  const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), {
+    denoExecutable: denoPath,
+    runFlags: [
+      `--node-modules-dir=manual`,
+      `--allow-read=${allowRead}`,
+      `--allow-net=${baseURLHostname}`,
+      // Allow environment variables because instantiating the client will try to read from them,
+      // even though they are not set.
+      '--allow-env',
+    ],
+    printOutput: true,
+    spawnOptions: {
+      cwd: path.dirname(workerPath),
+    },
+  });
+
+  try {
+    const resp = await new Promise<Response>((resolve, reject) => {
+      worker.addEventListener('exit', (exitCode) => {
+        reject(new Error(`Worker exited with code ${exitCode}`));
+      });
+
+      const opts: ClientOptions = {
+        baseURL: client.baseURL,
+        apiKey: client.apiKey,
+        defaultHeaders: {
+          'X-Stainless-MCP': 'true',
+        },
+      };
+
+      const req = worker.request(
+        'http://localhost',
+        {
+          headers: {
+            'content-type': 'application/json',
+          },
+          method: 'POST',
+        },
+        (resp) => {
+          const body: Uint8Array[] = [];
+          resp.on('error', (err) => {
+            reject(err);
+          });
+          resp.on('data', (chunk) => {
+            body.push(chunk);
+          });
+          resp.on('end', () => {
+            resolve(
+              new Response(Buffer.concat(body).toString(), {
+                status: resp.statusCode ?? 200,
+                headers: resp.headers as any,
+              }),
+            );
+          });
+        },
+      );
+
+      const body = JSON.stringify({
+        opts,
+        code,
+      });
+
+      req.write(body, (err) => {
+        if (err != null) {
+          reject(err);
+        }
+      });
+
+      req.end();
+    });
+
+    if (resp.status === 200) {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const returnOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [returnOutput, logOutput, errOutput].filter((block) => block !== null),
+      };
+    } else {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const messageOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [messageOutput, logOutput, errOutput].filter((block) => block !== null),
+        isError: true,
+      };
+    }
+  } finally {
+    worker.terminate();
+  }
+};

package/src/docs-search-tool.ts

@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, McpRequestContext, asTextContentResult } from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Metadata, McpRequestContext, asTextContentResult } from './types';
+import { getLogger } from './logger';
 
 export const metadata: Metadata = {
   resource: 'all',
@@ -12,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: {
@@ -50,19 +52,49 @@ export const handler = async ({
 }) => {
   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 }),
     },
   });
 
+  const logger = getLogger();
+
   if (!result.ok) {
+    const errorText = await result.text();
+    logger.warn(
+      {
+        durationMs: Date.now() - startTime,
+        query: body.query,
+        status: result.status,
+        statusText: result.statusText,
+        errorText,
+      },
+      'Got error response from docs search tool',
+    );
+
+    if (result.status === 404 && !reqContext.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.',
+      );
+    }
+
     throw new Error(
-      `${result.status}: ${result.statusText} when using doc search tool. Details: ${await result.text()}`,
+      `${result.status}: ${result.statusText} when using doc search tool. Details: ${errorText}`,
     );
   }
 
-  return asTextContentResult(await result.json());
+  const resultBody = await result.json();
+  logger.info(
+    {
+      durationMs: Date.now() - startTime,
+      query: body.query,
+    },
+    'Got docs search result',
+  );
+  return asTextContentResult(resultBody);
 };
 
 export default { metadata, tool, handler };

package/src/http.ts

@@ -4,9 +4,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { ClientOptions } from 'cas-parser-node';
 import express from 'express';
-import morgan from 'morgan';
-import morganBody from 'morgan-body';
+import pino from 'pino';
+import pinoHttp from 'pino-http';
 import { getStainlessApiKey, parseClientAuthHeaders } from './auth';
+import { getLogger } from './logger';
 import { McpOptions } from './options';
 import { initMcpServer, newMcpServer } from './server';
 
@@ -70,29 +71,60 @@ const del = async (req: express.Request, res: express.Response) => {
   });
 };
 
+const redactHeaders = (headers: Record<string, any>) => {
+  const hiddenHeaders = /auth|cookie|key|token/i;
+  const filtered = { ...headers };
+  Object.keys(filtered).forEach((key) => {
+    if (hiddenHeaders.test(key)) {
+      filtered[key] = '[REDACTED]';
+    }
+  });
+  return filtered;
+};
+
 export const streamableHTTPApp = ({
   clientOptions = {},
   mcpOptions,
-  debug,
 }: {
   clientOptions?: ClientOptions;
   mcpOptions: McpOptions;
-  debug: boolean;
 }): express.Express => {
   const app = express();
   app.set('query parser', 'extended');
   app.use(express.json());
-
-  if (debug) {
-    morganBody(app, {
-      logAllReqHeader: true,
-      logAllResHeader: true,
-      logRequestBody: true,
-      logResponseBody: true,
-    });
-  } else {
-    app.use(morgan('combined'));
-  }
+  app.use(
+    pinoHttp({
+      logger: getLogger(),
+      customLogLevel: (req, res) => {
+        if (res.statusCode >= 500) {
+          return 'error';
+        } else if (res.statusCode >= 400) {
+          return 'warn';
+        }
+        return 'info';
+      },
+      customSuccessMessage: function (req, res) {
+        return `Request ${req.method} to ${req.url} completed with status ${res.statusCode}`;
+      },
+      customErrorMessage: function (req, res, err) {
+        return `Request ${req.method} to ${req.url} errored with status ${res.statusCode}`;
+      },
+      serializers: {
+        req: pino.stdSerializers.wrapRequestSerializer((req) => {
+          return {
+            ...req,
+            headers: redactHeaders(req.raw.headers),
+          };
+        }),
+        res: pino.stdSerializers.wrapResponseSerializer((res) => {
+          return {
+            ...res,
+            headers: redactHeaders(res.headers),
+          };
+        }),
+      },
+    }),
+  );
 
   app.get('/health', async (req: express.Request, res: express.Response) => {
     res.status(200).send('OK');
@@ -106,22 +138,22 @@ export const streamableHTTPApp = ({
 
 export const launchStreamableHTTPServer = async ({
   mcpOptions,
-  debug,
   port,
 }: {
   mcpOptions: McpOptions;
-  debug: boolean;
   port: number | string | undefined;
 }) => {
-  const app = streamableHTTPApp({ mcpOptions, debug });
+  const app = streamableHTTPApp({ mcpOptions });
   const server = app.listen(port);
   const address = server.address();
 
+  const logger = getLogger();
+
   if (typeof address === 'string') {
-    console.error(`MCP Server running on streamable HTTP at ${address}`);
+    logger.info(`MCP Server running on streamable HTTP at ${address}`);
   } else if (address !== null) {
-    console.error(`MCP Server running on streamable HTTP on port ${address.port}`);
+    logger.info(`MCP Server running on streamable HTTP on port ${address.port}`);
   } else {
-    console.error(`MCP Server running on streamable HTTP on port ${port}`);
+    logger.info(`MCP Server running on streamable HTTP on port ${port}`);
   }
 };

package/src/index.ts

@@ -5,15 +5,20 @@ import { McpOptions, parseCLIOptions } from './options';
 import { launchStdioServer } from './stdio';
 import { launchStreamableHTTPServer } from './http';
 import type { McpTool } from './types';
+import { configureLogger, getLogger } from './logger';
 
 async function main() {
   const options = parseOptionsOrError();
+  configureLogger({
+    level: options.debug ? 'debug' : 'info',
+    pretty: options.logFormat === 'pretty',
+  });
 
   const selectedTools = await selectToolsOrError(options);
 
-  console.error(
-    `MCP Server starting with ${selectedTools.length} tools:`,
-    selectedTools.map((e) => e.tool.name),
+  getLogger().info(
+    { tools: selectedTools.map((e) => e.tool.name) },
+    `MCP Server starting with ${selectedTools.length} tools`,
   );
 
   switch (options.transport) {
@@ -23,7 +28,6 @@ async function main() {
     case 'http':
       await launchStreamableHTTPServer({
         mcpOptions: options,
-        debug: options.debug,
         port: options.socket ?? options.port,
       });
       break;
@@ -32,7 +36,8 @@ async function main() {
 
 if (require.main === module) {
   main().catch((error) => {
-    console.error('Fatal error in main():', error);
+    // Logger might not be initialized yet
+    console.error('Fatal error in main()', error);
     process.exit(1);
   });
 }
@@ -41,7 +46,8 @@ function parseOptionsOrError() {
   try {
     return parseCLIOptions();
   } catch (error) {
-    console.error('Error parsing options:', error);
+    // Logger is initialized after options, so use console.error here
+    console.error('Error parsing options', error);
     process.exit(1);
   }
 }
@@ -50,16 +56,12 @@ async function selectToolsOrError(options: McpOptions): Promise<McpTool[]> {
   try {
     const includedTools = selectTools(options);
     if (includedTools.length === 0) {
-      console.error('No tools match the provided filters.');
+      getLogger().error('No tools match the provided filters');
       process.exit(1);
     }
     return includedTools;
   } catch (error) {
-    if (error instanceof Error) {
-      console.error('Error filtering tools:', error.message);
-    } else {
-      console.error('Error filtering tools:', error);
-    }
+    getLogger().error({ error }, 'Error filtering tools');
     process.exit(1);
   }
 }

package/src/instructions.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { readEnv } from './util';
+import { getLogger } from './logger';
 
 const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
 
@@ -50,25 +51,15 @@ async function fetchLatestInstructions(stainlessApiKey: string | undefined): Pro
 
   let instructions: string | undefined;
   if (!response.ok) {
-    console.warn(
+    getLogger().warn(
       'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
     );
 
-    instructions = `
-      This is the cas-parser 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 cas-parser 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;
 }