chore(mcp): provides high-level initMcpServer function and exports known clients

Author: stainless-app[bot]

packages/mcp-server/package.json

@@ -28,10 +28,10 @@
   },
   "dependencies": {
     "scan-documents": "file:../../dist/",
-    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.11.5",
     "yargs": "^17.7.2",
     "@cloudflare/cabidela": "^0.2.4",
-    "zod": "^3.24.4",
+    "zod": "^3.25.20",
     "zod-to-json-schema": "^3.24.5"
   },
   "bin": {

packages/mcp-server/src/compat.ts

@@ -19,6 +19,46 @@ export const defaultClientCapabilities: ClientCapabilities = {
   toolNameLength: undefined,
 };
 
+export type ClientType = 'openai-agents' | 'claude' | 'claude-code' | 'cursor';
+
+// Client presets for compatibility
+// Note that these could change over time as models get better, so this is
+// a best effort.
+export const knownClients: Record<ClientType, ClientCapabilities> = {
+  'openai-agents': {
+    topLevelUnions: false,
+    validJson: true,
+    refs: true,
+    unions: true,
+    formats: true,
+    toolNameLength: undefined,
+  },
+  claude: {
+    topLevelUnions: true,
+    validJson: false,
+    refs: true,
+    unions: true,
+    formats: true,
+    toolNameLength: undefined,
+  },
+  'claude-code': {
+    topLevelUnions: false,
+    validJson: true,
+    refs: true,
+    unions: true,
+    formats: true,
+    toolNameLength: undefined,
+  },
+  cursor: {
+    topLevelUnions: false,
+    validJson: true,
+    refs: false,
+    unions: false,
+    formats: false,
+    toolNameLength: 50,
+  },
+};
+
 /**
  * Attempts to parse strings into JSON objects
  */

packages/mcp-server/src/index.ts

@@ -1,7 +1,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { init, selectTools, server } from './server';
 import { Endpoint, endpoints } from './tools';
-import { ParsedOptions, parseOptions } from './options';
+import { McpOptions, parseOptions } from './options';
 
 async function main() {
   const options = parseOptionsOrError();
@@ -41,7 +41,7 @@ function parseOptionsOrError() {
   }
 }
 
-function selectToolsOrError(endpoints: Endpoint[], options: ParsedOptions) {
+function selectToolsOrError(endpoints: Endpoint[], options: McpOptions) {
   try {
     const includedTools = selectTools(endpoints, options);
     if (includedTools.length === 0) {

packages/mcp-server/src/options.ts

@@ -1,55 +1,19 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { endpoints, Filter } from './tools';
-import { ClientCapabilities } from './compat';
+import { ClientCapabilities, knownClients, ClientType } from './compat';
 
-type ClientType = 'openai-agents' | 'claude' | 'claude-code' | 'cursor';
-
-// Client presets for compatibility
-// Note that these could change over time as models get better, so this is
-// a best effort.
-const CLIENT_PRESETS: Record<ClientType, ClientCapabilities> = {
-  'openai-agents': {
-    topLevelUnions: false,
-    validJson: true,
-    refs: true,
-    unions: true,
-    formats: true,
-    toolNameLength: undefined,
-  },
-  claude: {
-    topLevelUnions: true,
-    validJson: false,
-    refs: true,
-    unions: true,
-    formats: true,
-    toolNameLength: undefined,
-  },
-  'claude-code': {
-    topLevelUnions: false,
-    validJson: true,
-    refs: true,
-    unions: true,
-    formats: true,
-    toolNameLength: undefined,
-  },
-  cursor: {
-    topLevelUnions: false,
-    validJson: true,
-    refs: false,
-    unions: false,
-    formats: false,
-    toolNameLength: 50,
-  },
+export type CLIOptions = McpOptions & {
+  list: boolean;
 };
 
-export interface ParsedOptions {
+export type McpOptions = {
+  client: ClientType | undefined;
   includeDynamicTools: boolean | undefined;
   includeAllTools: boolean | undefined;
   filters: Filter[];
-  capabilities: ClientCapabilities;
-  list: boolean;
-}
+  capabilities?: Partial<ClientCapabilities>;
+};
 
 const CAPABILITY_CHOICES = [
   'top-level-unions',
@@ -80,7 +44,7 @@ function parseCapabilityValue(cap: string): { name: Capability; value?: number }
   return { name: cap as Capability };
 }
 
-export function parseOptions(): ParsedOptions {
+export function parseOptions(): CLIOptions {
   const opts = yargs(hideBin(process.argv))
     .option('tools', {
       type: 'string',
@@ -141,7 +105,7 @@ export function parseOptions(): ParsedOptions {
     })
     .option('client', {
       type: 'string',
-      choices: Object.keys(CLIENT_PRESETS),
+      choices: Object.keys(knownClients),
       description: 'Specify the MCP client being used',
     })
     .option('capability', {
@@ -229,14 +193,6 @@ export function parseOptions(): ParsedOptions {
     toolNameLength: undefined,
   };
 
-  // Apply client preset if specified
-  if (typeof argv.client === 'string') {
-    const clientKey = argv.client as ClientType;
-    if (CLIENT_PRESETS[clientKey]) {
-      Object.assign(clientCapabilities, CLIENT_PRESETS[clientKey]);
-    }
-  }
-
   // Apply individual capability overrides
   if (Array.isArray(argv.capability)) {
     for (const cap of argv.capability) {
@@ -282,7 +238,9 @@ export function parseOptions(): ParsedOptions {
   const includeAllTools =
     explicitTools ? argv.tools?.includes('all') && !argv.noTools?.includes('all') : undefined;
 
+  const client = argv.client as ClientType;
   return {
+    client: client && knownClients[client] ? client : undefined,
     includeDynamicTools,
     includeAllTools,
     filters,
@@ -323,7 +281,7 @@ Client Presets (--client):
 Presets like '--client=openai-agents' or '--client=cursor' automatically configure these capabilities based on current known limitations of those clients, simplifying setup.
 
 Current presets:
-${JSON.stringify(CLIENT_PRESETS, null, 2)}
+${JSON.stringify(knownClients, null, 2)}
   `;
 }
 

packages/mcp-server/src/server.ts

@@ -4,15 +4,22 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Endpoint, endpoints, HandlerFunction, query } from './tools';
 import { CallToolRequestSchema, ListToolsRequestSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from 'scan-documents';
 import ScanDocuments from 'scan-documents';
 import {
   applyCompatibilityTransformations,
   ClientCapabilities,
   defaultClientCapabilities,
+  knownClients,
   parseEmbeddedJSON,
 } from './compat';
 import { dynamicTools } from './dynamic-tools';
-import { ParsedOptions } from './options';
+import { McpOptions } from './options';
+
+export { McpOptions } from './options';
+export { ClientType } from './compat';
+export { Filter } from './tools';
+export { ClientOptions } from 'scan-documents';
 export { endpoints } from './tools';
 
 // Create server instance
@@ -32,6 +39,21 @@ export const server = new McpServer(
  * Initializes the provided MCP Server with the given tools and handlers.
  * If not provided, the default client, tools and handlers will be used.
  */
+export function initMcpServer(params: {
+  server: Server | McpServer;
+  clientOptions: ClientOptions;
+  mcpOptions: McpOptions;
+  endpoints?: { tool: Tool; handler: HandlerFunction }[];
+}) {
+  const transformedEndpoints = selectTools(endpoints, params.mcpOptions);
+  const client = new ScanDocuments(params.clientOptions);
+  const capabilities = {
+    ...defaultClientCapabilities,
+    ...(params.mcpOptions.client ? knownClients[params.mcpOptions.client] : params.mcpOptions.capabilities),
+  };
+  init({ server: params.server, client, endpoints: transformedEndpoints, capabilities });
+}
+
 export function init(params: {
   server: Server | McpServer;
   client?: ScanDocuments;
@@ -65,24 +87,27 @@ export function init(params: {
 /**
  * Selects the tools to include in the MCP Server based on the provided options.
  */
-export function selectTools(endpoints: Endpoint[], options: ParsedOptions) {
+export function selectTools(endpoints: Endpoint[], options: McpOptions) {
   const filteredEndpoints = query(options.filters, endpoints);
 
-  const includedTools = filteredEndpoints;
+  let includedTools = filteredEndpoints;
 
-  if (options.includeAllTools && includedTools.length === 0) {
-    includedTools.push(...endpoints);
-  }
-
-  if (options.includeDynamicTools) {
-    includedTools.push(...dynamicTools(endpoints));
-  }
-
-  if (includedTools.length === 0) {
-    includedTools.push(...endpoints);
+  if (includedTools.length > 0) {
+    if (options.includeDynamicTools) {
+      includedTools = dynamicTools(includedTools);
+    }
+  } else {
+    if (options.includeAllTools) {
+      includedTools = endpoints;
+    } else if (options.includeDynamicTools) {
+      includedTools = dynamicTools(endpoints);
+    } else {
+      includedTools = endpoints;
+    }
   }
 
-  return applyCompatibilityTransformations(includedTools, options.capabilities);
+  const capabilities = { ...defaultClientCapabilities, ...options.capabilities };
+  return applyCompatibilityTransformations(includedTools, capabilities);
 }
 
 /**

packages/mcp-server/src/tools/index.ts

@@ -70,9 +70,10 @@ export function query(filters: Filter[], endpoints: Endpoint[]): Endpoint[] {
   });
 
   // Check if any filters didn't match
-  if (unmatchedFilters.size > 0) {
+  const unmatched = Array.from(unmatchedFilters).filter((f) => f.type === 'tool' || f.type === 'resource');
+  if (unmatched.length > 0) {
     throw new Error(
-      `The following filters did not match any endpoints: ${[...unmatchedFilters]
+      `The following filters did not match any endpoints: ${unmatched
         .map((f) => `${f.type}=${f.value}`)
         .join(', ')}`,
     );

packages/mcp-server/src/tools/types.ts

@@ -91,7 +91,6 @@ export type Metadata = {
   resource: string;
   operation: 'read' | 'write';
   tags: string[];
-
   httpMethod?: string;
   httpPath?: string;
   operationId?: string;

packages/mcp-server/tests/options.test.ts

@@ -77,14 +77,7 @@ describe('parseOptions', () => {
 
     const result = parseOptions();
 
-    expect(result.capabilities).toEqual({
-      topLevelUnions: false,
-      validJson: true,
-      refs: true,
-      unions: true,
-      formats: true,
-      toolNameLength: undefined,
-    });
+    expect(result.client).toEqual('openai-agents');
 
     cleanup();
   });