Metadata-Version: 2.4
Name: mcp-swagger-ui
Version: 0.1.0
Summary: Swagger-like docs UI for FastMCP tools, prompts, and resources.
Author: mcp-swagger-ui contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/mcp-swagger-ui
Project-URL: Repository, https://github.com/your-org/mcp-swagger-ui
Project-URL: Issues, https://github.com/your-org/mcp-swagger-ui/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: uvicorn>=0.29.0; extra == "dev"
Dynamic: license-file

# mcp-swagger-ui

Swagger UI style documentation for MCP `FastMCP` servers.

## Features

Given an `mcp.server.fastmcp.FastMCP` instance, this package:

- inspects registered tools, prompts, resources, and resource templates
- generates an OpenAPI-like JSON document
- serves the same Swagger UI style as FastAPI `/docs`
- supports optional auth for docs endpoints

## Installation

```bash
pip install mcp-swagger-ui
```

For local development:

```bash
cd mcp_swagger_ui
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```

## Quickstart

```python
from fastapi import FastAPI, HTTPException, Header
from mcp.server.fastmcp import FastMCP
from mcp_swagger_ui import mount_mcp_docs

# your FastMCP instance
mcp = FastMCP("My MCP Server")

app = FastAPI()

def docs_auth(x_api_key: str | None = Header(default=None)) -> None:
    if x_api_key != "secret-docs-key":
        raise HTTPException(status_code=401, detail="Unauthorized")

mount_mcp_docs(
    app,
    mcp,
    mount_path="/mcp-docs",
    title="My MCP Server Docs",
    auth_dependency=docs_auth,  # optional
)
```

Then open:

- `http://localhost:8000/mcp-docs`
- `http://localhost:8000/mcp-docs/openapi.json`

## API

- `mount_mcp_docs(app, mcp, mount_path="/mcp-docs", title="MCP Docs", version="1.0.0", auth_dependency=None) -> None`
- `create_docs_router(mcp, title="MCP Docs", version="1.0.0", openapi_path="/openapi.json", auth_dependency=None) -> APIRouter`

## Compatibility

- FastMCP API alignment:
  - Uses official server methods first: `list_tools()`, `list_prompts()`, `list_resources()`, `list_resource_templates()`
  - Handles async and sync method returns
  - Uses converter helpers (`to_mcp_tool()`, `to_mcp_prompt()`, `to_mcp_resource()`) when available
- A generic fallback introspection path is still present for compatibility with FastMCP-adjacent objects.
- The generated schema is OpenAPI-like (not a strict operation execution contract), focused on discoverability/documentation.

## Important

- This package targets the `mcp` SDK FastMCP import path:
  - `from mcp.server.fastmcp import FastMCP`
- If you are using standalone `fastmcp`, this package will still usually work due to API overlap.

## Publishing

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```
