@stigg/typescript-mcp 0.1.0-alpha.10

package/src/code-tool.ts

@@ -0,0 +1,357 @@
+// 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,
+  ToolCallResult,
+  asErrorResult,
+  asTextContentResult,
+} from './types';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { readEnv, requireValue } from './util';
+import { WorkerInput, WorkerOutput } from './code-tool-types';
+import { SdkMethod } from './methods';
+import { McpCodeExecutionMode } from './options';
+import { ClientOptions } from '@stigg/typescript';
+
+const prompt = `Runs JavaScript code to interact with the Stigg API.
+
+You are a skilled 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:
+
+\`\`\`
+async function run(client) {
+  const customerResponse = await client.v1.customers.retrieve('REPLACE_ME');
+
+  console.log(customerResponse.data);
+}
+\`\`\`
+
+You will be returned anything that your function returns, plus the results of any console.log statements.
+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.`;
+
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * 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 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,
+  codeExecutionMode,
+}: {
+  blockedMethods: SdkMethod[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+}): McpTool {
+  const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
+  const tool: Tool = {
+    name: 'execute',
+    description: prompt,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: {
+          type: 'string',
+          description: 'Code to execute.',
+        },
+        intent: {
+          type: 'string',
+          description: 'Task you are trying to perform. Used for improving the service.',
+        },
+      },
+      required: ['code'],
+    },
+  };
+
+  const handler = async ({
+    reqContext,
+    args,
+  }: {
+    reqContext: McpRequestContext;
+    args: any;
+  }): Promise<ToolCallResult> => {
+    const code = args.code as string;
+    // Do very basic blocking of code that includes forbidden method names.
+    //
+    // WARNING: This is not secure against obfuscation and other evasion methods. If
+    // stronger security blocks are required, then these should be enforced in the downstream
+    // API (e.g., by having users call the MCP server with API keys with limited permissions).
+    if (blockedMethods) {
+      const blockedMatches = blockedMethods.filter((method) => code.includes(method.fullyQualifiedName));
+      if (blockedMatches.length > 0) {
+        return asErrorResult(
+          `The following methods have been blocked by the MCP server and cannot be used in code execution: ${blockedMatches
+            .map((m) => m.fullyQualifiedName)
+            .join(', ')}`,
+        );
+      }
+    }
+
+    if (codeExecutionMode === 'local') {
+      return await localDenoHandler({ reqContext, args });
+    } else {
+      return await remoteStainlessHandler({ reqContext, args });
+    }
+  };
+
+  return { metadata, tool, handler };
+}
+
+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',
+      client_envs: JSON.stringify({
+        STIGG_API_KEY: requireValue(
+          readEnv('STIGG_API_KEY') ?? client.apiKey,
+          'set STIGG_API_KEY environment variable or provide apiKey client option',
+        ),
+        STIGG_BASE_URL: readEnv('STIGG_BASE_URL') ?? client.baseURL ?? undefined,
+      }),
+    },
+    body: JSON.stringify({
+      project_name: 'stigg',
+      code,
+      intent,
+      client_opts: {},
+    } satisfies WorkerInput),
+  });
+
+  if (!res.ok) {
+    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 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 = '@stigg/typescript';
+    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

@@ -0,0 +1,68 @@
+// 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';
+
+export const metadata: Metadata = {
+  resource: 'all',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+};
+
+export const tool: Tool = {
+  name: 'search_docs',
+  description: 'Search for documentation for how to use the client to interact with the API.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The query to search for.',
+      },
+      language: {
+        type: 'string',
+        description: 'The language for the SDK to search for.',
+        enum: ['http', 'python', 'go', 'typescript', 'javascript', 'terraform', 'ruby', 'java', 'kotlin'],
+      },
+      detail: {
+        type: 'string',
+        description: 'The amount of detail to return.',
+        enum: ['default', 'verbose'],
+      },
+    },
+    required: ['query', 'language'],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+const docsSearchURL =
+  process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/stigg/docs/search';
+
+export const handler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => {
+  const body = args as any;
+  const query = new URLSearchParams(body).toString();
+  const result = await fetch(`${docsSearchURL}?${query}`, {
+    headers: {
+      ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
+    },
+  });
+
+  if (!result.ok) {
+    throw new Error(
+      `${result.status}: ${result.statusText} when using doc search tool. Details: ${await result.text()}`,
+    );
+  }
+
+  return asTextContentResult(await result.json());
+};
+
+export default { metadata, tool, handler };

package/src/http.ts

