# swagger-mcp

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for
**navigating** an OpenAPI / Swagger specification. It gives a coding agent tools
to explore a large API's documentation — search endpoints, read parameters and
schemas, inspect auth — without dumping the whole spec into context.

It **never calls the described API.** It only reads its documentation.

Works with any MCP-capable harness (Claude Code, Cursor, Cline, Windsurf,
Zed, opencode, …) over stdio.

## Usage

Add it to your MCP client config. No install step — `npx` fetches it on demand:

```json
{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@emreyc/swagger-mcp@latest"]
    }
  }
}
```

Every tool takes a `spec` parameter — a URL (or local path) to a Swagger 2.0 or
OpenAPI 3.x document — so a single server can navigate any number of specs in one
session. Internal/localhost URLs (e.g. Spring Boot's
`http://localhost:8080/v3/api-docs`) are supported.

If you mostly work with one spec, set `API_DOCS_URL` as a default so `spec` can be
omitted:

```json
{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@emreyc/swagger-mcp@latest"],
      "env": { "API_DOCS_URL": "https://api.example.com/swagger.json" }
    }
  }
}
```

Specs are fetched lazily and cached per URL for the process lifetime.

## Tools

Designed for progressive disclosure — orient, then discover, then drill down —
so the agent loads only what it needs.

| Tool | Purpose |
| --- | --- |
| `get_api_overview` | Title, version, servers, global security, counts. Start here. |
| `list_tags` | Tags (logical groups) with endpoint counts. |
| `list_endpoints` | Compact index of endpoints; optional `tag` filter. |
| `search_endpoints` | Substring search over path/summary/description/params. |
| `list_schemas` | Named schemas with one-line descriptions. |
| `search_schemas` | Substring search over schema names, fields, descriptions. |
| `get_endpoint` | Full detail for one `method`+`path`: params, request/response schemas, auth. |
| `get_schema` | Resolve one named schema. |
| `get_auth` | Security schemes in full (OAuth2 flows, scopes, API-key locations). |

Every tool also accepts an optional `spec` argument (a spec URL or path); when
omitted it falls back to `API_DOCS_URL`.

Swagger 2.0 and OpenAPI 3.x are normalized into one consistent output shape.
Nested named schemas are shown as `{ "$schema": "Name" }` markers — call
`get_schema` to expand them. This keeps every response bounded and is safe with
circular schemas.

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
```

## License

MIT