使用说明
FastMCP OpenAPI自动生成演示
该项目是使用FastMCP在OpenAPI规范中自动创建模型上下文协议（MCP）服务器并提供Swagger UI的演示。
🌟 主要功能
- 自动转换OpenAPI规格：将OpenAPI 3.0规范自动转换为MCP服务器
- 快速API통합：将FastAPI应用程序自动转换为MCP服务器
- 提供Swagger UI：可以在Web浏览器中查看API文档
- 自动测试：自动测试生成的MCP服务器的功能
- 现代化的工具：使用uv、pyproject.toml
🚀 快速入门
1.uv安装（建议）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 또는 pip로 설치
pip install uv
2.项目设置
# 프로젝트 클론 및 디렉토리 이동
git clone <repository-url>
cd fastmcp-openapi-demo
# uv로 가상환경 생성 및 의존성 설치
uv sync
# 또는 개발 의존성까지 포함해서 설치
uv sync --dev
3.运行演示
# 방법 1: uv run으로 직접 실행
uv run python run_demo.py
# 방법 2: 스크립트 명령어 사용
uv run fastmcp-demo
# 방법 3: 가상환경 활성화 후 실행
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
python run_demo.py
🛠️ 设置开发环境
代码质量工具
# 코드 포맷팅
uv run black .
# 린팅
uv run ruff check .
uv run ruff check . --fix # 자동 수정
# 타입 체킹
uv run mypy .
# 테스트 실행
uv run pytest
添加新的依赖性
# 런타임 의존성 추가
uv add package-name
# 개발 의존성 추가
uv add --dev package-name
# 특정 버전 지정
uv add "fastapi>=0.104.0"
📋 已解决的问题
现有问题
- 测试错误:
'list' object has no attribute 'tools' - 异步IO충돌:
Already running asyncio in this thread - MCP端点404:
/mcp无法访问路径 - 包管理：缓慢的pip，复杂的虚拟环境管理
解决方案
- API兼容性增强：添加tools/resources对象类型检查
- 创建独立服务器:
standalone_mcp_server.py通过解决asyncio冲突 - FastAPI集成增强：添加MCP信息端点
- 现代化的工具：使用uv快速管理依赖性
🌐 Web界面
运行FastAPI服务器后，从浏览器连接以下URL：
- 主页: http://localhost:8000
- FastAPI Swagger 用户界面: http://localhost:8000/docs ⭐ 建议
- 커스텀 Swagger用户界面: http://localhost:8000/swagger
- MCP信息: http://localhost:8000/mcp/info
- OpenAPI规格: http://localhost:8000/openapi.json
📋 文件结构
.
├── pyproject.toml # 프로젝트 설정 및 의존성
├── .python-version # Python 버전 지정
├── uv.lock # 의존성 잠금 파일 (자동 생성)
├── openapi_mcp_server.py # 메인 MCP 서버 구현
├── standalone_mcp_server.py # 독립 STDIO MCP 서버
├── test_mcp_client.py # MCP 클라이언트 테스트
├── run_demo.py # 데모 실행 스크립트
└── README.md # 이 문서
🔧 实施方法
1.在OpenAPI规范中创建MCP服务器
from fastmcp import FastMCP
from fastmcp.server.openapi import RouteMap, MCPType
import httpx
# HTTP 클라이언트 생성
client = httpx.AsyncClient(base_url="https://api.example.com")
# OpenAPI 스펙 로드
openapi_spec = {...} # OpenAPI 3.0 스펙
# MCP 서버 생성
mcp = FastMCP.from_openapi(
openapi_spec=openapi_spec,
client=client,
name="My API Server"
)
# 서버 실행
await mcp.run()
2.在FastAPI应用程序中创建MCP服务器
from fastapi import FastAPI
from fastmcp import FastMCP
# FastAPI 앱 생성
app = FastAPI()
@app.get("/items")
def get_items():
return [{"id": 1, "name": "Item 1"}]
# FastAPI를 MCP 서버로 변환
mcp = FastMCP.from_fastapi(app=app)
# 서버 실행
await mcp.run()
🧪 测试
# 모든 테스트 실행
uv run pytest
# 특정 테스트 파일 실행
uv run pytest test_mcp_client.py
# 커버리지 포함 테스트
uv run pytest --cov=. --cov-report=html
🆚 uv vs pip比较
| 功能 | uv | pip |
|---|---|---|
| 速度 | 🚀 速度快10-100倍 | 🐌 慢 |
| 解决依赖关系 | 宣传算法基本信息 | |
| 虚拟环境 | 集成管理 | 需要单独的工具 |
| 锁定文件 | 不存在 | |
| 跨平台 | 分享一致的经验不同平台的差异 |
💡 uv使用技巧
# 프로젝트 초기화
uv init my-project
cd my-project
# Python 버전 설정
uv python pin 3.12
# 의존성 설치 (pyproject.toml 기반)
uv sync
# 스크립트 실행
uv run python script.py
# 패키지 추가/제거
uv add requests
uv remove requests
# 개발 서버 실행
uv run uvicorn app:app --reload
🤝 贡献
- 分叉存储库
- 创建功能分支：
git checkout -b feature/amazing-feature - 使用uv设置开发环境：
uv sync --dev - 运行代码质量工具：
uv run black . && uv run ruff check . - 运行测试：
uv run pytest - 提交更改：
git commit -m 'Add amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 打开Pull Request
📄 许可证
此项目在MIT许可证下分发。
📞 支持
如果有问题或问题，请生成问题。
