swagger-navigator

Swagger Navigator is an MCP server that indexes and searches Swagger/OpenAPI specifications to help AI assistants explore REST APIs. It dynamically discovers API specs from local files or remote HTTP endpoints, builds an internal index, and provides a fuzzy search interface over endpoints, descriptions, and metadata. Use the provided commands to list sources and endpoints, and to search for endpoints using natural language queries. The server is designed to be queried by LLMs or IDE assistants to generate clients, anticorruption layers, or type-safe clients based on the actual API schema.

Prerequisites:

• Node.js 18+ (npm comes with Node.js)
• A working network connection for fetching remote OpenAPI specs (if used)

Install and build:

# 1) Install dependencies
npm install

# 2) Build TypeScript sources (if the project uses a build step)
npm run build

Run the MCP server (example with a configuration path):

CONFIG_PATH=./swagger-navigator-mcp.config.yaml npm start

If you prefer using npx to run directly (as in the MCP config):

# This will fetch and run the package without local installation
npx -y swagger-navigator-mcp

Configuration file (swagger-navigator-mcp.config.yaml) example:

# Swagger Navigator MCP Server Configuration

sources:
  - name: "petstore-local"
    source: "./specs/petstore.json"
    description: "Local Petstore API specification"

  - name: "github-api"
    source: "https://api.github.com"
    description: "GitHub REST API v3"
    headers:
      Authorization: "token ${GITHUB_TOKEN}"
      Accept: "application/vnd.github.v3+json"

search:
  fuzzyThreshold: 0.6

refreshInterval: 300

Environment variables can be substituted in the config using ${VAR_NAME} syntax. Ensure required variables are exported before starting the server.

Notes:

• The CONFIG_PATH environment variable points to the YAML config that lists sources and search options.
• For private APIs, supply authentication headers in the config, using environment variable substitution for secrets.
• If the OpenAPI spec changes, the MCP’s refresh interval will trigger re-indexing; you can also restart the server to force a reload.
• When starting with npx, the package will be fetched on demand; with local npm install, you can reuse the built artifacts for faster startup.