{"id":28655708,"url":"https://github.com/tbosak/specbridge","last_synced_at":"2026-04-14T00:04:19.727Z","repository":{"id":298622401,"uuid":"1000567548","full_name":"TBosak/specbridge","owner":"TBosak","description":"Turn OpenAPI Specs into MCP Tools","archived":false,"fork":false,"pushed_at":"2025-06-12T03:02:11.000Z","size":593,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T03:22:31.127Z","etag":null,"topics":["api","bridge","mcp","model-context-protocol","model-context-protocol-servers","openapi","tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TBosak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T01:52:57.000Z","updated_at":"2025-06-12T03:02:15.000Z","dependencies_parsed_at":"2025-06-12T03:22:34.315Z","dependency_job_id":"4a95c502-aa4a-4891-ac5d-28753ea348a2","html_url":"https://github.com/TBosak/specbridge","commit_stats":null,"previous_names":["tbosak/specbridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TBosak/specbridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBosak%2Fspecbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBosak%2Fspecbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBosak%2Fspecbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBosak%2Fspecbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TBosak","download_url":"https://codeload.github.com/TBosak/specbridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBosak%2Fspecbridge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259606974,"owners_count":22883559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bridge","mcp","model-context-protocol","model-context-protocol-servers","openapi","tools"],"created_at":"2025-06-13T08:07:41.350Z","updated_at":"2026-04-14T00:04:19.721Z","avatar_url":"https://github.com/TBosak.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  SpecBridge\n\n[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/ab3b0729-c54e-4359-aed0-606b90995b59)\n\u003cimg src=\"https://badge.mcpx.dev\" title=\"MCP\"/\u003e\n\n\u003c/h1\u003e\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\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## 💻 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## 🔧 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\u003e **⚠️ 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\n\u003cp\u003e\n\u003ca href=\"https://glama.ai/mcp/servers/@TBosak/specbridge\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@TBosak/specbridge/badge\" alt=\"Specbridge MCP server\" /\u003e\n\u003c/a\u003e\n  \u003ca href=\"https://mseep.ai/app/tbosak-specbridge\"\u003e\n  \u003cimg src=\"https://mseep.net/pr/tbosak-specbridge-badge.png\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbosak%2Fspecbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftbosak%2Fspecbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbosak%2Fspecbridge/lists"}