Metadata-Version: 2.4
Name: mcp-from-openapi
Version: 0.1.0
Summary: Convert OpenAPI 3.x specs into live, working MCP servers
Author: Vinayak Rastogi
License: MIT
Project-URL: Homepage, https://github.com/vinayakrastogi/openAPI-to-MCP-converter
Project-URL: Repository, https://github.com/vinayakrastogi/openAPI-to-MCP-converter
Project-URL: Issues, https://github.com/vinayakrastogi/openAPI-to-MCP-converter/issues
Keywords: openapi,mcp,model-context-protocol,ai,cli,code-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn>=0.30
Requires-Dist: starlette>=0.37
Dynamic: license-file

# openapi-to-mcp

Convert any OpenAPI 3.x spec file into a live, working MCP (Model Context Protocol) server that AI agents can connect to and use as tools.

## What it does
This CLI tool parses an OpenAPI 3.x specification and generates a standalone Python script acting as an MCP server. This allows AI assistants (like Claude, Cursor, or Copilot) to understand and interact with your existing REST APIs by converting your OpenAPI endpoints into MCP tools.

## How it works
1. **Parse**: Reads your OpenAPI specification (YAML or JSON).
2. **Generate**: Uses Jinja2 templates to construct a complete, standalone Python file containing the MCP server logic.
3. **Run**: Provides an option to immediately start the generated MCP server using the stdio or sse transport.

## Installation

```bash
pip install mcp-from-openapi
```

For development:
```bash
git clone https://github.com/vinayakrastogi/openAPI-to-MCP-converter.git
cd openAPI-to-MCP-converter
pip install -e .
```

## Commands

### 1. Inspect endpoints in a spec (dry-run)
Prints a table of all discovered endpoints, their tool names, and parameters without generating any files.

```bash
openapi-to-mcp inspect --spec examples/math_api.yaml
```

### 2. Generate a standalone MCP server
Outputs a ready-to-run Python file (e.g., `output/math_api_mcp_server.py`).

```bash
openapi-to-mcp generate \
  --spec examples/math_api.yaml \
  --base-url http://127.0.0.1:8000
```

### 3. Generate and immediately run
Creates the MCP server file and starts it immediately.

```bash
openapi-to-mcp run \
  --spec examples/math_api.yaml \
  --base-url http://127.0.0.1:8000
```

### 4. Run with Authentication
Injects authentication headers into every request made by the MCP server.

```bash
# Bearer token style:
openapi-to-mcp run \
  --spec examples/pet_api.yaml \
  --base-url https://api.example.com \
  --auth-header "Authorization: Bearer mytoken"

# API key style:
openapi-to-mcp run \
  --spec examples/pet_api.yaml \
  --base-url https://api.example.com \
  --auth-header "X-Api-Key: abc123"
```

## CLI Reference

```
openapi-to-mcp <command> [options]

Commands:
  inspect   Parse a spec and display endpoints (dry-run, no files written)
  generate  Parse a spec and write a standalone MCP server file
  run       Generate AND immediately start the MCP server

Common Options:
  --spec,       -s  FILE    Path to the OpenAPI YAML or JSON spec file [required]
  --base-url,   -u  URL     Base URL of the live API (overrides servers[0].url)
  --auth-header,-a  HEADER  Auth header injected into every request
  --transport,  -t          MCP transport: stdio (default) or sse
  --name,       -n  NAME    Server name (defaults to spec info.title)
  --output,     -o  FILE    Output path for the generated server file
```

## Connecting to AI Agents

### Claude Desktop
Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/absolute/path/to/output/math_api_mcp_server.py"]
    }
  }
}
```

### Cursor / VS Code (Copilot MCP)
Add the following to `.cursor/mcp.json` or your workspace MCP config:

```json
{
  "servers": {
    "my-api": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/output/math_api_mcp_server.py"]
    }
  }
}
```

## Supported OpenAPI Features

| Feature | Status |
|---------|--------|
| OpenAPI 3.x (YAML & JSON) | Supported |
| Path parameters (`in: path`) | Supported |
| Query parameters (`in: query`) | Supported |
| Request bodies (`application/json`) | Supported |
| `$ref` schema resolution | Supported |
| `operationId` as tool name | Supported |
| Fallback tool name from method + path | Supported |
| Auth header injection | Supported |
| `servers[0].url` as base URL | Supported |
| stdio transport | Supported |
| SSE transport | Supported |
| Header parameters | Parsed, not injected (use `--auth-header`) |
| OAuth flows | Not Supported (v2 roadmap) |
| `multipart/form-data` bodies | Not Supported (v2 roadmap) |
