context.dev-mcp 0.1.0

package/src/docs-search-tool.ts

@@ -0,0 +1,100 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Metadata, McpRequestContext, asTextContentResult } from './types';
+import { getLogger } from './logger';
+
+export const metadata: Metadata = {
+  resource: 'all',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+};
+
+export const tool: Tool = {
+  name: 'search_docs',
+  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: {
+      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/context.dev/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 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: ${errorText}`,
+    );
+  }
+
+  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

@@ -0,0 +1,173 @@
+// 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 'context.dev';
+import express from 'express';
+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';
+
+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);
+
+  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
+    }
+  }
+
+  await initMcpServer({
+    server: server,
+    mcpOptions: mcpOptions,
+    clientOptions: {
+      ...clientOptions,
+      ...authOptions,
+    },
+    stainlessApiKey: stainlessApiKey,
+    upstreamClientEnvs,
+  });
+
+  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',
+    },
+  });
+};
+
+const redactHeaders = (headers: Record<string, any>) => {
+  const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i;
+  const filtered = { ...headers };
+  Object.keys(filtered).forEach((key) => {
+    if (hiddenHeaders.test(key)) {
+      filtered[key] = '[REDACTED]';
+    }
+  });
+  return filtered;
+};
+
+export const streamableHTTPApp = ({
+  clientOptions = {},
+  mcpOptions,
+}: {
+  clientOptions?: ClientOptions;
+  mcpOptions: McpOptions;
+}): express.Express => {
+  const app = express();
+  app.set('query parser', 'extended');
+  app.use(express.json());
+  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');
+  });
+  app.get('/', get);
+  app.post('/', post({ clientOptions, mcpOptions }));
+  app.delete('/', del);
+
+  return app;
+};
+
+export const launchStreamableHTTPServer = async ({
+  mcpOptions,
+  port,
+}: {
+  mcpOptions: McpOptions;
+  port: number | string | undefined;
+}) => {
+  const app = streamableHTTPApp({ mcpOptions });
+  const server = app.listen(port);
+  const address = server.address();
+
+  const logger = getLogger();
+
+  if (typeof address === 'string') {
+    logger.info(`MCP Server running on streamable HTTP at ${address}`);
+  } else if (address !== null) {
+    logger.info(`MCP Server running on streamable HTTP on port ${address.port}`);
+  } else {
+    logger.info(`MCP Server running on streamable HTTP on port ${port}`);
+  }
+};

package/src/index.ts

@@ -0,0 +1,67 @@
+#!/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';
+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);
+
+  getLogger().info(
+    { tools: selectedTools.map((e) => e.tool.name) },
+    `MCP Server starting with ${selectedTools.length} tools`,
+  );
+
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer(options);
+      break;
+    case 'http':
+      await launchStreamableHTTPServer({
+        mcpOptions: options,
+        port: options.socket ?? options.port,
+      });
+      break;
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    // Logger might not be initialized yet
+    console.error('Fatal error in main()', error);
+    process.exit(1);
+  });
+}
+
+function parseOptionsOrError() {
+  try {
+    return parseCLIOptions();
+  } catch (error) {
+    // Logger is initialized after options, so use console.error here
+    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) {
+      getLogger().error('No tools match the provided filters');
+      process.exit(1);
+    }
+    return includedTools;
+  } catch (error) {
+    getLogger().error({ error }, 'Error filtering tools');
+    process.exit(1);
+  }
+}

package/src/instructions.ts

@@ -0,0 +1,60 @@
+// 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
+
+interface InstructionsCacheEntry {
+  fetchedInstructions: string;
+  fetchedAt: number;
+}
+
+const instructionsCache = new Map<string, InstructionsCacheEntry>();
+
+export async function getInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  const now = Date.now();
+  const cacheKey = stainlessApiKey ?? '';
+  const cached = instructionsCache.get(cacheKey);
+
+  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: 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/context.dev',
+    {
+      method: 'GET',
+      headers: { ...(stainlessApiKey && { Authorization: stainlessApiKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    getLogger().warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions =
+      '\n  This is the context.dev 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;
+
+  return instructions;
+}

package/src/logger.ts

@@ -0,0 +1,28 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { pino, type Level, type Logger } from 'pino';
+import pretty from 'pino-pretty';
+
+let _logger: Logger | undefined;
+
+export function configureLogger({ level, pretty: usePretty }: { level: Level; pretty: boolean }): void {
+  _logger = pino(
+    {
+      level,
+      timestamp: pino.stdTimeFunctions.isoTime,
+      formatters: {
+        level(label) {
+          return { level: label };
+        },
+      },
+    },
+    usePretty ? pretty({ colorize: true, levelFirst: true, destination: 2 }) : process.stderr,
+  );
+}
+
+export function getLogger(): Logger {
+  if (!_logger) {
+    throw new Error('Logger has not been configured. Call configureLogger() before using the logger.');
+  }
+  return _logger;
+}

package/src/methods.ts

@@ -0,0 +1,206 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpOptions } from './options';
+
+export type SdkMethod = {
+  clientCallName: string;
+  fullyQualifiedName: string;
+  httpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'query';
+  httpPath?: string;
+};
+
+export const sdkMethods: SdkMethod[] = [
+  {
+    clientCallName: 'client.brand.retrieve',
+    fullyQualifiedName: 'brand.retrieve',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve',
+  },
+  {
+    clientCallName: 'client.brand.aiProduct',
+    fullyQualifiedName: 'brand.aiProduct',
+    httpMethod: 'post',
+    httpPath: '/brand/ai/product',
+  },
+  {
+    clientCallName: 'client.brand.aiProducts',
+    fullyQualifiedName: 'brand.aiProducts',
+    httpMethod: 'post',
+    httpPath: '/brand/ai/products',
+  },
+  {
+    clientCallName: 'client.brand.aiQuery',
+    fullyQualifiedName: 'brand.aiQuery',
+    httpMethod: 'post',
+    httpPath: '/brand/ai/query',
+  },
+  {
+    clientCallName: 'client.brand.fonts',
+    fullyQualifiedName: 'brand.fonts',
+    httpMethod: 'get',
+    httpPath: '/brand/fonts',
+  },
+  {
+    clientCallName: 'client.brand.identifyFromTransaction',
+    fullyQualifiedName: 'brand.identifyFromTransaction',
+    httpMethod: 'get',
+    httpPath: '/brand/transaction_identifier',
+  },
+  {
+    clientCallName: 'client.brand.prefetch',
+    fullyQualifiedName: 'brand.prefetch',
+    httpMethod: 'post',
+    httpPath: '/brand/prefetch',
+  },
+  {
+    clientCallName: 'client.brand.prefetchByEmail',
+    fullyQualifiedName: 'brand.prefetchByEmail',
+    httpMethod: 'post',
+    httpPath: '/brand/prefetch-by-email',
+  },
+  {
+    clientCallName: 'client.brand.retrieveByEmail',
+    fullyQualifiedName: 'brand.retrieveByEmail',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve-by-email',
+  },
+  {
+    clientCallName: 'client.brand.retrieveByIsin',
+    fullyQualifiedName: 'brand.retrieveByIsin',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve-by-isin',
+  },
+  {
+    clientCallName: 'client.brand.retrieveByName',
+    fullyQualifiedName: 'brand.retrieveByName',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve-by-name',
+  },
+  {
+    clientCallName: 'client.brand.retrieveByTicker',
+    fullyQualifiedName: 'brand.retrieveByTicker',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve-by-ticker',
+  },
+  {
+    clientCallName: 'client.brand.retrieveNaics',
+    fullyQualifiedName: 'brand.retrieveNaics',
+    httpMethod: 'get',
+    httpPath: '/brand/naics',
+  },
+  {
+    clientCallName: 'client.brand.retrieveSimplified',
+    fullyQualifiedName: 'brand.retrieveSimplified',
+    httpMethod: 'get',
+    httpPath: '/brand/retrieve-simplified',
+  },
+  {
+    clientCallName: 'client.brand.screenshot',
+    fullyQualifiedName: 'brand.screenshot',
+    httpMethod: 'get',
+    httpPath: '/brand/screenshot',
+  },
+  {
+    clientCallName: 'client.brand.styleguide',
+    fullyQualifiedName: 'brand.styleguide',
+    httpMethod: 'get',
+    httpPath: '/brand/styleguide',
+  },
+  {
+    clientCallName: 'client.brand.webScrapeHTML',
+    fullyQualifiedName: 'brand.webScrapeHTML',
+    httpMethod: 'get',
+    httpPath: '/web/scrape/html',
+  },
+  {
+    clientCallName: 'client.brand.webScrapeImages',
+    fullyQualifiedName: 'brand.webScrapeImages',
+    httpMethod: 'get',
+    httpPath: '/web/scrape/images',
+  },
+  {
+    clientCallName: 'client.brand.webScrapeMd',
+    fullyQualifiedName: 'brand.webScrapeMd',
+    httpMethod: 'get',
+    httpPath: '/web/scrape/markdown',
+  },
+  {
+    clientCallName: 'client.brand.webScrapeSitemap',
+    fullyQualifiedName: 'brand.webScrapeSitemap',
+    httpMethod: 'get',
+    httpPath: '/web/scrape/sitemap',
+  },
+];
+
+function allowedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined {
+  if (!options) {
+    return undefined;
+  }
+
+  let allowedMethods: SdkMethod[];
+
+  if (options.codeAllowHttpGets || options.codeAllowedMethods) {
+    // Start with nothing allowed and then add into it from options
+    let allowedMethodsSet = new Set<SdkMethod>();
+
+    if (options.codeAllowHttpGets) {
+      // Add all methods that map to an HTTP GET
+      sdkMethods
+        .filter((method) => method.httpMethod === 'get')
+        .forEach((method) => allowedMethodsSet.add(method));
+    }
+
+    if (options.codeAllowedMethods) {
+      // Add all methods that match any of the allowed regexps
+      const allowedRegexps = options.codeAllowedMethods.map((pattern) => {
+        try {
+          return new RegExp(pattern);
+        } catch (e) {
+          throw new Error(
+            `Invalid regex pattern for allowed method: "${pattern}": ${e instanceof Error ? e.message : e}`,
+          );
+        }
+      });
+
+      sdkMethods
+        .filter((method) => allowedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)))
+        .forEach((method) => allowedMethodsSet.add(method));
+    }
+
+    allowedMethods = Array.from(allowedMethodsSet);
+  } else {
+    // Start with everything allowed
+    allowedMethods = [...sdkMethods];
+  }
+
+  if (options.codeBlockedMethods) {
+    // Filter down based on blocked regexps
+    const blockedRegexps = options.codeBlockedMethods.map((pattern) => {
+      try {
+        return new RegExp(pattern);
+      } catch (e) {
+        throw new Error(
+          `Invalid regex pattern for blocked method: "${pattern}": ${e instanceof Error ? e.message : e}`,
+        );
+      }
+    });
+
+    allowedMethods = allowedMethods.filter(
+      (method) => !blockedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)),
+    );
+  }
+
+  return allowedMethods;
+}
+
+export function blockedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined {
+  const allowedMethods = allowedMethodsForCodeTool(options);
+  if (!allowedMethods) {
+    return undefined;
+  }
+
+  const allowedSet = new Set(allowedMethods.map((method) => method.fullyQualifiedName));
+
+  // Return any methods that are not explicitly allowed
+  return sdkMethods.filter((method) => !allowedSet.has(method.fullyQualifiedName));
+}