anyformat-mcp 0.1.3

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,182 @@
+// 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.health.check',
+    fullyQualifiedName: 'health.check',
+    httpMethod: 'get',
+    httpPath: '/health/',
+  },
+  {
+    clientCallName: 'client.webhooks.create',
+    fullyQualifiedName: 'webhooks.create',
+    httpMethod: 'post',
+    httpPath: '/v2/webhooks/',
+  },
+  {
+    clientCallName: 'client.webhooks.list',
+    fullyQualifiedName: 'webhooks.list',
+    httpMethod: 'get',
+    httpPath: '/v2/webhooks/',
+  },
+  {
+    clientCallName: 'client.webhooks.delete',
+    fullyQualifiedName: 'webhooks.delete',
+    httpMethod: 'delete',
+    httpPath: '/v2/webhooks/{webhook_id}/',
+  },
+  {
+    clientCallName: 'client.files.create',
+    fullyQualifiedName: 'files.create',
+    httpMethod: 'post',
+    httpPath: '/v2/files/',
+  },
+  {
+    clientCallName: 'client.files.list',
+    fullyQualifiedName: 'files.list',
+    httpMethod: 'get',
+    httpPath: '/v2/files/',
+  },
+  {
+    clientCallName: 'client.files.delete',
+    fullyQualifiedName: 'files.delete',
+    httpMethod: 'delete',
+    httpPath: '/v2/files/{collection_id}/',
+  },
+  {
+    clientCallName: 'client.files.getExtractionResults',
+    fullyQualifiedName: 'files.getExtractionResults',
+    httpMethod: 'get',
+    httpPath: '/v2/files/{collection_id}/extraction/',
+  },
+  {
+    clientCallName: 'client.workflows.create',
+    fullyQualifiedName: 'workflows.create',
+    httpMethod: 'post',
+    httpPath: '/v2/workflows/',
+  },
+  {
+    clientCallName: 'client.workflows.retrieve',
+    fullyQualifiedName: 'workflows.retrieve',
+    httpMethod: 'get',
+    httpPath: '/v2/workflows/{workflow_id}/',
+  },
+  {
+    clientCallName: 'client.workflows.list',
+    fullyQualifiedName: 'workflows.list',
+    httpMethod: 'get',
+    httpPath: '/v2/workflows/',
+  },
+  {
+    clientCallName: 'client.workflows.delete',
+    fullyQualifiedName: 'workflows.delete',
+    httpMethod: 'delete',
+    httpPath: '/v2/workflows/{workflow_id}/',
+  },
+  {
+    clientCallName: 'client.workflows.listRuns',
+    fullyQualifiedName: 'workflows.listRuns',
+    httpMethod: 'get',
+    httpPath: '/v2/workflows/{workflow_id}/runs/',
+  },
+  {
+    clientCallName: 'client.workflows.results',
+    fullyQualifiedName: 'workflows.results',
+    httpMethod: 'get',
+    httpPath: '/v2/workflows/{workflow_id}/results/',
+  },
+  {
+    clientCallName: 'client.workflows.run',
+    fullyQualifiedName: 'workflows.run',
+    httpMethod: 'post',
+    httpPath: '/v2/workflows/{workflow_id}/run/',
+  },
+  {
+    clientCallName: 'client.workflows.upload',
+    fullyQualifiedName: 'workflows.upload',
+    httpMethod: 'post',
+    httpPath: '/v2/workflows/{workflow_id}/upload/',
+  },
+];
+
+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,185 @@
+// 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;
+  docsSearchMode?: 'stainless-api' | 'local' | undefined;
+  docsDir?: string | undefined;
+  codeAllowHttpGets?: boolean | undefined;
+  codeAllowedMethods?: string[] | undefined;
+  codeBlockedMethods?: string[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+  customInstructionsPath?: string | undefined;
+};
+
+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('custom-instructions-path', {
+      type: 'string',
+      description: 'Path to custom instructions for the MCP server',
+    })
+    .option('debug', { type: 'boolean', description: 'Enable debug logging' })
+    .option('docs-dir', {
+      type: 'string',
+      description:
+        'Path to a directory of local documentation files (markdown/JSON) to include in local docs search.',
+    })
+    .option('docs-search-mode', {
+      type: 'string',
+      choices: ['stainless-api', 'local'],
+      default: 'stainless-api',
+      description:
+        "Where to search documentation; 'stainless-api' uses the Stainless-hosted search API whereas 'local' uses an in-memory search index built from embedded SDK method data and optional local docs files.",
+    })
+    .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,
+    docsSearchMode: argv.docsSearchMode as 'stainless-api' | 'local' | undefined,
+    docsDir: argv.docsDir,
+    codeAllowHttpGets: argv.codeAllowHttpGets,
+    codeAllowedMethods: argv.codeAllowedMethods,
+    codeBlockedMethods: argv.codeBlockedMethods,
+    codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode,
+    customInstructionsPath: argv.customInstructionsPath,
+    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,
+    docsSearchMode: defaultOptions.docsSearchMode,
+    docsDir: defaultOptions.docsDir,
+  };
+}

package/src/server.ts

@@ -0,0 +1,208 @@
+// 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 'anyformat-ai';
+import Anyformat from 'anyformat-ai';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { setLocalSearch } from './docs-search-tool';
+import { LocalDocsSearch } from './local-docs-search';
+import { getInstructions } from './instructions';
+import { McpOptions } from './options';
+import { blockedMethodsForCodeTool } from './methods';
+import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types';
+
+export const newMcpServer = async ({
+  stainlessApiKey,
+  customInstructionsPath,
+}: {
+  stainlessApiKey?: string | undefined;
+  customInstructionsPath?: string | undefined;
+}) =>
+  new McpServer(
+    {
+      name: 'anyformat_ai_api',
+      version: '0.1.3',
+    },
+    {
+      instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),
+      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;
+  upstreamClientEnvs?: Record<string, string> | undefined;
+  mcpSessionId?: string | undefined;
+  mcpClientInfo?: { name: string; version: 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'),
+  };
+
+  if (params.mcpOptions?.docsSearchMode === 'local') {
+    const docsDir = params.mcpOptions?.docsDir;
+    const localSearch = await LocalDocsSearch.create(docsDir ? { docsDir } : undefined);
+    setLocalSearch(localSearch);
+  }
+
+  let _client: Anyformat | undefined;
+  let _clientError: Error | undefined;
+  let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined;
+
+  const getClient = (): Anyformat => {
+    if (_clientError) throw _clientError;
+    if (!_client) {
+      try {
+        _client = new Anyformat({
+          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: Anyformat;
+    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,
+        upstreamClientEnvs: params.upstreamClientEnvs,
+        mcpSessionId: params.mcpSessionId,
+        mcpClientInfo: params.mcpClientInfo,
+      },
+      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,17 @@
+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({
+    stainlessApiKey: mcpOptions.stainlessApiKey,
+    customInstructionsPath: mcpOptions.customInstructionsPath,
+  });
+
+  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"
+  }
+}