<h1 align="center">
  SpecBridge

[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/ab3b0729-c54e-4359-aed0-606b90995b59)
<img src="https://badge.mcpx.dev" title="MCP"/>

</h1>
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](https://www.npmjs.com/package/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

## 🚀 Quick Start

### 1️⃣ Install (optional)

```bash
npm install -g specbridge
```

### 2️⃣ Create a specs folder

```bash
mkdir ~/mcp-apis
```

### 3️⃣ Add OpenAPI specs

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

```bash
# 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:

```bash
# ~/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:
```json
{
  "mcpServers": {
    "specbridge": {
      "command": "specbridge",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}
```

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

## 💻 CLI Usage

### 🚀 Start the server

```bash
# 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

```bash
# 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`

## 🔧 Troubleshooting

### ❌ No tools appearing?

1. Check that your OpenAPI specs are valid:
   ```bash
   specbridge list --specs /path/to/specs
   ```

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

3. 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?

1. Verify your `.env` file is in the specs directory
2. Check the naming pattern matches your spec filename
3. Use the list command to verify auth configuration:
   ```bash
   specbridge list
   ```

### 🔄 Tools not updating after spec changes?

1. Restart the MCP server to reload the specs
2. Check file permissions
3. Restart the MCP client if needed

## 🛠️ Development

```bash
# 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.

<p>
<a href="https://glama.ai/mcp/servers/@TBosak/specbridge">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@TBosak/specbridge/badge" alt="Specbridge MCP server" />
</a>
  <a href="https://mseep.ai/app/tbosak-specbridge">
  <img src="https://mseep.net/pr/tbosak-specbridge-badge.png">
  </a>
</p>