swag

MCP server (Python, FastMCP).

Run

The only runtime mode is an HTTP server: FastAPI + MCP on /mcp and GET /health. Locally it runs via Docker; in production the same image runs (uv run uvicorn swag.app.asgi:app).

Local (Docker)

docker compose up --build

Compose mounts ./swag into the container and runs uvicorn with --reload, so code changes are picked up without rebuilding the image.

Check:

curl http://localhost:8000/health
# {"status":"ok","service":"swag"}
# MCP for Cursor: http://localhost:8000/mcp

Related MCP server: Swagger Navigator MCP Server

Cursor

Connect to the running server over HTTP:

{
  "mcpServers": {
    "swag": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Tools

On MCP initialize, the server sends instructions telling the agent to call list_services first, pick a service_id from name/description, then search_spec with the user's action/entity query and any clear method/path/tag hints, and finally get_operation on the chosen hit to fetch the details needed to build a request.

search_spec does not return the full OpenAPI document. It builds an in-memory search index from the selected spec (JSON or YAML) and returns top operation candidates; get_operation then returns the self-contained contract of a single operation. The server never calls the target API itself.

Configuration

Layout

The code is organized into vertical feature packages: each package is self-contained (its own models / service / tool).

swag/
  config.py             # settings
  exceptions.py         # SwagError hierarchy
  mcp_instructions.py   # server instructions for agents
  catalog/              # services registry (list_services): models, source, service, tool
  spec/                 # raw OpenAPI/Swagger document: models, fetch, decode, validate, parsing, service
  search/               # search index + ranking (search_spec): models, text, extractors,
                        #   index, keyword, fuzzy, boosters, engine, tool
  operation/            # full contract of a single operation (get_operation): models, detail, ref_resolver, tool
  app/                  # composition root: gateway (orchestrator), tools, server (FastMCP), asgi (FastAPI)
data/
  catalog.json          # production catalog (URLs only)

Development

Install dev dependencies and pre-commit hooks (runs ruff + mypy from pyproject.toml before each commit):

uv sync --group dev
task pre-commit-install
# or: uv run pre-commit install

Run all hooks manually:

uv run pre-commit run --all-files

Requires go-task: brew install go-task (or see project docs).

Tests

uv run pytest
# or: task test