FastAPI-MCP文档生成：自动创建MCP工具说明与使用示例
项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp 痛点：API文档与AI工具集成的鸿沟
你是否遇到过这样的困境？精心设计的FastAPI接口文档在Swagger UI中完美呈现，但当需要将这些API作为AI工具集成到LLM（大语言模型）生态中时，却需要手动编写大量重复的MCP（Model Context Protocol）工具定义代码。这不仅耗时耗力，还容易导致文档与实现不一致的问题。
FastAPI-MCP正是为解决这一痛点而生——它能够自动将你的FastAPI端点转换为标准的MCP工具，实现零配置的AI工具集成。
快速开始：5分钟搭建MCP服务器
安装与基础配置
首先安装FastAPI-MCP包：
uv add fastapi-mcp
# 或者使用pip
pip install fastapi-mcp
基础示例代码
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 创建FastAPI应用
app = FastAPI()
@app.get("/items/", operation_id="list_items")
async def list_items():
"""获取所有项目列表"""
return [{"id": 1, "name": "示例项目"}]
# 创建MCP服务器实例
mcp = FastApiMCP(app)
# 挂载MCP服务器到FastAPI应用
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
启动服务后，你的MCP服务器将在 http://localhost:8000/mcp 可用，所有FastAPI端点已自动转换为MCP工具。
核心功能详解
自动文档转换机制
FastAPI-MCP通过解析OpenAPI schema实现自动转换：
参数类型映射表
| FastAPI参数类型 | MCP Schema类型 | 示例 |
|---|---|---|
path参数 | string | item_id: int → {"type": "string"} |
query参数 | 对应Python类型 | limit: int = 10 → {"type": "integer"} |
requestBody | object属性 | Pydantic模型 → 多个属性字段 |
| Header参数 | string | 自定义头参数 → {"type": "string"} |
响应文档生成
FastAPI-MCP会自动提取响应信息并生成详细的工具描述：
@app.get("/users/{user_id}", response_model=User, operation_id="get_user")
async def get_user(user_id: int):
"""
获取用户详细信息
返回包含用户基本资料和权限信息的完整用户对象
"""
# 实现代码...
生成的MCP工具描述将包含：
- 方法摘要和详细说明
- 成功响应示例
- 错误状态码信息
- 响应数据结构
高级配置选项
工具过滤与定制
mcp = FastApiMCP(
app,
# 只包含特定操作
include_operations=["list_items", "get_item"],
# 或者排除特定标签
exclude_tags=["internal"],
# 详细响应描述
describe_all_responses=True,
describe_full_response_schema=True
)
认证集成
from fastapi_mcp import AuthConfig, OAuthMetadata
auth_config = AuthConfig(
client_id="your-client-id",
issuer="https://your-auth-domain.com",
setup_proxies=True
)
mcp = FastApiMCP(app, auth_config=auth_config)
实际应用场景
电商API示例
from fastapi import FastAPI, Query
from pydantic import BaseModel
from typing import List, Optional
from fastapi_mcp import FastApiMCP
app = FastAPI()
class Product(BaseModel):
id: int
name: str
price: float
category: str
in_stock: bool
@app.get("/products", response_model=List[Product], operation_id="list_products")
async def list_products(
category: Optional[str] = Query(None),
min_price: Optional[float] = Query(None),
max_price: Optional[float] = Query(None)
):
"""根据条件筛选商品列表"""
# 实现筛选逻辑
return filtered_products
@app.get("/products/{product_id}", response_model=Product, operation_id="get_product")
async def get_product(product_id: int):
"""获取单个商品详情"""
# 实现详情查询
return product_details
# 自动转换为MCP工具
mcp = FastApiMCP(app)
mcp.mount_http()
生成的MCP工具文档示例
每个工具都会生成完整的说明文档：
list_products - 根据条件筛选商品列表
根据分类、价格范围等条件筛选商品列表
参数:
- category: string (可选) - 商品分类筛选
- min_price: number (可选) - 最低价格
- max_price: number (可选) - 最高价格
响应:
200: 成功返回商品列表
示例响应:
[
{
"id": 1,
"name": "商品名称",
"price": 99.99,
"category": "电子产品",
"in_stock": true
}
]
部署与最佳实践
生产环境配置
mcp = FastApiMCP(
app,
name="电商平台API工具",
description="提供商品查询、订单管理等AI工具",
# 只转发认证头
headers=["authorization", "x-api-key"]
)
# 使用HTTP传输（推荐）
mcp.mount_http(mount_path="/api/mcp")
# 或者使用SSE传输
mcp.mount_sse(mount_path="/api/mcp-sse")
性能优化建议
- 缓存OpenAPI解析：在频繁调用时缓存解析结果
- 选择性包含：只暴露必要的API端点
- 连接池配置：优化HTTP客户端配置
- 监控与日志：添加详细的运行日志
故障排除与调试
常见问题解决
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 工具未显示 | 缺少operation_id | 为每个路由添加operation_id参数 |
| 参数类型错误 | Schema解析异常 | 检查Pydantic模型定义 |
| 认证失败 | 头信息未转发 | 配置headers参数包含所需头 |
调试模式启用
import logging
logging.basicConfig(level=logging.DEBUG)
总结与展望
FastAPI-MCP通过自动文档生成机制，彻底解决了FastAPI与MCP协议之间的集成难题。它的核心价值体现在：
- 零配置自动化：无需手动编写MCP工具定义
- 文档一致性：确保API文档与AI工具描述完全同步
- 灵活定制：支持多种过滤和配置选项
- 生产就绪：包含认证、监控等企业级功能
随着AI应用生态的快速发展，将现有API系统无缝集成到LLM工作流中已成为刚需。FastAPI-MCP为此提供了最优雅的解决方案，让开发者能够专注于业务逻辑，而非协议转换的繁琐工作。
未来，该库将继续增强对OpenAPI特性的支持，提供更智能的文档生成算法，并优化大规模API系统的性能表现，为构建下一代AI原生应用提供坚实基础。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
