@revoxai/sdk-mcp 0.1.0

package/src/instructions.ts

@@ -0,0 +1,65 @@
+// 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>();
+
+// 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/revox',
+    {
+      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 revox 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,164 @@
+// 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.assistants.create',
+    fullyQualifiedName: 'assistants.create',
+    httpMethod: 'post',
+    httpPath: '/assistants',
+  },
+  {
+    clientCallName: 'client.assistants.retrieve',
+    fullyQualifiedName: 'assistants.retrieve',
+    httpMethod: 'get',
+    httpPath: '/assistants/{id}',
+  },
+  {
+    clientCallName: 'client.assistants.update',
+    fullyQualifiedName: 'assistants.update',
+    httpMethod: 'patch',
+    httpPath: '/assistants/{id}',
+  },
+  {
+    clientCallName: 'client.assistants.list',
+    fullyQualifiedName: 'assistants.list',
+    httpMethod: 'get',
+    httpPath: '/assistants',
+  },
+  {
+    clientCallName: 'client.assistants.delete',
+    fullyQualifiedName: 'assistants.delete',
+    httpMethod: 'delete',
+    httpPath: '/assistants/{id}',
+  },
+  {
+    clientCallName: 'client.call.create',
+    fullyQualifiedName: 'call.create',
+    httpMethod: 'post',
+    httpPath: '/call',
+  },
+  {
+    clientCallName: 'client.call.retrieve',
+    fullyQualifiedName: 'call.retrieve',
+    httpMethod: 'get',
+    httpPath: '/call/{id}',
+  },
+  {
+    clientCallName: 'client.call.list',
+    fullyQualifiedName: 'call.list',
+    httpMethod: 'get',
+    httpPath: '/call',
+  },
+  {
+    clientCallName: 'client.voices.retrieve',
+    fullyQualifiedName: 'voices.retrieve',
+    httpMethod: 'get',
+    httpPath: '/voices/{id}',
+  },
+  {
+    clientCallName: 'client.voices.list',
+    fullyQualifiedName: 'voices.list',
+    httpMethod: 'get',
+    httpPath: '/voices',
+  },
+  {
+    clientCallName: 'client.voices.preview',
+    fullyQualifiedName: 'voices.preview',
+    httpMethod: 'post',
+    httpPath: '/voices/preview',
+  },
+  {
+    clientCallName: 'client.users.me.retrieve',
+    fullyQualifiedName: 'users.me.retrieve',
+    httpMethod: 'get',
+    httpPath: '/users/me',
+  },
+  {
+    clientCallName: 'client.users.me.update',
+    fullyQualifiedName: 'users.me.update',
+    httpMethod: 'patch',
+    httpPath: '/users/me',
+  },
+];
+
+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));
+}

package/src/options.ts

