@spec2tools/stdio-mcp 0.1.1 → 0.2.0

package/README.md

@@ -12,6 +12,22 @@ pnpm add @spec2tools/stdio-mcp
 
 ## Quick Start
 
+### With Claude Code
+
+```bash
+# Add as an MCP server
+claude mcp add stdio my-api \
+  -- npx @spec2tools/stdio-mcp ./path/to/openapi.yaml
+
+# With authentication
+claude mcp add --env API_KEY=your-api-key my-api \
+  -- npx @spec2tools/stdio-mcp ./openapi.yaml
+
+# With code mode (2 tools: search + execute)
+claude mcp add my-api \
+  -- npx @spec2tools/stdio-mcp ./openapi.yaml --code-mode
+```
+
 ### With Claude Desktop
 
 Add to your `claude_desktop_config.json`:
@@ -40,22 +56,6 @@ For authenticated APIs:
 }
 ```
 
-Or using environment variables:
-
-```json
-{
-  "mcpServers": {
-    "my-api": {
-      "command": "npx",
-      "args": ["@spec2tools/stdio-mcp", "./openapi.yaml"],
-      "env": {
-        "API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
 ### CLI Usage
 
 ```bash
@@ -72,6 +72,36 @@ spec2tools-mcp ./api.yaml --api-key your-api-key
 API_KEY=your-api-key spec2tools-mcp ./api.yaml
 ```
 
+### Remote MCP Server
+
+Proxy an existing remote MCP server through stdio. This lets you connect any HTTP or SSE-based MCP server to clients that only support stdio transport (like Claude Desktop), and optionally apply code mode to reduce token usage.
+
+```bash
+# Proxy via Streamable HTTP
+spec2tools-mcp --http https://example.com/mcp
+
+# Proxy via SSE
+spec2tools-mcp --sse https://example.com/sse
+
+# Proxy with code mode
+spec2tools-mcp --sse https://example.com/sse --code-mode
+```
+
+With Claude Code:
+
+```bash
+claude mcp add my-remote-api \
+  -- npx @spec2tools/stdio-mcp --sse https://example.com/sse --code-mode
+```
+
+### Code Mode
+
+Code mode collapses all API endpoints into 2 tools (`search` + `execute`), reducing token usage by ~99.9%. The model discovers endpoints via keyword search and calls them by writing Python code in a sandboxed interpreter.
+
+```bash
+spec2tools-mcp ./openapi.yaml --code-mode
+```
+
 ### Programmatic Usage
 
 ```typescript
@@ -93,6 +123,9 @@ await startMcpServer({
 | `--name <name>` | Server name for MCP (default: `openapi-mcp-server`) |
 | `--version <ver>` | Server version for MCP (default: `1.0.0`) |
 | `--api-key <key>` | API key or bearer token for authentication |
+| `--http <url>` | Connect to a remote MCP server (Streamable HTTP) |
+| `--sse <url>` | Connect to a remote MCP server (SSE transport) |
+| `--code-mode` | Use code mode (2 tools: search + execute) |
 | `-h, --help` | Show help message |
 
 ## Environment Variables

package/dist/index.js

@@ -17,8 +17,8 @@ async function main() {
         process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
     }
     const options = parseArgs(args);
-    if (!options.spec) {
-        console.error('Error: OpenAPI spec path is required');
+    if (!options.spec && !options.httpUrl && !options.sseUrl) {
+        console.error('Error: OpenAPI spec path or remote MCP URL (--http / --sse) is required');
         printUsage();
         process.exit(1);
     }
@@ -43,6 +43,15 @@ function parseArgs(args) {
         else if (arg === '--api-key' && args[i + 1]) {
             options.apiKey = args[++i];
         }
+        else if (arg === '--code-mode') {
+            options.codeMode = true;
+        }
+        else if (arg === '--http' && args[i + 1]) {
+            options.httpUrl = args[++i];
+        }
+        else if (arg === '--sse' && args[i + 1]) {
+            options.sseUrl = args[++i];
+        }
         else if (!arg.startsWith('-')) {
             options.spec = arg;
         }
@@ -55,14 +64,19 @@ function printUsage() {
 
 Usage:
   spec2tools-mcp <spec-path> [options]
+  spec2tools-mcp --http <url> [options]
+  spec2tools-mcp --sse <url> [options]
 
 Arguments:
   spec-path           Path or URL to OpenAPI specification (JSON or YAML)
 
 Options:
+  --http <url>        Connect to a remote MCP server (Streamable HTTP)
+  --sse <url>         Connect to a remote MCP server (SSE transport)
   --name <name>       Server name for MCP (default: openapi-mcp-server)
   --version <ver>     Server version for MCP (default: 1.0.0)
   --api-key <key>     API key or token for authentication
+  --code-mode         Use code mode (2 tools: search + execute)
   -h, --help          Show this help message
 
 Environment Variables:
@@ -78,6 +92,13 @@ Examples:
   # Start with authentication
   API_KEY=xxx spec2tools-mcp ./api.yaml
 
+  # Proxy a remote MCP server via stdio
+  spec2tools-mcp --http https://example.com/mcp
+  spec2tools-mcp --sse https://example.com/sse
+
+  # Proxy with code mode (collapse all tools into search + execute)
+  spec2tools-mcp --sse https://example.com/sse --code-mode
+
   # Configure in Claude Desktop (claude_desktop_config.json):
   {
     "mcpServers": {

package/dist/server.d.ts

@@ -7,6 +7,12 @@ export interface McpServerOptions {
     version?: string;
     /** API key or token for authentication */
     apiKey?: string;
+    /** Use code mode (2 tools: search + execute) */
+    codeMode?: boolean;
+    /** URL of a remote MCP server (Streamable HTTP transport) */
+    httpUrl?: string;
+    /** URL of a remote MCP server (SSE transport) */
+    sseUrl?: string;
 }
 /**
  * Create and start an MCP server that exposes OpenAPI operations as tools.

package/dist/server.js

@@ -2,7 +2,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, AuthManager, createExecutableTools, } from '@spec2tools/core';
+import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, AuthManager, createExecutableTools, toAISDKTools, toCodeModeTools, } from '@spec2tools/core';
+import { createMCPClient } from '@ai-sdk/mcp';
 /**
  * Create and start an MCP server that exposes OpenAPI operations as tools.
  *
@@ -17,41 +18,80 @@ import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, Au
  * ```
  */
 export async function startMcpServer(options) {
-    const { spec: specPath, name = 'openapi-mcp-server', version = '0.1.0' } = options;
-    // Load and parse OpenAPI spec
-    const spec = await loadOpenAPISpec(specPath);
-    const baseUrl = extractBaseUrl(spec);
-    const authConfig = extractAuthConfig(spec);
-    // Set up auth manager
-    const authManager = new AuthManager(authConfig);
-    configureAuth(authManager, authConfig, options);
-    // Parse operations into tool definitions and create executable tools
-    const toolDefs = parseOperations(spec);
-    const tools = createExecutableTools(toolDefs, baseUrl, authManager);
+    const { name = 'openapi-mcp-server', version = '0.1.0' } = options;
+    let tools;
+    let mcpClient;
+    if (options.httpUrl || options.sseUrl) {
+        // Remote MCP proxy mode: connect to an existing MCP server
+        const transport = options.httpUrl
+            ? { type: 'http', url: options.httpUrl, headers: { Authorization: `Bearer ${options.apiKey || ''}` } }
+            : { type: 'sse', url: options.sseUrl, headers: { Authorization: `Bearer ${options.apiKey || ''}` } };
+        mcpClient = await createMCPClient({ transport });
+        tools = await mcpClient.tools();
+        if (options.codeMode) {
+            tools = toCodeModeTools(tools);
+        }
+    }
+    else {
+        // OpenAPI spec mode: load spec and create tools
+        const spec = await loadOpenAPISpec(options.spec);
+        const baseUrl = extractBaseUrl(spec);
+        const authConfig = extractAuthConfig(spec);
+        const authManager = new AuthManager(authConfig);
+        configureAuth(authManager, authConfig, options);
+        const toolDefs = parseOperations(spec);
+        const coreTools = createExecutableTools(toolDefs, baseUrl, authManager);
+        tools = toAISDKTools(coreTools);
+        if (options.codeMode) {
+            tools = toCodeModeTools(tools);
+        }
+    }
     // Create MCP server
     const server = new Server({ name, version }, { capabilities: { tools: { listChanged: false } } });
     // Register tool listing handler
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return {
-            tools: tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                inputSchema: zodToJsonSchema(tool.parameters, { target: 'jsonSchema7' }),
-            })),
+            tools: Object.entries(tools).map(([toolName, t]) => {
+                const description = 'description' in t ? t.description || '' : '';
+                const schema = ('inputSchema' in t ? t.inputSchema : undefined) ??
+                    ('parameters' in t ? t.parameters : undefined);
+                let inputSchema = { type: 'object', properties: {} };
+                if (schema && typeof schema === 'object') {
+                    const schemaObj = schema;
+                    if ('jsonSchema' in schemaObj && schemaObj.jsonSchema) {
+                        inputSchema = schemaObj.jsonSchema;
+                    }
+                    else if ('_def' in schemaObj) {
+                        inputSchema = zodToJsonSchema(schema, { target: 'jsonSchema7' });
+                    }
+                }
+                return {
+                    name: toolName,
+                    description,
+                    inputSchema,
+                };
+            }),
         };
     });
     // Register tool execution handler
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name: toolName, arguments: args } = request.params;
-        const tool = tools.find((t) => t.name === toolName);
-        if (!tool) {
+        const toolEntry = tools[toolName];
+        if (!toolEntry) {
             return {
                 content: [{ type: 'text', text: `Error: Unknown tool "${toolName}"` }],
                 isError: true,
             };
         }
         try {
-            const result = await tool.execute(args ?? {});
+            const execute = 'execute' in toolEntry ? toolEntry.execute : undefined;
+            if (!execute) {
+                return {
+                    content: [{ type: 'text', text: `Error: Tool "${toolName}" has no execute function` }],
+                    isError: true,
+                };
+            }
+            const result = await execute(args ?? {}, {});
             const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
             return {
                 content: [{ type: 'text', text: resultText }],
@@ -61,7 +101,6 @@ export async function startMcpServer(options) {
             let errorMessage;
             if (error instanceof Error) {
                 errorMessage = error.message;
-                // Include stack trace for debugging if available
                 if (error.stack) {
                     errorMessage += `\n\nStack trace:\n${error.stack}`;
                 }
@@ -75,6 +114,14 @@ export async function startMcpServer(options) {
             };
         }
     });
+    // Clean up remote MCP client on process exit
+    if (mcpClient) {
+        const cleanup = async () => {
+            await mcpClient.close();
+        };
+        process.on('SIGINT', () => { cleanup().then(() => process.exit(0)); });
+        process.on('SIGTERM', () => { cleanup().then(() => process.exit(0)); });
+    }
     // Start stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -82,7 +129,7 @@ export async function startMcpServer(options) {
 /**
  * Configure authentication from options or environment variables
  */
-function configureAuth(authManager, authConfig, options) {
+function configureAuth(authManager, _authConfig, options) {
     // Check for explicit option first, then fall back to environment variable
     const apiKey = options.apiKey || process.env.API_KEY;
     // Set the API key if provided, regardless of auth type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/stdio-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server that exposes OpenAPI endpoints as tools via stdio transport",
   "type": "module",
   "main": "dist/index.js",
@@ -34,10 +34,12 @@
     "directory": "packages/stdio-mcp"
   },
   "dependencies": {
+    "@ai-sdk/mcp": "^1.0.21",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "ai": "^6.0.68",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.24.0",
-    "@spec2tools/core": "0.1.2"
+    "@spec2tools/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",