使用说明
MCP服务器——Python示例
A示例 MCP（模型上下文协议） 服务器使用FastAPI实现，并使用Keycloak JSON Web令牌（JWKS）进行身份验证。
备注：本示例是使用MCP官方文档作为参考而设计的https://github.com/modelcontextprotocol/python-sdk.
程序图
目录
特性
需求
| 工具 | 版本 |
|---|---|
| Python | 3.11或更高版本 |
| 诗歌 | ≥1.8(pipx install poetry) |
（可选） uv |
最新(pipx install uv) |
小贴士 –
poetry install自动创建一个隔离的虚拟环境。
入门指南
1.安装依赖项
poetry install
2.运行服务器
选项A-诗歌
# this will create an environment, install dependencies and run the API (auto-reload watches files)
poetry run mcp-server --port 8000
选项B—— uv 命令行界面
# this will create an environment, install dependencies and run the API (auto-reload watches files)
uv run mcp-server --port 8000
选项C–FastAPI CLI（可选）
fastapi run src/mcp_server_python_example/main.py --reload --port 8000
一旦运行，打开 http://localhost:8000/docs 在浏览器中探索交互式Swagger UI。
环境变量
创建一个 .env 项目根目录下的文件（您可以从以下位置复制内容 .env.example):
```dotenv
KEYCLOAK_ISSUER=https://qa-access-key-corp.falabella.tech/realms/test
KEYCLOAK_AUDIENCE=myclient
调整以匹配您的Keycloak领域和客户端。
python-dotenv 启动时自动加载文件。
项目布局
.
├── README.md
├── docs/
│ └── app_diagram.png
├── pyproject.toml
├── poetry.lock
├── src/
│ └── mcp_server_python_example/
│ ├── main.py ← FastAPI root application
│ ├── auth/ ← JWT verification helpers
│ ├── servers/
│ │ ├── echo/ ← Echo MCP service
│ │ └── calculator/ ← Math MCP service
│ └── settings/ ← Config & structured logging
└── tests/
API使用
| 方法 | 路径 | 描述 | 身份验证 |
|---|---|---|---|
| 得到 | /open/ |
健康/公共端点 | ❌ |
| 得到 | /items/ |
退货 sub 来自JWT✅ |
|
| 任何 | /echo/* |
MCP Echo服务流 | ✅ |
| 任何 | /math/* |
MCP计算器服务流 | ✅ |
# Public
curl http://localhost:8000/open/
# Protected
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
http://localhost:8000/items/
测试使用 MCP检查员
MCP Inspector是一个用于测试和调试MCP服务器的交互式开发工具。
- 如上所述运行MCP服务器。
- 运行MCP检查器：
npx @modelcontextprotocol/inspector http://localhost:8000/math/mcp - 在浏览器中打开MCP检查器 http://localhost:3000.
- 通过输入URL连接到服务器
http://localhost:8000/math/mcp. - 测试
/math服务。
预提交设置
此项目使用 pre-commit 在每次提交之前验证代码。确保在本地安装并激活挂钩。
安装
- 安装开发依赖项：
poetry install
- 安装Git钩子：
poetry run pre-commit install
- （可选）手动运行所有检查：
poetry run pre-commit run --all-files
Hooks现在将在每次执行之前自动运行 git commit.
已实现的钩子
秘密检测
该项目使用 detect-secrets 在每次提交之前扫描秘密
生成机密基线（仅一次）:
poetry run detect-secrets scan > .secrets.baseline
git add .secrets.baseline
贡献
欢迎投稿！请随时提交改进或创建新功能的拉取请求。
测试
poetry run pytest -q
许可证
麻省理工学院
