# @minamorl/openapi-mcp-bridge

Runtime MCP server that dynamically bridges any OpenAPI 3.x spec to MCP tools.

**No code generation. No build step. One command.**

## Quick Start

```bash
npx @minamorl/openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json
```

## Why not codegen?

Existing tools (openapi-mcp-generator, etc.) generate static TypeScript files from your OpenAPI spec. Every time the API changes, you regenerate, rebuild, redeploy.

openapi-mcp-bridge takes a different approach: **runtime bridging**. It reads the OpenAPI spec at startup and dynamically creates MCP tools. Update the spec → restart the server. That's it.

| | Codegen tools | openapi-mcp-bridge |
|---|---|---|
| API spec changes | Regenerate → rebuild → restart | **Restart only** |
| Setup | npm install → generate → configure → build → start | **npx + 1 flag** |
| OAuth2 | "Put token in .env" | Built-in auth flows |
| Transport | stdio only | stdio + Streamable HTTP (planned) |

## Usage

### CLI

```bash
# From URL
openapi-mcp-bridge --spec https://api.example.com/openapi.json

# From local file (JSON or YAML)
openapi-mcp-bridge --spec ./api.yaml

# With auth
openapi-mcp-bridge --spec ./api.yaml --auth-type bearer --auth-token $TOKEN

# With custom base URL
openapi-mcp-bridge --spec ./api.yaml --base-url http://localhost:3000

# With custom headers
openapi-mcp-bridge --spec ./api.yaml -H "X-Custom: value"
```

### Claude Desktop / Cursor config

```json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@minamorl/openapi-mcp-bridge", "--spec", "https://api.example.com/openapi.json"]
    }
  }
}
```

### Programmatic API

```typescript
import { parseSpec, createBridgeServer, startStdioServer } from "@minamorl/openapi-mcp-bridge";

const doc = await parseSpec("./api.yaml");
const server = await createBridgeServer({ doc, baseUrl: "http://localhost:3000" });
await startStdioServer(server);
```

## How It Works

```
OpenAPI 3.x spec (JSON/YAML/URL)
        ↓ Parse + resolve $refs
   Tool definitions (name, schema, method, path)
        ↓ Register as MCP tools
   MCP Server (stdio)
        ↓ On tool call
   HTTP request to actual API
        ↓
   Response back to LLM
```

1. **Parser** reads and validates the OpenAPI spec, resolving all `$ref` references
2. **Mapper** converts each operation to an MCP tool with proper input schemas
3. **Server** registers tools and handles MCP protocol
4. **Executor** translates tool calls into HTTP requests

## Auth

```bash
# Bearer token
--auth-type bearer --auth-token YOUR_TOKEN

# API key
--auth-type api-key --auth-token YOUR_KEY --api-key-header X-API-Key

# Basic auth (token = base64 of user:pass)
--auth-type basic --auth-token BASE64_CREDENTIALS
```

## License

MIT