{"_id":"specbridge","_rev":"3-81a67109ec812f8b927e9d7e5eaf6a5e","name":"specbridge","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"specbridge","version":"1.0.0","keywords":["mcp","openapi","swagger","api","tools","bridge","fastmcp","model-context-protocol"],"author":"","license":"MIT","_id":"specbridge@1.0.0","maintainers":[{"name":"tbosak","email":"timb63701@gmail.com"}],"bin":{"specbridge":"dist/cli.js"},"dist":{"shasum":"b92486e82a4c1ea52628013f64bd4ac138420129","tarball":"https://registry.npmjs.org/specbridge/-/specbridge-1.0.0.tgz","fileCount":45,"integrity":"sha512-IYvNN4xEn8BoX/URK16t/UGUwb9hnXMDWxhCE0eeUpCscyUHMbFoO8NOg2sQgmUp+sZLeuIM3c34COa8x0rREw==","signatures":[{"sig":"MEUCIGNZps88/nRBc348QPIVKX7ZDS1enzsPy9LhKiJpVhRPAiEAp+XiBYgkLt1w+FMTQfdvv35ldHrJSuri+0xm1D+E5c8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108291},"main":"dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"3570fc07de2733137ed1af4979de40a91c92bcd4","scripts":{"dev":"tsx src/cli.ts","test":"npm run build && node dist/cli.js --help","build":"tsc","start":"node dist/cli.js","prepare":"npm run build"},"_npmUser":{"name":"tbosak","email":"timb63701@gmail.com"},"_npmVersion":"10.9.2","description":"An MCP server that bridges OpenAPI specifications to MCP tools - scan a folder for spec files and automatically generate corresponding tools","directories":{},"_nodeVersion":"23.6.0","dependencies":{"zod":"^3.22.4","axios":"^1.6.0","dotenv":"^16.3.1","fastmcp":"^3.1.1","commander":"^11.1.0","@apidevtools/swagger-parser":"^10.1.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.6.0","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/specbridge_1.0.0_1749698929281_0.6737253597332269","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"specbridge","version":"1.0.1","keywords":["mcp","openapi","swagger","api","tools","bridge","fastmcp","model-context-protocol"],"author":"","license":"MIT","_id":"specbridge@1.0.1","maintainers":[{"name":"tbosak","email":"timb63701@gmail.com"}],"bin":{"specbridge":"dist/cli.js"},"dist":{"shasum":"d14fbec03c896d2ddca6ecdbb6e161d22f9bc278","tarball":"https://registry.npmjs.org/specbridge/-/specbridge-1.0.1.tgz","fileCount":46,"integrity":"sha512-jPwlTn86LT1OQUdZWKWFLYTDz+Mdh2AzuDNUUpaNOB/dgsRb1dn4Eyq4nOFeGxjhp+E7UJtRd7l1ftOO8iQXuA==","signatures":[{"sig":"MEUCIGCnzQ4dfSrYvJt+SdVP1CbP2bMIfEO9YfOX+dNaeKlOAiEAmL3RIoVwyXtm16Y/EC369W2xXWs+Gid3z/naPn6pVmo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109738},"main":"dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0b75da5c4fe15639ca40c5478c8e70b0e0fa75af","scripts":{"dev":"tsx src/cli.ts","test":"npm run build && node dist/cli.js --help","build":"tsc","start":"node dist/cli.js","prepare":"npm run build"},"_npmUser":{"name":"tbosak","email":"timb63701@gmail.com"},"_npmVersion":"10.9.2","description":"An MCP server that bridges OpenAPI specifications to MCP tools - scan a folder for spec files and automatically generate corresponding tools","directories":{},"_nodeVersion":"23.6.0","dependencies":{"zod":"^3.22.4","axios":"^1.6.0","dotenv":"^16.3.1","fastmcp":"^3.1.1","commander":"^11.1.0","@apidevtools/swagger-parser":"^10.1.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.6.0","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/specbridge_1.0.1_1749822352989_0.26899712543206333","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"specbridge","version":"1.0.2","description":"An MCP server that bridges OpenAPI specifications to MCP tools - scan a folder for spec files and automatically generate corresponding tools","main":"dist/index.js","bin":{"specbridge":"dist/cli.js"},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","start":"node dist/cli.js","test":"npm run build && node dist/cli.js --help","prepare":"npm run build"},"keywords":["mcp","openapi","swagger","api","tools","bridge","fastmcp","model-context-protocol"],"author":"","license":"MIT","dependencies":{"@apidevtools/swagger-parser":"^10.1.0","axios":"^1.6.0","commander":"^11.1.0","dotenv":"^16.3.1","fastmcp":"^3.1.1","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.10.0","tsx":"^4.6.0","typescript":"^5.3.0"},"engines":{"node":">=18.0.0"},"_id":"specbridge@1.0.2","gitHead":"0b75da5c4fe15639ca40c5478c8e70b0e0fa75af","types":"./dist/index.d.ts","_nodeVersion":"23.6.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-3qdSOIXd9fK3hKc84BJf9ozRq8Mf7zN6lD2pwEB8nW+S4EK4oe9rThHlSd39N5ImIF3RORpoLfNlIa5A9ZcN2A==","shasum":"6633ab3f869e0b289e474079b1b6bb62ea8c14e0","tarball":"https://registry.npmjs.org/specbridge/-/specbridge-1.0.2.tgz","fileCount":46,"unpackedSize":159655,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC9YgTTxG2DPyv+cbHmDeKTdkmV+KXewHzS8Y2+exp0OgIhAKii1HqvfgrctSOb7sfoPJsvyGYSvcjnf2R0vYlUSnsV"}]},"_npmUser":{"name":"tbosak","email":"timb63701@gmail.com","actor":{"name":"tbosak","email":"timb63701@gmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"tbosak","email":"timb63701@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/specbridge_1.0.2_1750299656381_0.4875322062502865"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-12T03:28:49.280Z","modified":"2025-06-19T02:20:57.084Z","1.0.0":"2025-06-12T03:28:49.460Z","1.0.1":"2025-06-13T13:45:53.216Z","1.0.2":"2025-06-19T02:20:56.579Z"},"license":"MIT","keywords":["mcp","openapi","swagger","api","tools","bridge","fastmcp","model-context-protocol"],"description":"An MCP server that bridges OpenAPI specifications to MCP tools - scan a folder for spec files and automatically generate corresponding tools","maintainers":[{"name":"tbosak","email":"timb63701@gmail.com"}],"readme":"

SpecBridge\n

\n\n \"Specbridge\n\n

\n

\n\nAn MCP server that turns OpenAPI specifications into MCP tools. Scan a folder for OpenAPI spec files and automatically generate corresponding tools. No configuration files, no separate servers - just drop specs in a folder and get tools.\n\n\nBuilt with [FastMCP](https://www.npmjs.com/package/fastmcp) for TypeScript.\n\n## āœØ Features\n\n- šŸŽÆ **Zero Configuration**: Filesystem is the interface - just drop OpenAPI specs in a folder\n- šŸ” **Auto Authentication**: Simple `.env` file with `{API_NAME}_API_KEY` pattern\n- šŸ·ļø **Namespace Isolation**: Multiple APIs coexist cleanly (e.g., `petstore_getPet`, `github_getUser`)\n- šŸ“ **Full OpenAPI Support**: Handles parameters, request bodies, authentication, and responses\n- šŸš€ **Multiple Transports**: Support for stdio and HTTP streaming\n- šŸ” **Built-in Debugging**: List command to see loaded specs and tools\n- āœļø **Spec Management**: Built-in tools to list, get, and update OpenAPI specifications\n- šŸŒ **API Discovery**: Integrated APIs.guru directory with 3000+ public API specifications\n\n## šŸš€ Quick Start\n\n### 1ļøāƒ£ Install (optional)\n\n```bash\nnpm install -g specbridge\n```\n\n### 2ļøāƒ£ Create a specs folder\n\n```bash\nmkdir ~/mcp-apis\n```\n\n### 3ļøāƒ£ Add OpenAPI specs\n\nDrop any `.json`, `.yaml`, or `.yml` OpenAPI specification files into your specs folder:\n\n```bash\n# Example: Download the Petstore spec\ncurl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json\n```\n\n### 4ļøāƒ£ Configure authentication (optional)\n\nCreate a `.env` file in your specs folder:\n\n```bash\n# ~/mcp-apis/.env\nPETSTORE_API_KEY=your_api_key_here\nGITHUB_TOKEN=ghp_your_github_token\nOPENAI_API_KEY=sk-your_openai_key\n```\n\n### 5ļøāƒ£ Add to MCP client configuration\n\nFor Claude Desktop or Cursor, add to your MCP configuration:\n\nIf installed on your machine:\n```json\n{\n \"mcpServers\": {\n \"specbridge\": {\n \"command\": \"specbridge\",\n \"args\": [\"--specs\", \"/path/to/your/specs/folder\"]\n }\n }\n}\n```\n\nOtherwise:\n```json\n{\n \"mcpServers\": {\n \"specbridge\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"specbridge\", \"--specs\", \"/absolute/path/to/your/specs\"]\n }\n }\n}\n```\n\n### 6ļøāƒ£ Restart your MCP client\n\nThat's it! Your OpenAPI specs are now available as MCP tools. āœ…\n\n## šŸ’» CLI Usage\n\n### šŸš€ Start the server\n\n```bash\n# Default: stdio transport, current directory\nspecbridge\n\n# Custom specs folder\nspecbridge --specs ~/my-api-specs\n\n# HTTP transport mode\nspecbridge --transport httpStream --port 8080\n```\n\n### šŸ“‹ List loaded specs and tools\n\n```bash\n# List all loaded specifications and their tools\nspecbridge list\n\n# List specs from custom folder\nspecbridge list --specs ~/my-api-specs\n\n## šŸ”‘ Authentication Patterns\n\nThe server automatically detects authentication from environment variables using these patterns:\n\n| Pattern | Auth Type | Usage |\n|---------|-----------|--------|\n| `{API_NAME}_API_KEY` | šŸ—ļø API Key | `X-API-Key` header |\n| `{API_NAME}_TOKEN` | šŸŽ« Bearer Token | `Authorization: Bearer {token}` |\n| `{API_NAME}_BEARER_TOKEN` | šŸŽ« Bearer Token | `Authorization: Bearer {token}` |\n| `{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD` | šŸ‘¤ Basic Auth | `Authorization: Basic {base64}` |\n\nThe `{API_NAME}` is derived from the filename of your OpenAPI spec:\n- `petstore.json` ā†’ `PETSTORE_API_KEY`\n- `github-api.yaml` ā†’ `GITHUB_TOKEN` \n- `my_custom_api.yml` ā†’ `MYCUSTOMAPI_API_KEY`\n\n## šŸ·ļø Tool Naming\n\nTools are automatically named using this pattern:\n- **With operationId**: `{api_name}_{operationId}`\n- **Without operationId**: `{api_name}_{method}_{path_segments}`\n\nExamples:\n- `petstore_getPetById` (from operationId)\n- `github_get_user_repos` (generated from `GET /user/repos`)\n\n## šŸ“ File Structure\n\n```\nyour-project/\nā”œā”€ā”€ api-specs/ # Your OpenAPI specs folder\nā”‚ ā”œā”€ā”€ .env # Authentication credentials\nā”‚ ā”œā”€ā”€ petstore.json # OpenAPI spec files\nā”‚ ā”œā”€ā”€ github.yaml # \nā”‚ ā””ā”€ā”€ custom-api.yml # \nā””ā”€ā”€ mcp-config.json # MCP client configuration\n```\n\n## šŸ“„ Example OpenAPI Spec\n\nHere's a minimal example that creates two tools:\n\n```yaml\n# ~/mcp-apis/example.yaml\nopenapi: 3.0.0\ninfo:\n title: Example API\n version: 1.0.0\nservers:\n - url: https://api.example.com\npaths:\n /users/{id}:\n get:\n operationId: getUser\n summary: Get user by ID\n parameters:\n - name: id\n in: path\n required: true\n schema:\n type: string\n responses:\n '200':\n description: User found\n /users:\n post:\n operationId: createUser\n summary: Create a new user\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n properties:\n name:\n type: string\n email:\n type: string\n responses:\n '201':\n description: User created\n```\n\nThis creates tools named:\n- `example_getUser`\n- `example_createUser`\n\n## šŸ› ļø Built-in Spec Management Tools\n\nSpecbridge automatically provides three built-in tools that allow you to manage your OpenAPI specifications:\n\n### šŸ”§ `specbridge_list_specs`\nLists all OpenAPI specification files in your specs folder with details like file size and modification date.\n\n### šŸ“„ `specbridge_get_spec`\nRetrieves the complete content of a specific OpenAPI specification file.\n- **Parameter**: `filename` - The name of the spec file (e.g., \"petstore.json\", \"github.yaml\")\n\n### āœļø `specbridge_update_spec`\nUpdates the content of a specific OpenAPI specification file. Automatically validates the content and reloads the tools.\n- **Parameters**: \n - `filename` - The name of the spec file to update\n - `content` - The new content for the specification file\n- **Features**:\n - āœ… Automatic backup creation before updates\n - āœ… JSON/YAML validation before saving\n - āœ… Security checks to prevent directory traversal\n - šŸ”„ Requires server restart to see updated tools\n\n### šŸ’” Use Cases\n\nThese tools enable powerful workflows:\n- **Enhance specs**: Use the LLM to improve descriptions, add missing parameters, or fix validation issues\n- **Add endpoints**: Dynamically extend APIs by adding new paths and operations\n- **Debug specs**: Retrieve and examine specification content to troubleshoot tool generation issues\n- **Maintain consistency**: Standardize naming conventions, descriptions, and schemas across multiple specs\n\nExample workflow:\n1. `specbridge_list_specs` - See what specs are available\n2. `specbridge_get_spec` - Retrieve a spec that needs enhancement\n3. Ask the LLM to improve descriptions or add missing fields\n4. `specbridge_update_spec` - Save the enhanced version\n5. Restart the MCP server to see the updated tools with better descriptions!\n\n## šŸŒ API Discovery with APIs.guru\n\nSpecbridge includes built-in integration with [APIs.guru](https://apis.guru/), the largest directory of OpenAPI specifications with 3000+ public APIs. This enables powerful discovery and installation workflows:\n\n### šŸ” Discovery Tools\n\n- **`apisguru_listAPIs`** - Browse all 3000+ APIs in the directory\n- **`apisguru_getProviders`** - List providers like Google, GitHub, Stripe, etc.\n- **`apisguru_getMetrics`** - Get directory statistics (APIs, endpoints, etc.)\n- **`apisguru_getProvider`** - Get all APIs from a specific provider\n- **`apisguru_getServices`** - Get service names for a provider (e.g., Gmail, Drive for Google)\n- **`apisguru_getAPI`** - Get details for a specific API version\n- **`apisguru_getServiceAPI`** - Get details for a specific service API\n\n### ā¬‡ļø Download Tool\n\n- **`specbridge_download_spec`** - Download and save any OpenAPI spec from a URL\n\n### šŸ’” Discovery Workflow Examples\n\n**Find and add the Stripe API:**\n1. `apisguru_getProvider` with provider `\"stripe.com\"` - See available Stripe APIs\n2. `apisguru_getAPI` with provider `\"stripe.com\"` and api `\"2020-08-27\"` - Get API details\n3. Use the `swaggerUrl` from the response with `specbridge_download_spec` - Download the spec\n4. Restart server - Now you have Stripe API tools!\n\n**Explore Google APIs:**\n1. `apisguru_getServices` with provider `\"googleapis.com\"` - See all Google services\n2. `apisguru_getServiceAPI` with provider `\"googleapis.com\"`, service `\"gmail\"`, api `\"v1\"` - Get Gmail API details\n3. Download using the returned OpenAPI spec URL\n\n**Browse popular APIs:**\n1. `apisguru_listAPIs` - Get full directory (warning: large response!)\n2. Filter by preferred APIs or search for specific providers\n3. Download the ones you need\n\n## šŸ”§ Troubleshooting\n\n### āŒ No tools appearing?\n\n1. Check that your OpenAPI specs are valid:\n ```bash\n specbridge list --specs /path/to/specs\n ```\n\n2. Ensure files have correct extensions (`.json`, `.yaml`, `.yml`)\n\n3. Check the server logs for parsing errors\n\n> **āš ļø Note:** Specbridge works best when you use absolute paths (with no spaces) for the `--specs` argument and other file paths. Relative paths or paths containing spaces may cause issues on some platforms or with some MCP clients.\n\n### šŸ” Authentication not working?\n\n1. Verify your `.env` file is in the specs directory\n2. Check the naming pattern matches your spec filename\n3. Use the list command to verify auth configuration:\n ```bash\n specbridge list\n ```\n\n### šŸ”„ Tools not updating after spec changes?\n\n1. Restart the MCP server to reload the specs\n2. Check file permissions\n3. Restart the MCP client if needed\n\n## šŸ› ļø Development\n\n```bash\n# Clone and install\ngit clone https://github.com/TBosak/specbridge.git\ncd specbridge\nnpm install\n\n# Build\nnpm run build\n\n# Test locally\nnpm run dev -- --specs ./examples\n```\n\n## šŸ¤ Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n","readmeFilename":"README.md"}