AI导哈

Swagger UI文档生成工具

为FastMCP服务器生成Swagger UI风格的API文档，支持工具、提示和资源的自动发现与展示。

  • by VasuDevAiNamaha
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 VasuDevAiNamaha/mcp_swagger_ui

使用说明

mcp大摇大摆ui

MCP的Swagger UI风格文档 FastMCP 服务器。

特性

给定一个 mcp.server.fastmcp.FastMCP 实例，此包：

  • 检查已注册的工具、提示、资源和资源模板
  • 生成类似OpenAPI的JSON文档
  • 提供与FastAPI相同的Swagger UI风格 /docs
  • 在Swagger参数列表中直接显示工具和提示参数
  • 在生成的文档中突出显示必需参数和可选参数
  • 支持文档端点的可选身份验证

安装

pip install mcp-swagger-ui

对于当地发展：

cd mcp_swagger_ui
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

快速入门

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
)

然后打开：

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

文档显示什么

生成的文档以可发现性为重点，当前文档为：

  • 工具说明
  • 提示性描述
  • 参数名称、类型、默认值和所需状态
  • 响应模式摘要（如果可用）

工具、提示和资源按Swagger标记分组，而显示的路径仅使用项目名称，例如 /search_users 或 /summarize_text.

测试

该项目包括 pytest 该套件具有覆盖执行功能。

发布流程

此存储库遵循自动化的开源发布流程：

  • 拉取请求运行CI
  • 发布准备在维护者控制的发布分支中进行
  • 发布PR必须包括版本和更改日志更新
  • 发布到PyPI只发生在推送 v* 与上的包版本匹配的标记 master

贡献者指南：

  • 在需要时，将面向用户的更改记录在PR和文档中
  • 除非工作是明确的发布准备，否则不要手动编辑正常功能PR的版本

维护指南：

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

兼容性

  • FastMCP API校准：
    • 首先使用官方服务器方法： list_tools(), list_prompts(), list_resources(), list_resource_templates()
    • 处理异步和同步方法返回
    • 使用转换器助手(to_mcp_tool(), to_mcp_prompt(), to_mcp_resource())如果可用
  • 为了与FastMCP相邻对象兼容，仍然存在通用的回退自检路径。
  • 生成的模式类似于OpenAPI，侧重于可发现性/文档。
  • 此包中尚未实现对已安装的MCP JSON-RPC端点执行工具。

重要

  • 此套餐针对的是 mcp SDK FastMCP导入路径：
    • from mcp.server.fastmcp import FastMCP
  • 如果您使用的是单机版 fastmcp，由于API重叠，此程序包通常仍然有效。

出版

发布是通过GitHub Actions从GitHub Release自动完成的。

初始存储库设置仍然需要：

  • 为此存储库配置PyPI可信发布
  • 可选地保护 pypi GitHub环境

相关 MCP