specbridge

SpecBridge

An 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.

Built with FastMCP for TypeScript.

✨ Features

• 🎯 Zero Configuration: Filesystem is the interface - just drop OpenAPI specs in a folder
• 🔐 Auto Authentication: Simple .env file with {API_NAME}_API_KEY pattern
• 🏷️ Namespace Isolation: Multiple APIs coexist cleanly (e.g., petstore_getPet, github_getUser)
• 📝 Full OpenAPI Support: Handles parameters, request bodies, authentication, and responses
• 🚀 Multiple Transports: Support for stdio and HTTP streaming
• 🔍 Built-in Debugging: List command to see loaded specs and tools
• ✏️ Spec Management: Built-in tools to list, get, and update OpenAPI specifications
• 🌐 API Discovery: Integrated APIs.guru directory with 3000+ public API specifications

🚀 Quick Start

1️⃣ Install (optional)

npm install -g specbridge

2️⃣ Create a specs folder

mkdir ~/mcp-apis

3️⃣ Add OpenAPI specs

Drop any .json, .yaml, or .yml OpenAPI specification files into your specs folder:

# Example: Download the Petstore spec
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4️⃣ Configure authentication (optional)

Create a .env file in your specs folder:

# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key

5️⃣ Add to MCP client configuration

For Claude Desktop or Cursor, add to your MCP configuration:

If installed on your machine:

{
  "mcpServers": {
    "specbridge": {
      "command": "specbridge",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

Otherwise:

{
  "mcpServers": {
    "specbridge": {
      "command": "npx",
      "args": ["-y", "specbridge", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}

6️⃣ Restart your MCP client

That's it! Your OpenAPI specs are now available as MCP tools. ✅

💻 CLI Usage

🚀 Start the server

# Default: stdio transport, current directory
specbridge

# Custom specs folder
specbridge --specs ~/my-api-specs

# HTTP transport mode
specbridge --transport httpStream --port 8080

📋 List loaded specs and tools

# List all loaded specifications and their tools
specbridge list

# List specs from custom folder
specbridge list --specs ~/my-api-specs

## 🔑 Authentication Patterns

The server automatically detects authentication from environment variables using these patterns:

| Pattern | Auth Type | Usage |
|---------|-----------|--------|
| `{API_NAME}_API_KEY` | 🗝️ API Key | `X-API-Key` header |
| `{API_NAME}_TOKEN` | 🎫 Bearer Token | `Authorization: Bearer {token}` |
| `{API_NAME}_BEARER_TOKEN` | 🎫 Bearer Token | `Authorization: Bearer {token}` |
| `{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD` | 👤 Basic Auth | `Authorization: Basic {base64}` |

The `{API_NAME}` is derived from the filename of your OpenAPI spec:
- `petstore.json` → `PETSTORE_API_KEY`
- `github-api.yaml` → `GITHUB_TOKEN` 
- `my_custom_api.yml` → `MYCUSTOMAPI_API_KEY`

## 🏷️ Tool Naming

Tools are automatically named using this pattern:
- **With operationId**: `{api_name}_{operationId}`
- **Without operationId**: `{api_name}_{method}_{path_segments}`

Examples:
- `petstore_getPetById` (from operationId)
- `github_get_user_repos` (generated from `GET /user/repos`)

## 📁 File Structure

your-project/ ├── api-specs/ # Your OpenAPI specs folder │ ├── .env # Authentication credentials │ ├── petstore.json # OpenAPI spec files │ ├── github.yaml # │ └── custom-api.yml # └── mcp-config.json # MCP client configuration

## 📄 Example OpenAPI Spec

Here's a minimal example that creates two tools:

```yaml
# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created

This creates tools named:

• example_getUser
• example_createUser

🛠️ Built-in Spec Management Tools

Specbridge automatically provides three built-in tools that allow you to manage your OpenAPI specifications:

🔧 specbridge_list_specs

Lists all OpenAPI specification files in your specs folder with details like file size and modification date.

📄 specbridge_get_spec

Retrieves the complete content of a specific OpenAPI specification file.

• Parameter: filename - The name of the spec file (e.g., "petstore.json", "github.yaml")

✏️ specbridge_update_spec

Updates the content of a specific OpenAPI specification file. Automatically validates the content and reloads the tools.

• Parameters:
  • filename - The name of the spec file to update
  • content - The new content for the specification file
• Features:
  • ✅ Automatic backup creation before updates
  • ✅ JSON/YAML validation before saving
  • ✅ Security checks to prevent directory traversal
  • 🔄 Requires server restart to see updated tools

💡 Use Cases

These tools enable powerful workflows:

• Enhance specs: Use the LLM to improve descriptions, add missing parameters, or fix validation issues
• Add endpoints: Dynamically extend APIs by adding new paths and operations
• Debug specs: Retrieve and examine specification content to troubleshoot tool generation issues
• Maintain consistency: Standardize naming conventions, descriptions, and schemas across multiple specs

Example workflow:

• specbridge_list_specs - See what specs are available
• specbridge_get_spec - Retrieve a spec that needs enhancement
• Ask the LLM to improve descriptions or add missing fields
• specbridge_update_spec - Save the enhanced version
• Restart the MCP server to see the updated tools with better descriptions!

🌐 API Discovery with APIs.guru

Specbridge includes built-in integration with APIs.guru, the largest directory of OpenAPI specifications with 3000+ public APIs. This enables powerful discovery and installation workflows:

🔍 Discovery Tools

• apisguru_listAPIs - Browse all 3000+ APIs in the directory
• apisguru_getProviders - List providers like Google, GitHub, Stripe, etc.
• apisguru_getMetrics - Get directory statistics (APIs, endpoints, etc.)
• apisguru_getProvider - Get all APIs from a specific provider
• apisguru_getServices - Get service names for a provider (e.g., Gmail, Drive for Google)
• apisguru_getAPI - Get details for a specific API version
• apisguru_getServiceAPI - Get details for a specific service API

⬇️ Download Tool

• specbridge_download_spec - Download and save any OpenAPI spec from a URL

💡 Discovery Workflow Examples

Find and add the Stripe API:

• apisguru_getProvider with provider "stripe.com" - See available Stripe APIs
• apisguru_getAPI with provider "stripe.com" and api "2020-08-27" - Get API details
• Use the swaggerUrl from the response with specbridge_download_spec - Download the spec
• Restart server - Now you have Stripe API tools!

Explore Google APIs:

• apisguru_getServices with provider "googleapis.com" - See all Google services
• apisguru_getServiceAPI with provider "googleapis.com", service "gmail", api "v1" - Get Gmail API details
• Download using the returned OpenAPI spec URL

Browse popular APIs:

• apisguru_listAPIs - Get full directory (warning: large response!)
• Filter by preferred APIs or search for specific providers
• Download the ones you need

🔧 Troubleshooting

❌ No tools appearing?

• Check that your OpenAPI specs are valid:

  specbridge list --specs /path/to/specs
  

• Ensure files have correct extensions (.json, .yaml, .yml)

• Check the server logs for parsing errors

⚠️ 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.

🔐 Authentication not working?

• Verify your .env file is in the specs directory
• Check the naming pattern matches your spec filename
• Use the list command to verify auth configuration:

  specbridge list
  

🔄 Tools not updating after spec changes?

• Restart the MCP server to reload the specs
• Check file permissions
• Restart the MCP client if needed

🛠️ Development

# Clone and install
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# Build
npm run build

# Test locally
npm run dev -- --specs ./examples

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.