@@ -0,0 +1,161 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import qs from 'qs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import z from 'zod';
+import { readEnv } from './util';
+
+export type CLIOptions = McpOptions & {
+  debug: boolean;
+  logFormat: 'json' | 'pretty';
+  transport: 'stdio' | 'http';
+  port: number | undefined;
+  socket: string | undefined;
+};
+
+export type McpOptions = {
+  includeCodeTool?: boolean | undefined;
+  includeDocsTools?: boolean | undefined;
+  stainlessApiKey?: string | undefined;
+  codeAllowHttpGets?: boolean | undefined;
+  codeAllowedMethods?: string[] | undefined;
+  codeBlockedMethods?: string[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+};
+
+export type McpCodeExecutionMode = 'stainless-sandbox' | 'local';
+
+export function parseCLIOptions(): CLIOptions {
+  const opts = yargs(hideBin(process.argv))
+    .option('code-allow-http-gets', {
+      type: 'boolean',
+      description:
+        'Allow all code tool methods that map to HTTP GET operations. If all code-allow-* flags are unset, then everything is allowed.',
+    })
+    .option('code-allowed-methods', {
+      type: 'string',
+      array: true,
+      description:
+        'Methods to explicitly allow for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.',
+    })
+    .option('code-blocked-methods', {
+      type: 'string',
+      array: true,
+      description:
+        'Methods to explicitly block for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.',
+    })
+    .option('code-execution-mode', {
+      type: 'string',
+      choices: ['stainless-sandbox', 'local'],
+      default: 'stainless-sandbox',
+      description:
+        "Where to run code execution in code tool; 'stainless-sandbox' will execute code in Stainless-hosted sandboxes whereas 'local' will execute code locally on the MCP server machine.",
+    })
+    .option('debug', { type: 'boolean', description: 'Enable debug logging' })
+    .option('log-format', {
+      type: 'string',
+      choices: ['json', 'pretty'],
+      description: 'Format for log output; defaults to json unless tty is detected',
+    })
+    .option('no-tools', {
+      type: 'string',
+      array: true,
+      choices: ['code', 'docs'],
+      description: 'Tools to explicitly disable',
+    })
+    .option('port', {
+      type: 'number',
+      default: 3000,
+      description: 'Port to serve on if using http transport',
+    })
+    .option('socket', { type: 'string', description: 'Unix socket to serve on if using http transport' })
+    .option('stainless-api-key', {
+      type: 'string',
+      default: readEnv('STAINLESS_API_KEY'),
+      description:
+        'API key for Stainless. Used to authenticate requests to Stainless-hosted tools endpoints.',
+    })
+    .option('tools', {
+      type: 'string',
+      array: true,
+      choices: ['code', 'docs'],
+      description: 'Tools to explicitly enable',
+    })
+    .option('transport', {
+      type: 'string',
+      choices: ['stdio', 'http'],
+      default: 'stdio',
+      description: 'What transport to use; stdio for local servers or http for remote servers',
+    })
+    .env('MCP_SERVER')
+    .version(true)
+    .help();
+
+  const argv = opts.parseSync();
+
+  const shouldIncludeToolType = (toolType: 'code' | 'docs') =>
+    argv.noTools?.includes(toolType) ? false
+    : argv.tools?.includes(toolType) ? true
+    : undefined;
+
+  const includeCodeTool = shouldIncludeToolType('code');
+  const includeDocsTools = shouldIncludeToolType('docs');
+
+  const transport = argv.transport as 'stdio' | 'http';
+  const logFormat =
+    argv.logFormat ? (argv.logFormat as 'json' | 'pretty')
+    : process.stderr.isTTY ? 'pretty'
+    : 'json';
+
+  return {
+    ...(includeCodeTool !== undefined && { includeCodeTool }),
+    ...(includeDocsTools !== undefined && { includeDocsTools }),
+    debug: !!argv.debug,
+    stainlessApiKey: argv.stainlessApiKey,
+    codeAllowHttpGets: argv.codeAllowHttpGets,
+    codeAllowedMethods: argv.codeAllowedMethods,
+    codeBlockedMethods: argv.codeBlockedMethods,
+    codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode,
+    transport,
+    logFormat,
+    port: argv.port,
+    socket: argv.socket,
+  };
+}
+
+const coerceArray = <T extends z.ZodTypeAny>(zodType: T) =>
+  z.preprocess(
+    (val) =>
+      Array.isArray(val) ? val
+      : val ? [val]
+      : val,
+    z.array(zodType).optional(),
+  );
+
+const QueryOptions = z.object({
+  tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to use'),
+  no_tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to not use.'),
+  tool: coerceArray(z.string()).describe('Include tools matching the specified names'),
+});
+
+export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): McpOptions {
+  const queryObject = typeof query === 'string' ? qs.parse(query) : query;
+  const queryOptions = QueryOptions.parse(queryObject);
+
+  let codeTool: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('code') ? false
+    : queryOptions.tools?.includes('code') ? true
+    : defaultOptions.includeCodeTool;
+
+  let docsTools: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false
+    : queryOptions.tools?.includes('docs') ? true
+    : defaultOptions.includeDocsTools;
+
+  return {
+    ...(codeTool !== undefined && { includeCodeTool: codeTool }),
+    ...(docsTools !== undefined && { includeDocsTools: docsTools }),
+    codeExecutionMode: defaultOptions.codeExecutionMode,
+  };
+}

package/src/server.ts

