# MCP OpenAPI Bridge

[![CI](https://github.com/KaryawanSurga/mcp-openapi-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/mcp-openapi-bridge/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Turn any OpenAPI 3.x spec into callable MCP tools at runtime.**

Point the bridge at a spec — JSON or YAML — and every operation becomes an MCP tool with a real input schema: path, query, and header parameters plus the JSON request body. Calling a tool performs the HTTP request and returns a bounded, readable response. No code generation, no build step, no wrappers to maintain.

Tenth tool in the TokenSaver family: [TokenSaver MCP](https://github.com/KaryawanSurga/TokenSaverMcp) maps repositories, [MCP Context Budget](https://github.com/KaryawanSurga/mcp-context-budget) audits tool costs, [MCP Web Snapshot](https://github.com/KaryawanSurga/mcp-web-snapshot) reads the web, [MCP Log Tail](https://github.com/KaryawanSurga/mcp-log-tail) summarizes logs, [MCP Secret Scan](https://github.com/KaryawanSurga/mcp-secret-scan) guards commits, [MCP JSON Lens](https://github.com/KaryawanSurga/mcp-json-lens) explores data, [MCP Gateway](https://github.com/KaryawanSurga/mcp-gateway) aggregates servers, [commitsmith](https://github.com/KaryawanSurga/commitsmith) writes commits, [MCP Injection Guard](https://github.com/KaryawanSurga/mcp-injection-guard) screens input, and OpenAPI Bridge connects APIs.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## Why

Almost every API ships an OpenAPI spec, and almost no agent can call it without someone writing and maintaining a wrapper. The bridge closes that gap at runtime: the spec is the integration. Add a server, remove a server, change a schema — the tools follow.

## Quick start

List what a spec exposes:

```sh
npx -y mcp-openapi-bridge inspect ./openapi.yaml
```

```text
# Petstore (5 tool(s), base https://api.example.com/v1)
- listpets  GET /pets — List pets
- createpet  POST /pets — Create a pet
- getpetbyid  GET /pets/{petId} — Find pet by ID
- deletepet  DELETE /pets/{petId} — Delete a pet
- gettree  GET /tree
```

Call an operation without any MCP client:

```sh
npx -y mcp-openapi-bridge call ./openapi.yaml getpetbyid --args '{"petId":"42"}' \
  --base-url https://api.example.com/v1 --header "Authorization: Bearer $TOKEN"
```

Serve it to your agent:

```sh
npx -y mcp-openapi-bridge serve ./openapi.yaml --read-only
```

## MCP server

```json
{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-bridge", "serve", "./openapi.yaml"],
      "env": { "PETSTORE_TOKEN": "..." }
    }
  }
}
```

Every operation becomes a tool named from `operationId` (or `METHOD /path` when missing) with a description built from the summary and route.

## How it works

1. **Load** the spec from a JSON or YAML file.
2. **Resolve** local `$ref`s (schemas, parameters, request bodies) with recursion protection.
3. **Index** operations, merging path-level and operation-level parameters.
4. **Generate** one MCP tool per operation with a JSON Schema built from parameters plus a `body` property for JSON request bodies.
5. **Invoke** by mapping arguments to the URL, query string, headers, and body — then return the response capped by size and token budgets.

## Options

| Flag | Meaning |
| --- | --- |
| `--base-url <url>` | Override `servers[0].url` |
| `--header "Name: value"` | Extra request header; repeatable |
| `--read-only` | Only expose GET and HEAD operations |
| `--tag <name>` / `--exclude-tag <name>` | Filter operations by tag |
| `--timeout <ms>` | Request timeout (default 15000) |
| `--max-bytes <n>` | Response size cap (default 1000000) |
| `--budget <n>` | Token budget for responses (default 4000) |

Exit codes: `0` success, `1` request or HTTP failure, `2` usage error. `call` exits `1` on HTTP errors so scripts can gate on it.

## Limitations (v0.1.0)

- Local `$ref`s only; external files are rejected with a clear message.
- Cookie parameters are ignored.
- OpenAPI 3.x only (2.0 / Swagger is not supported).
- Response bodies are returned as text or pretty JSON; binary responses are capped, not decoded.
- No OAuth flow — pass tokens through `--header` or your MCP server `env` config.

## Security notes

- The bridge itself stores nothing. Credentials live in your client config or shell.
- `--read-only` plus tag filters keep mutating operations away from an agent session.
- Responses are bounded by `--max-bytes` and `--budget`, so a huge API payload cannot flood the context.
- Requests go only to the configured base URL; no telemetry, no callbacks.

## Development

```sh
npm install
npm run typecheck
npm run build
npm test
```

The suite covers spec loading (JSON + YAML), `$ref` resolution, operation indexing, schema generation, request building, live HTTP invocation against a local test API, MCP round trips, and CLI flows.

## License

MIT — see [LICENSE](LICENSE).