@spec2tools/stdio-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @spec2tools/stdio-mcp
+
+MCP (Model Context Protocol) server that exposes OpenAPI endpoints as tools via stdio transport. This allows AI agents like Claude to call any API described by an OpenAPI specification.
+
+## Installation
+
+```bash
+npm install @spec2tools/stdio-mcp
+# or
+pnpm add @spec2tools/stdio-mcp
+```
+
+## Quick Start
+
+### With Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": ["@spec2tools/stdio-mcp", "./path/to/openapi.yaml"]
+    }
+  }
+}
+```
+
+For authenticated APIs:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": ["@spec2tools/stdio-mcp", "./openapi.yaml", "--api-key", "your-api-key"]
+    }
+  }
+}
+```
+
+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
+# Start server with local spec
+spec2tools-mcp ./openapi.yaml
+
+# Start server with remote spec
+spec2tools-mcp https://api.example.com/openapi.json
+
+# Start with authentication
+spec2tools-mcp ./api.yaml --api-key your-api-key
+
+# Or use environment variable
+API_KEY=your-api-key spec2tools-mcp ./api.yaml
+```
+
+### Programmatic Usage
+
+```typescript
+import { startMcpServer } from '@spec2tools/stdio-mcp';
+
+await startMcpServer({
+  spec: './openapi.yaml',
+  name: 'my-api-server',
+  version: '1.0.0',
+  apiKey: 'your-api-key', // optional
+});
+```
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `<spec-path>` | Path or URL to OpenAPI specification (JSON or YAML) |
+| `--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 |
+| `-h, --help` | Show help message |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `API_KEY` | API key or bearer token for authentication |
+
+## How It Works
+
+1. **Loads OpenAPI Spec**: Reads your OpenAPI 3.x specification from a local file or URL (supports both JSON and YAML)
+
+2. **Parses Operations**: Converts each API operation into an MCP tool with:
+   - Tool name from `operationId` (or generated from method + path)
+   - Description from `summary` or `description`
+   - Input schema from parameters and request body
+
+3. **Starts MCP Server**: Creates a stdio-based MCP server that AI agents can connect to
+
+4. **Handles Tool Calls**: When an agent calls a tool, the server:
+   - Validates the parameters
+   - Builds the HTTP request (URL, headers, body)
+   - Adds authentication if configured
+   - Executes the request and returns the response
+
+## Supported OpenAPI Features
+
+- **HTTP Methods**: GET, POST, PUT, PATCH, DELETE
+- **Parameters**: Path and query parameters (string, number, boolean, arrays)
+- **Request Bodies**: JSON with primitives and flat objects
+- **Authentication**: Bearer tokens, API keys (header or query)
+
+### Limitations
+
+- Nested objects beyond 1 level deep are not supported
+- Arrays of objects are not supported
+- Schema composition (`anyOf`, `oneOf`, `allOf`) is not supported
+- File uploads are not supported
+- `$ref` schema references are not supported
+
+## Example
+
+Given this OpenAPI spec:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+servers:
+  - url: https://api.example.com
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List all users
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Success
+  /users/{id}:
+    get:
+      operationId: getUser
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Success
+```
+
+The MCP server will expose two tools:
+
+- `listUsers(limit?: number)` - List all users
+- `getUser(id: number)` - Get user by ID
+
+An AI agent can then call these tools naturally:
+
+> "Get me the user with ID 42"
+
+The agent will call `getUser({ id: 42 })` and receive the API response.
+
+## Related Packages
+
+- [`@spec2tools/core`](../core) - Core utilities for OpenAPI parsing
+- [`@spec2tools/cli`](../cli) - Interactive CLI with chat interface
+- [`@spec2tools/sdk`](../sdk) - AI SDK tool generation
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export { startMcpServer, McpServerOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { startMcpServer } from './server.js';
+// Re-export for programmatic use
+export { startMcpServer } from './server.js';
+/**
+ * CLI entry point
+ * Usage: spec2tools-mcp <spec-path> [--name <server-name>] [--version <server-version>]
+ *
+ * Authentication can be provided via:
+ * - Environment variable: API_KEY
+ * - Command line: --api-key <key>
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        printUsage();
+        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');
+        printUsage();
+        process.exit(1);
+    }
+    try {
+        await startMcpServer(options);
+    }
+    catch (error) {
+        console.error('Error starting MCP server:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+function parseArgs(args) {
+    const options = { spec: '' };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--name' && args[i + 1]) {
+            options.name = args[++i];
+        }
+        else if (arg === '--version' && args[i + 1]) {
+            options.version = args[++i];
+        }
+        else if (arg === '--api-key' && args[i + 1]) {
+            options.apiKey = args[++i];
+        }
+        else if (!arg.startsWith('-')) {
+            options.spec = arg;
+        }
+    }
+    return options;
+}
+function printUsage() {
+    console.log(`
+@spec2tools/stdio-mcp - MCP server exposing OpenAPI endpoints as tools
+
+Usage:
+  spec2tools-mcp <spec-path> [options]
+
+Arguments:
+  spec-path           Path or URL to OpenAPI specification (JSON or YAML)
+
+Options:
+  --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
+  -h, --help          Show this help message
+
+Environment Variables:
+  API_KEY             API key or token for authentication
+
+Examples:
+  # Start server with local spec
+  spec2tools-mcp ./openapi.yaml
+
+  # Start server with remote spec
+  spec2tools-mcp https://api.example.com/openapi.json
+
+  # Start with authentication
+  API_KEY=xxx spec2tools-mcp ./api.yaml
+
+  # Configure in Claude Desktop (claude_desktop_config.json):
+  {
+    "mcpServers": {
+      "my-api": {
+        "command": "npx",
+        "args": ["@spec2tools/stdio-mcp", "./openapi.yaml"]
+      }
+    }
+  }
+`);
+}
+// Run CLI if this is the entry point
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+export interface McpServerOptions {
+    /** Path or URL to OpenAPI specification */
+    spec: string;
+    /** Server name for MCP */
+    name?: string;
+    /** Server version for MCP */
+    version?: string;
+    /** API key or token for authentication */
+    apiKey?: string;
+}
+/**
+ * Create and start an MCP server that exposes OpenAPI operations as tools.
+ *
+ * @example
+ * ```ts
+ * import { startMcpServer } from '@spec2tools/stdio-mcp';
+ *
+ * await startMcpServer({
+ *   spec: './openapi.yaml',
+ *   name: 'my-api-server',
+ * });
+ * ```
+ */
+export declare function startMcpServer(options: McpServerOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,93 @@
+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';
+/**
+ * Create and start an MCP server that exposes OpenAPI operations as tools.
+ *
+ * @example
+ * ```ts
+ * import { startMcpServer } from '@spec2tools/stdio-mcp';
+ *
+ * await startMcpServer({
+ *   spec: './openapi.yaml',
+ *   name: 'my-api-server',
+ * });
+ * ```
+ */
+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);
+    // 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' }),
+            })),
+        };
+    });
+    // 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) {
+            return {
+                content: [{ type: 'text', text: `Error: Unknown tool "${toolName}"` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await tool.execute(args ?? {});
+            const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            return {
+                content: [{ type: 'text', text: resultText }],
+            };
+        }
+        catch (error) {
+            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}`;
+                }
+            }
+            else {
+                errorMessage = String(error);
+            }
+            return {
+                content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
+    // Start stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+/**
+ * Configure authentication from options or environment variables
+ */
+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
+    if (apiKey) {
+        authManager.setAccessToken(apiKey);
+    }
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@spec2tools/stdio-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that exposes OpenAPI endpoints as tools via stdio transport",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "spec2tools-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "keywords": [
+    "openapi",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "tools",
+    "stdio"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CahidArda/spec2tools.git",
+    "directory": "packages/stdio-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.24.0",
+    "@spec2tools/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}