Metadata-Version: 2.4
Name: mcp-swagger-ui
Version: 0.1.3
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/VasuDevAiNamaha/mcp_swagger_ui
Project-URL: Repository, https://github.com/VasuDevAiNamaha/mcp_swagger_ui
Project-URL: Issues, https://github.com/VasuDevAiNamaha/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: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: uvicorn>=0.29.0; extra == "dev"
Dynamic: license-file

# mcp-swagger-ui

[![Upload Python Package](https://github.com/VasuDevAiNamaha/mcp_swagger_ui/actions/workflows/python-publish.yml/badge.svg)](https://github.com/VasuDevAiNamaha/mcp_swagger_ui/actions/workflows/python-publish.yml)

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`
- shows tool and prompt arguments directly in Swagger parameter lists
- highlights required vs optional arguments in generated 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 ".[dev]"
```

## 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`

## What The Docs Show

The generated docs are discoverability-focused and currently document:

- tool descriptions
- prompt descriptions
- argument names, types, defaults, and required status
- response schema summaries when available

Tools, prompts, and resources are grouped by Swagger tags, while the displayed paths use only the item names such as `/search_users` or `/summarize_text`.

## Testing

This project includes a `pytest` suite with coverage enforcement.

- minimum coverage: `90%`
- configured in: [pyproject.toml](./pyproject.toml)
- command guide: [TESTING.md](./TESTING.md)

## Release Process

This repository follows an automated open-source release flow:

- pull requests run CI
- release preparation happens in a maintainer-controlled release branch
- release PRs must include version and changelog updates
- publishing to PyPI happens only from a pushed `v*` tag that matches the package version on `master`

Contributor guidance:

- keep user-facing changes documented in the PR and in docs when needed
- do not manually edit versions for normal feature PRs unless the work is explicitly release preparation

Maintainer guides:

- release process details: [RELEASING.md](./RELEASING.md)
- test and local commands: [TESTING.md](./TESTING.md)

## 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 and focused on discoverability/documentation.
- Tool execution against an already-mounted MCP JSON-RPC endpoint is not implemented in this package yet.

## 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

Publishing is automated from GitHub Releases via GitHub Actions.

Initial repository setup still requires:

- configuring PyPI Trusted Publishing for this repository
- optionally protecting the `pypi` GitHub environment
