Metadata-Version: 2.5
Name: fastapi-mcp-server
Version: 0.1.0
Summary: A Model Context Protocol (MCP) server functioning as a Full-Stack Context Bridge for FastAPI, APIRouters, and Pydantic codebase introspection.
Project-URL: Homepage, https://github.com/goodluckigbokwe/fastapi-mcp-server
Project-URL: Documentation, https://github.com/goodluckigbokwe/fastapi-mcp-server#readme
Project-URL: Repository, https://github.com/goodluckigbokwe/fastapi-mcp-server
Project-URL: Issues, https://github.com/goodluckigbokwe/fastapi-mcp-server/issues
Author: FastAPI MCP Team
License: MIT
License-File: LICENSE
Keywords: ai,claude,code-generation,cursor,developer-tools,fastapi,mcp,model-context-protocol,pydantic,typescript,vscode,zed,zod
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dev
Requires-Dist: basedpyright>=1.20.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# fastapi-mcp-server

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/fastapi-mcp-server.svg)](https://pypi.org/project/fastapi-mcp-server/)
[![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-mcp-server.svg)](https://pypi.org/project/fastapi-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![FastAPI](https://img.shields.io/badge/FastAPI-009485.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Protocol-blue.svg)](https://modelcontextprotocol.io/)
[![CI](https://github.com/username/fastapi-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/username/fastapi-mcp-server/actions/workflows/ci.yml)

<p><strong>A Model Context Protocol (MCP) server functioning as a Full-Stack Context Bridge for FastAPI, APIRouters, live OpenAPI endpoints, and Pydantic models.</strong></p>

</div>

---

## ⚡ Why this exists: Two Different MCP Paradigms

It is important to distinguish between two completely different uses of MCP with FastAPI:

| Feature / Goal             | `fastapi-mcp` (Execution Tool)                          | `fastapi-mcp-server` (Co-Developer Bridge)                              |
| -------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Primary Goal**           | Enables AI to **call** live endpoints as runtime tools. | Enables AI to **write**, inspect, and synchronize code.                 |
| **Server Requirement**     | Requires a running, live `uvicorn` instance.            | **Zero server needed:** inspects local files on disk (or live URLs).    |
| **Pydantic Model Schemas** | Only exposes parameters for executed calls.             | Extracts full JSON schemas directly from Python `BaseModel` classes.    |
| **Frontend Code Gen**      | Not supported.                                          | **Directly outputs TypeScript interfaces & Zod validation schemas.**    |
| **Project Auto-Discovery** | Manual route registration.                              | **AST scanner catalogs all apps, routers, and models automatically.**   |
| **Ideal For**              | AI agents executing actions in production.              | **Developers & AI assistants writing frontend & backend code in IDEs.** |

---

## 🌟 Key Capabilities

1. **Dual-Mode Introspection:** Inspects local `.py` files directly from disk without running a server, **or** fetches live schemas from deployed staging/production URLs (`https://api.example.com/openapi.json` or `http://localhost:8000/docs`).
2. **Instant TypeScript & Zod Generation:** Converts Pydantic models and OpenAPI schemas into strict, copy-paste ready TypeScript `interface`s and Zod validation schemas with full typing, nullability, and JSDoc comments.
3. **Standalone Router & Sub-Module Support:** Introspects full applications (`main:app`) as well as standalone `APIRouter` files (`routers.users:router`) and factory functions.
4. **Project Auto-Discovery:** Scans backend repositories using AST analysis to catalog every FastAPI app, router, and Pydantic model automatically.
5. **Cross-Repository Context:** Frontend developers working in a separate repository (e.g. Next.js/React) can point their IDE's MCP client to the backend project directory to inspect backend types while writing frontend code.

---

## 📦 Installation & Quickstart

### Using `uvx` (Recommended — no installation needed)

```bash
uvx fastapi-mcp-server
```

### Using `pip`

```bash
pip install fastapi-mcp-server
```

### Running from source

```bash
git clone https://github.com/username/fastapi-mcp-server.git
cd fastapi-mcp-server
uv sync
uv run fastapi-mcp-server
```

---

## 🛠️ Editor & Client Configuration

### Zed IDE

Add to your Zed `settings.json` (`Ctrl + ,` or `Cmd + ,`):

```json
{
  "context_servers": {
    "fastapi-mcp-server": {
      "command": {
        "path": "uvx",
        "args": ["fastapi-mcp-server"]
      }
    }
  }
}
```

_For local workspace development without publishing:_

```json
{
  "context_servers": {
    "fastapi-mcp-server": {
      "command": {
        "path": "uv",
        "args": [
          "run",
          "--directory",
          "/path/to/fastapi-mcp-server",
          "fastapi-mcp-server"
        ]
      }
    }
  }
}
```

### Cursor

Go to **Cursor Settings** > **Features** > **MCP Servers** > **+ Add New MCP Server**:

- **Name:** `fastapi-mcp-server`
- **Type:** `command`
- **Command:** `uvx fastapi-mcp-server`

### VS Code (with MCP / Copilot)

Add to your VS Code user or workspace settings (`settings.json`):

```json
{
  "mcp": {
    "servers": {
      "fastapi-mcp-server": {
        "command": "uvx",
        "args": ["fastapi-mcp-server"]
      }
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fastapi-mcp-server": {
      "command": "uvx",
      "args": ["fastapi-mcp-server"]
    }
  }
}
```

---

## 🧰 Available MCP Tools

### 1. `get_openapi_schema`

Extracts the complete OpenAPI JSON schema from a local FastAPI app, standalone `APIRouter`, factory function, or live deployed HTTP URL.

- `app_path` _(str, required)_: Import target (e.g. `"main:app"`, `"routers.users:router"`, `"src/api.py:app"`) or live URL (`"https://api.example.com/openapi.json"`, `"http://localhost:8000/docs"`).
- `project_dir` _(str, optional)_: Path to the backend project root.

### 2. `get_pydantic_schema`

Extracts the JSON Schema from any Pydantic `BaseModel` class (supporting both Pydantic v2 and v1).

- `model_path` _(str, required)_: Import target (e.g. `"models.user:UserProfile"`, `"src/schemas.py:Item"`).
- `project_dir` _(str, optional)_: Path to the backend project root.

### 3. `list_registered_routes`

Returns a structured catalog of registered routes, HTTP methods, operation IDs, summaries, and tags from an app, standalone router, or live URL.

- `app_path` _(str, required)_: Target app, router, or URL.
- `project_dir` _(str, optional)_: Path to the backend project root.

### 4. `get_typescript_definition`

Directly generates strict TypeScript interfaces and types from a Pydantic model, local app, or remote OpenAPI URL.

- `target` _(str, required)_: Model target (e.g. `"models.user:UserProfile"`), app target (`"main:app"`), or live URL.
- `project_dir` _(str, optional)_: Path to the backend project root.

### 5. `get_zod_schema`

Generates client-side Zod validation schemas (`z.object({...})`) and inferred TypeScript types from a Pydantic model or OpenAPI target.

- `target` _(str, required)_: Model target, app target, or live URL.
- `project_dir` _(str, optional)_: Path to the backend project root.

### 6. `discover_fastapi_project`

Scans a backend project directory using zero-execution AST parsing to catalog all FastAPI instances, APIRouters, and Pydantic models.

- `project_dir` _(str, optional)_: Path to the project directory to scan.

---

## 🛡️ Error Handling

All tools return clean structured JSON dictionaries rather than raising unhandled exceptions or crashing the MCP connection:

```json
{
  "error": "ModuleNotFoundError",
  "detail": "Failed to import module 'src.main'. Searched in sys.path: [...]"
}
```

---

## 🤝 Contributing

We welcome contributions! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for details on setting up the dev environment, running tests, and submitting PRs.

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.