@@ -0,0 +1,188 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  SetLevelRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from '@revoxai/sdk';
+import Revox from '@revoxai/sdk';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { getInstructions } from './instructions';
+import { McpOptions } from './options';
+import { blockedMethodsForCodeTool } from './methods';
+import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types';
+
+export const newMcpServer = async (stainlessApiKey: string | undefined) =>
+  new McpServer(
+    {
+      name: 'revoxai_sdk_api',
+      version: '0.1.0',
+    },
+    {
+      instructions: await getInstructions(stainlessApiKey),
+      capabilities: { tools: {}, logging: {} },
+    },
+  );
+
+/**
+ * Initializes the provided MCP Server with the given tools and handlers.
+ * If not provided, the default client, tools and handlers will be used.
+ */
+export async function initMcpServer(params: {
+  server: Server | McpServer;
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+  stainlessApiKey?: string | undefined;
+}) {
+  const server = params.server instanceof McpServer ? params.server.server : params.server;
+
+  const logAtLevel =
+    (level: 'debug' | 'info' | 'warning' | 'error') =>
+    (message: string, ...rest: unknown[]) => {
+      void server.sendLoggingMessage({
+        level,
+        data: { message, rest },
+      });
+    };
+  const logger = {
+    debug: logAtLevel('debug'),
+    info: logAtLevel('info'),
+    warn: logAtLevel('warning'),
+    error: logAtLevel('error'),
+  };
+
+  let _client: Revox | undefined;
+  let _clientError: Error | undefined;
+  let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined;
+
+  const getClient = (): Revox => {
+    if (_clientError) throw _clientError;
+    if (!_client) {
+      try {
+        _client = new Revox({
+          logger,
+          ...params.clientOptions,
+          defaultHeaders: {
+            ...params.clientOptions?.defaultHeaders,
+            'X-Stainless-MCP': 'true',
+          },
+        });
+        if (_logLevel) {
+          _client = _client.withOptions({ logLevel: _logLevel });
+        }
+      } catch (e) {
+        _clientError = e instanceof Error ? e : new Error(String(e));
+        throw _clientError;
+      }
+    }
+    return _client;
+  };
+
+  const providedTools = selectTools(params.mcpOptions);
+  const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool]));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: providedTools.map((mcpTool) => mcpTool.tool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const mcpTool = toolMap[name];
+    if (!mcpTool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    let client: Revox;
+    try {
+      client = getClient();
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Failed to initialize client: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    return executeHandler({
+      handler: mcpTool.handler,
+      reqContext: {
+        client,
+        stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey,
+      },
+      args,
+    });
+  });
+
+  server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const { level } = request.params;
+    let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off';
+    switch (level) {
+      case 'debug':
+        logLevel = 'debug';
+        break;
+      case 'info':
+        logLevel = 'info';
+        break;
+      case 'notice':
+      case 'warning':
+        logLevel = 'warn';
+        break;
+      case 'error':
+        logLevel = 'error';
+        break;
+      default:
+        logLevel = 'off';
+        break;
+    }
+    _logLevel = logLevel;
+    if (_client) {
+      _client = _client.withOptions({ logLevel });
+    }
+    return {};
+  });
+}
+
+/**
+ * Selects the tools to include in the MCP Server based on the provided options.
+ */
+export function selectTools(options?: McpOptions): McpTool[] {
+  const includedTools = [];
+
+  if (options?.includeCodeTool ?? true) {
+    includedTools.push(
+      codeTool({
+        blockedMethods: blockedMethodsForCodeTool(options),
+        codeExecutionMode: options?.codeExecutionMode ?? 'stainless-sandbox',
+      }),
+    );
+  }
+  if (options?.includeDocsTools ?? true) {
+    includedTools.push(docsSearchTool);
+  }
+  return includedTools;
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler({
+  handler,
+  reqContext,
+  args,
+}: {
+  handler: HandlerFunction;
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}): Promise<ToolCallResult> {
+  return await handler({ reqContext, args: args || {} });
+}

package/src/stdio.ts

@@ -0,0 +1,14 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpOptions } from './options';
+import { initMcpServer, newMcpServer } from './server';
+import { getLogger } from './logger';
+
+export const launchStdioServer = async (mcpOptions: McpOptions) => {
+  const server = await newMcpServer(mcpOptions.stainlessApiKey);
+
+  await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  getLogger().info('MCP Server running on stdio');
+};

package/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // this config is included in the published src directory to prevent TS errors
+  // from appearing when users go to source, and VSCode opens the source .ts file
+  // via declaration maps
+  "include": ["index.ts"],
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["DOM"],
+    "moduleResolution": "node"
+  }
+}