Metadata-Version: 2.4
Name: openapi-atlas-mcp
Version: 0.0.1
Summary: Aggregate multiple OpenAPI/Swagger specs into one searchable, documentation-focused MCP server.
Project-URL: Homepage, https://github.com/mbvillaverde/openapi-atlas-mcp
Project-URL: Repository, https://github.com/mbvillaverde/openapi-atlas-mcp
Project-URL: Issues, https://github.com/mbvillaverde/openapi-atlas-mcp/issues
Author: openapi-atlas-mcp contributors
License-Expression: MIT
License-File: LICENSE
Keywords: api,documentation,llm,mcp,model-context-protocol,openapi,swagger
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp~=3.0
Requires-Dist: httpx~=0.27
Requires-Dist: openapi-pydantic~=0.5.0
Requires-Dist: pydantic~=2.0
Requires-Dist: pyyaml~=6.0
Requires-Dist: typer~=0.12
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6; extra == 'dev'
Description-Content-Type: text/markdown

# openapi-atlas-mcp

`openapi-atlas-mcp` aggregates multiple OpenAPI/Swagger specifications from your
backend services into a single searchable, documentation-focused
[Model Context Protocol](https://modelcontextprotocol.io) server. It lets an AI
agent (Claude Desktop, Cursor, Claude Code, VS Code) answer questions like
_"show me the payload for submit order"_ across **all** of your configured
services in one query — instead of making you hunt through N separate Swagger UIs.

## Install

```bash
# pip
pip install openapi-atlas-mcp

# uv (recommended for MCP servers)
uv tool install openapi-atlas-mcp
```

## Quick start

1. Create a config file (`.openapi-atlas.json`) in your project root:

```bash
openapi-atlas-mcp init
```

This launches an interactive wizard. Or write the file manually:

```json
{
  "services": [
    {
      "name": "orders",
      "url": "http://localhost:8000"
    },
    {
      "name": "billing",
      "url": "https://billing.internal.example.com",
      "auth": {
        "type": "bearer",
        "token_env": "BILLING_API_TOKEN"
      }
    }
  ]
}
```

2. Set any required environment variables:

```bash
export BILLING_API_TOKEN=your-secret-token
```

3. Start the server:

```bash
openapi-atlas-mcp serve
```

## Agent-host integration

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "openapi-atlas": {
      "command": "uv",
      "args": ["tool", "run", "openapi-atlas-mcp", "serve"]
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "openapi-atlas": {
      "command": "openapi-atlas-mcp",
      "args": ["serve"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add openapi-atlas -- openapi-atlas-mcp serve
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "openapi-atlas": {
      "command": "openapi-atlas-mcp",
      "args": ["serve"]
    }
  }
}
```

## Configuration reference

The config file (`.openapi-atlas.json` or path via `OPENAPI_ATLAS_CONFIG` env var):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `services` | `ServiceConfig[]` | Yes | One or more backend services to aggregate |
| `auth` | `AuthConfig \| null` | No | Global default auth (overridable per-service) |
| `allow_insecure_http_hosts` | `string[]` | No | Hosts allowed for plain HTTP (e.g. `["localhost"]`) |
| `cache.spec_ttl_seconds` | `int` | No | Spec cache TTL in seconds (default: 60) |
| `cache.disk_cache_dir` | `string \| null` | No | Custom disk cache directory |

### ServiceConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Unique service identifier |
| `url` | `string` | Yes | Base URL of the service (must include scheme) |
| `spec_path` | `string \| null` | No | Explicit spec path (e.g. `/api/openapi.json`). Auto-discovered if omitted. |
| `auth` | `AuthConfig \| null` | No | Per-service auth override |

### AuthConfig

Secrets are referenced **by env-var name** — never inline. See [`docs/auth.md`](docs/auth.md) for patterns.

| Type | Required fields | Behavior |
|------|----------------|----------|
| `none` | (none) | No auth headers sent |
| `bearer` | `token_env` | Sends `Authorization: Bearer <env value>` |
| `basic` | `username_env`, `password_env` | Sends `Authorization: Basic <base64>` |
| `headers` | `headers_env` | Sends custom headers from a JSON env var |

## Tools

| Tool | Description |
|------|-------------|
| `search_endpoints` | Keyword-search operations across all services. Returns ranked matches with scores. |
| `get_endpoint_detail` | Returns the fully `$ref`-resolved schema for one endpoint. |
| `list_services` | Lists all configured services with health, version, and freshness metadata. |
| `refresh_specs` | Force a fresh fetch of one or all services. Clears caches. |

## When things go wrong

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| `ConfigNotFoundError` | No `.openapi-atlas.json` found | Run `openapi-atlas-mcp init` or set `OPENAPI_ATLAS_CONFIG` |
| `MissingEnvVarError` | Referenced env var not set | `export BILLING_API_TOKEN=...` |
| `InsecureHttpHostError` | Plain HTTP to non-localhost | Add host to `allow_insecure_http_hosts` |
| Service shows `unhealthy` | Service unreachable | Check URL, auth, and network connectivity |
| Service shows `degraded` | Serving stale cache | Service was up before; check if it restarted |
| Empty search results | No services indexed yet | Call `refresh_specs` or check service health |

See [`docs/errors.md`](docs/errors.md) for the full warning catalog.

## License

MIT
