SpecBridge

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
• 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

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.
4. Configure authentication (optional) Create a .env file in your specs folder.
5. Add to MCP client configuration For Claude Desktop or Cursor, add to your MCP configuration.

CLI Usage# Start the server

specbridge
```\n\n### List loaded specs and tools
```bash
specbridge list

Authentication Patterns

The server automatically detects authentication from environment variables using specific patterns.

Tool Naming

Tools are automatically named using specific patterns based on operationId or method and path segments.

File Structure

your-project/
├── api-specs/
│   ├── .env
│   ├── petstore.json
│   ├── github.yaml
│   └── custom-api.yml
└── mcp-config.json

Example OpenAPI Spec

Here's a minimal example that creates two tools:

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

Troubleshooting

1. Check that your OpenAPI specs are valid.
2. Ensure files have correct extensions.
3. Check the server logs for parsing errors.

Development

git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install\n\n# Build
npm run build\n\n# Test locally
npm run dev -- --specs ./examples

Contributing

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