# mcp-openapi-query

[![CI](https://github.com/sesopenko/mcp-openapi-query/actions/workflows/ci.yml/badge.svg)](https://github.com/sesopenko/mcp-openapi-query/actions/workflows/ci.yml)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE.txt)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/downloads/)

A [FastMCP](https://github.com/jlowin/fastmcp) server for navigating and querying OpenAPI specifications. Connect any MCP-compatible AI application to this server so it can explore API schemas, resolve `$ref` pointers, and inspect paths and operations without reading an entire spec file at once.

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is an open standard that lets AI assistants call external tools and services. This server implements MCP over HTTP so any MCP-compatible AI application can reach it.

---

## Prerequisites

- **Docker** — for the Docker Compose deployment path
- **uv** — for the source deployment path (see [Installing uv](https://docs.astral.sh/uv/getting-started/installation/))

---

## Quick Start

### Option A — Docker Compose

1. Create a `docker-compose.yml`:

   ```yaml
   services:
     mcp-openapi-query:
       image: sesopenko/mcp-openapi-query:latest
       ports:
         - "8080:8080"
       volumes:
         - ./config.toml:/config/config.toml:ro
       restart: unless-stopped
   ```

2. Copy the example config and edit it:

   ```bash
   cp config.toml.example config.toml
   ```

3. Start the server:

   ```bash
   docker compose up -d
   ```

### Option B — Run from Source

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already.

2. Install dependencies:

   ```bash
   uv sync
   ```

3. Copy the example config and edit it:

   ```bash
   cp config.toml.example config.toml
   ```

4. Start the server:

   ```bash
   uv run python -m mcp_openapi_query
   ```

---

## Security

This server has **no authentication** on its MCP endpoint. It is designed for LAN use only.

**Do not expose this server directly to the internet.**

If you need to access it remotely, place it behind a reverse proxy that handles TLS termination and access control. Configuring a reverse proxy is outside the scope of this project.

---

## Configuration

Create a `config.toml` in the working directory (or pass `--config <path>`):

```toml
[server]
host = "0.0.0.0"
port = 8080

[logging]
level = "info"
```

### [server]

| Key | Default | Description |
|---|---|---|
| `host` | `"0.0.0.0"` | Address the MCP server listens on. `0.0.0.0` binds all interfaces. |
| `port` | `8080` | Port the MCP server listens on. |

### [logging]

| Key | Default | Description |
|---|---|---|
| `level` | `"info"` | Log verbosity. One of: `debug`, `info`, `warning`, `error`. |

---

## Connecting an AI Application

This server uses the **Streamable HTTP** MCP transport. Clients communicate via HTTP POST with streaming responses — opening the endpoint in a browser will return a `Not Acceptable` error, which is expected.

Point your MCP-compatible AI application at the server's MCP endpoint:

```
http://<host>:<port>/mcp
```

For example, if the server is running on `192.168.1.10` with the default port:

```
http://192.168.1.10:8080/mcp
```

Consult your AI application's documentation for how to register an MCP server. Ensure it supports the Streamable HTTP transport (most modern MCP clients do).

---

## Using with Claude Code

### 1. Start the server

Create a `docker-compose.yml` and a minimal `config.toml`, then start the server:

```yaml
services:
  mcp-openapi-query:
    image: sesopenko/mcp-openapi-query:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.toml:/config/config.toml:ro
    restart: unless-stopped
```

```toml
[server]
host = "0.0.0.0"
port = 8080

[logging]
level = "info"
```

```bash
docker compose up -d
```

### 2. Register the MCP server in Claude Code

Add the server to your project's MCP configuration. Run this from your project root:

```bash
claude mcp add --transport http openapi-query http://localhost:8080/mcp
```

Or add it manually to `.claude/settings.json` in your project:

```json
{
  "mcpServers": {
    "openapi-query": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

### 3. Verify the connection

In a Claude Code session, run:

```
/mcp
```

The `openapi-query` server should appear as connected. You can also call `health_check` directly to confirm the server is reachable.

---

## Available Tools

| Tool | Description |
|---|---|
| `health_check` | Returns `{"status": "ok"}` to confirm the server is running. |
| `list_paths` | List all path keys defined in an OpenAPI specification, each with an optional description when present in the Path Item. |
| `get_path_item` | Return the full Path Item object for a specific path. |
| `get_operation` | Return the Operation object for a specific HTTP method and path. |
| `get_spec_version` | Return the specification format version string (e.g. `swagger 2.0`, `openapi 3.0.3`). |
| `list_refs_in_path` | List all `$ref` values and their JSON Pointer locations within a path item. |
| `get_component_schema` | Return a named schema object from `components.schemas`. |
| `list_refs_in_schema` | List all `$ref` values within a schema, resolved by name or `$ref` string. |
| `resolve_ref` | Resolve an internal `$ref` string and return the target object with its canonical pointer. |

---

## Running Tests

```bash
uv run pytest tests/unit/
```

---

## Contributing / Maintaining

See [MAINTAINERS.md](MAINTAINERS.md) for setup, development commands, AI agent rails, and how to run tests.

---

## License

Copyright (c) Sean Esopenko 2026

This project is licensed under the [GNU General Public License v3.0](LICENSE.txt).

---

## Acknowledgement: Riding on the Backs of Giants

This project was built with the assistance of [Claude Code](https://claude.ai/code), an AI coding assistant developed by Anthropic.

AI assistants like Claude are trained on enormous amounts of data — much of it written by the open-source community: the libraries, tools, documentation, and decades of shared knowledge that developers have contributed freely. Without that foundation, tools like this would not be possible.

In recognition of that debt, this project is released under the [GNU General Public License v3.0](LICENSE.txt). The GPL ensures that this code — and any derivative work — remains open source. It is a small act of reciprocity: giving back to the commons that made it possible.

To every developer who ever pushed a commit to a public repo, wrote a Stack Overflow answer, or published a package under an open license — thank you.