@@ -0,0 +1,127 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { ClientOptions } from '@stigg/typescript';
+import express from 'express';
+import morgan from 'morgan';
+import morganBody from 'morgan-body';
+import { getStainlessApiKey, parseClientAuthHeaders } from './auth';
+import { McpOptions } from './options';
+import { initMcpServer, newMcpServer } from './server';
+
+const newServer = async ({
+  clientOptions,
+  mcpOptions,
+  req,
+  res,
+}: {
+  clientOptions: ClientOptions;
+  mcpOptions: McpOptions;
+  req: express.Request;
+  res: express.Response;
+}): Promise<McpServer | null> => {
+  const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
+  const server = await newMcpServer(stainlessApiKey);
+
+  const authOptions = parseClientAuthHeaders(req, false);
+
+  await initMcpServer({
+    server: server,
+    mcpOptions: mcpOptions,
+    clientOptions: {
+      ...clientOptions,
+      ...authOptions,
+    },
+    stainlessApiKey: stainlessApiKey,
+  });
+
+  return server;
+};
+
+const post =
+  (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
+  async (req: express.Request, res: express.Response) => {
+    const server = await newServer({ ...options, req, res });
+    // If we return null, we already set the authorization error.
+    if (server === null) return;
+    const transport = new StreamableHTTPServerTransport();
+    await server.connect(transport as any);
+    await transport.handleRequest(req, res, req.body);
+  };
+
+const get = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+const del = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+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.get('/health', async (req: express.Request, res: express.Response) => {
+    res.status(200).send('OK');
+  });
+  app.get('/', get);
+  app.post('/', post({ clientOptions, mcpOptions }));
+  app.delete('/', del);
+
+  return app;
+};
+
+export const launchStreamableHTTPServer = async ({
+  mcpOptions,
+  debug,
+  port,
+}: {
+  mcpOptions: McpOptions;
+  debug: boolean;
+  port: number | string | undefined;
+}) => {
+  const app = streamableHTTPApp({ mcpOptions, debug });
+  const server = app.listen(port);
+  const address = server.address();
+
+  if (typeof address === 'string') {
+    console.error(`MCP Server running on streamable HTTP at ${address}`);
+  } else if (address !== null) {
+    console.error(`MCP Server running on streamable HTTP on port ${address.port}`);
+  } else {
+    console.error(`MCP Server running on streamable HTTP on port ${port}`);
+  }
+};

package/src/index.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { selectTools } from './server';
+import { McpOptions, parseCLIOptions } from './options';
+import { launchStdioServer } from './stdio';
+import { launchStreamableHTTPServer } from './http';
+import type { McpTool } from './types';
+
+async function main() {
+  const options = parseOptionsOrError();
+
+  const selectedTools = await selectToolsOrError(options);
+
+  console.error(
+    `MCP Server starting with ${selectedTools.length} tools:`,
+    selectedTools.map((e) => e.tool.name),
+  );
+
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer(options);
+      break;
+    case 'http':
+      await launchStreamableHTTPServer({
+        mcpOptions: options,
+        debug: options.debug,
+        port: options.socket ?? options.port,
+      });
+      break;
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+  });
+}
+
+function parseOptionsOrError() {
+  try {
+    return parseCLIOptions();
+  } catch (error) {
+    console.error('Error parsing options:', error);
+    process.exit(1);
+  }
+}
+
+async function selectToolsOrError(options: McpOptions): Promise<McpTool[]> {
+  try {
+    const includedTools = selectTools(options);
+    if (includedTools.length === 0) {
+      console.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);
+    }
+    process.exit(1);
+  }
+}

package/src/instructions.ts

@@ -0,0 +1,74 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { readEnv } from './util';
+
+const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+interface InstructionsCacheEntry {
+  fetchedInstructions: string;
+  fetchedAt: number;
+}
+
+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 cacheKey = stainlessApiKey ?? '';
+  const cached = instructionsCache.get(cacheKey);
+
+  if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
+    return cached.fetchedInstructions;
+  }
+
+  const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+  return fetchedInstructions;
+}
+
+async function fetchLatestInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  // Setting the stainless API key is optional, but may be required
+  // to authenticate requests to the Stainless API.
+  const response = await fetch(
+    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/stigg',
+    {
+      method: 'GET',
+      headers: { ...(stainlessApiKey && { Authorization: stainlessApiKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    console.warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions = `
+      This is the stigg 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 ??= ((await response.json()) as { instructions: string }).instructions;
+  instructions = `
+    If needed, you can get the current time by executing Date.now().
+
+    ${instructions}
+  `;
+
+  return instructions;
+}