# swagger-openapi-mcp

MCP server for querying Swagger/OpenAPI metadata efficiently from AI tools.

It is useful for large API projects where querying the generated OpenAPI contract is faster and more reliable than reading controller and DTO source code directly.

## Features

- Load one or more OpenAPI JSON sources from URLs or local files.
- Search APIs by path, method, tag, summary, description, operation ID, parameter names, request schemas, and response schemas.
- Get exact API details by `method + path`.
- Inspect schema fields, required flags, descriptions, references, and enum values.
- Reverse lookup APIs by schema name.
- Export currently loaded OpenAPI JSON for offline use.
- Cache OpenAPI sources so clients can keep querying when an API service is temporarily unavailable.
- Revalidate cached URL sources with `ETag` and `Last-Modified` when supported.
- Ranked fuzzy search for partial terms, acronyms, and non-contiguous matches.
- Markdown and JSON response formats.
- Pagination and response truncation for large projects.

## Requirements

- Node.js 18 or newer.
- An MCP client that supports stdio servers.

## Install

```bash
npm install
npm run build
```

## Configure Sources

Single Swagger/OpenAPI endpoint:

```bash
export OPENAPI_URL="http://localhost:8080/v3/api-docs"
```

Multiple Swagger/OpenAPI groups:

```bash
export OPENAPI_SOURCES="admin=http://localhost:8080/v3/api-docs/admin,public=http://localhost:8080/v3/api-docs/public"
```

Local exported JSON:

```bash
export OPENAPI_FILE="./openapi.json"
```

Optional cache:

```bash
export OPENAPI_CACHE_DIR=".cache/openapi"
export OPENAPI_CACHE_TTL_SECONDS="86400"
```

When `OPENAPI_CACHE_DIR` is set, each loaded source is cached. If the original file or URL is unavailable later, the server falls back to cache when possible.

For URL sources, the server stores `ETag` and `Last-Modified` response headers when present. Later refreshes send `If-None-Match` and `If-Modified-Since`; a `304 Not Modified` response reuses the cached OpenAPI JSON without re-parsing a new document. If the remote server does not provide these headers, the server still fetches the latest JSON and updates the cache.

## MCP Client Config

After building from source, configure your MCP client to run the compiled stdio server:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": ["./dist/index.js"],
      "environment": {
        "OPENAPI_SOURCES": "admin=http://localhost:8080/v3/api-docs/admin,public=http://localhost:8080/v3/api-docs/public",
        "OPENAPI_CACHE_DIR": ".cache/openapi",
        "OPENAPI_CACHE_TTL_SECONDS": "86400"
      }
    }
  }
}
```

If installed as a package, use the binary name instead:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "openapi-mcp-server",
      "environment": {
        "OPENAPI_URL": "http://localhost:8080/v3/api-docs"
      }
    }
  }
}
```

## TLS Notes

For HTTPS Swagger/OpenAPI endpoints with a self-signed or untrusted test certificate, Node may fail with `fetch failed` during MCP startup. Prefer fixing the test certificate or installing the internal CA. For short-lived test environments only, you can disable Node TLS verification for this MCP process:

```json
{
  "environment": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}
```

Do not use `NODE_TLS_REJECT_UNAUTHORIZED=0` for production or untrusted networks.

## Tools

- `openapi_refresh_index`: reload OpenAPI sources.
- `openapi_list_sources`: list source groups and operation counts.
- `openapi_list_tags`: list API tags/modules.
- `openapi_search_api`: search APIs by natural keywords.
- `openapi_get_api_detail`: get full detail for one API.
- `openapi_get_schema`: inspect schema fields.
- `openapi_find_api_by_schema`: reverse lookup APIs by schema.
- `openapi_export_documents`: export loaded OpenAPI JSON to local files.

## Typical AI Workflow

1. `openapi_list_sources`
2. `openapi_list_tags`
3. `openapi_search_api({ "query": "product list" })`
4. `openapi_get_api_detail({ "method": "GET", "path": "/admin/products" })`
5. `openapi_get_schema({ "name": "ProductListResponse" })`

## Export Workflow

Export currently loaded documents:

```json
{
  "output_dir": "./openapi-exports"
}
```

Then use an exported file as an offline source:

```bash
export OPENAPI_FILE="./openapi-exports/admin.openapi.json"
```

## Development

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

## Notes

- The server is stdio-based and long-running. Run it through an MCP client.
- Tool logs go to stderr so stdout remains reserved for MCP protocol messages.
- If the API service is not running, use `OPENAPI_FILE` with exported JSON.
- For frequently changing APIs, call `openapi_refresh_index` after restarting the API service or regenerating Swagger/OpenAPI.

## License

MIT