MCP Forge Python - 准备就绪的生产级MCP服务器模板
一个使用Python构建的全面且可投入生产的MCP(模型上下文协议)服务器模板。这是原始MCP Forge Go项目的Python移植版本,具备OAuth 2.0认证、JWT(JSON Web Token)验证功能,并为开发AI驱动应用程序的开发者提供了无缝部署选项。
MCP Forge Python 的关键特性
MCP协议实现
- 用……构建
mcp[cli]支持完整MCP协议的Python库 - 全面的工具、资源和提示实施
- 可配置服务器初始化,包含名称和版本
通信运输
- HTTP 流媒体用于实时网页通信的可流式传输HTTP
内置的MCP工具
服务器包含通过路由器注册的几个MCP工具:
- 你好,世界个性化问候功能(需要
tool:user在HTTP模式下的作用域 - 我是谁基于JWT的用户信息泄露(来自JWT有效载荷)
安全与中间件
- 访问日志记录可配置的请求日志记录,支持头部信息脱敏
- JWT 验证双令牌认证策略
- 使用JWKS URI和CEL表达式进行本地验证
- 外部代理委托(兼容Istio)
- CORS(跨源资源共享)可配置的跨域资源共享
- JWT 上下文在中间件和MCP工具之间安全共享JWT声明
OAuth 2.0 集成(RFC 8414 和 RFC 9728)
- OAuth 授权服务器OpenID Connect 配置代理
- 受保护资源元数据完成OAuth资源发现端点
- OAuth 流程内置用于授权码流程的登录和回调端点
灵活配置
- 基于TOML的配置系统,包含专用部分用于:
- 服务器设置(名称、版本、传输方式)
- 中间件配置(日志记录、JWT、CORS)
- OAuth 集成(授权服务器、受保护资源)
- OAuth 流的认证设置(客户端凭据、重定向 URI)
- JWT声明暴露配置
额外的终点(或:额外的端点)
除了MCP协议端点外,服务器还提供:
- GET /服务器信息
- 获取 /health(或“访问 /health 端点”)健康检查端点
生产就绪部署
- 使用Dockerfile完成Docker容器化
- 用于云部署的Kubernetes Helm图表
- Keycloak、Istio 和 Hashrouter 的集成指南
系统要求
外部依赖
- python大于等于 3.11
- Docker (可选):用于构建镜像
JWT 策略的要求
- “local”策略需要一个 JWKS 服务器 (如Keycloak、Auth0等OAuth提供者)提供JWKS(JSON Web Key Set)端点以获取公钥并验证令牌。在(相关配置中)进行配置
jwks_uri。 - “external”策略(或“外向型”策略)需要一个 上游代理 (如Istio、Envoy或API网关)验证JWT并在头部转发声明。在MCP中不需要JWKS,但代理必须配置为注入头部(例如。
X-Forwarded-User)。
当地要求
-
生产依赖项:
-
fastapiASGI网络框架 uvicorn[standard]支持HTTP流的ASGI服务器pydantic数据验证pydantic-settings从文件中配置tomli适用于Python 3.11之前的TOML解析器mcp[cli]MCP Python SDKhttpx异步HTTP客户端PyJWTJWT 处理requests同步HTTP客户端-
cryptography加密操作 -
开发依赖项:
-
ruff代码检查和格式化 pyright类型检查pytest测试框架pytest-asyncio为 pytest 提供异步支持coverage代码覆盖率pytest-benchmark性能基准测试
安装与设置```bash
Install dependencies
uv sync
Install package (enables direct commands)
uv pip install -e .
Run HTTP server with streaming
uv run http
Alternative: Run stdio server for local AI clients
uv run stdio
## 开发命令```bash
# Testing & Quality
just test # Run all tests
just cov # Run tests with coverage report
just bench # Run benchmarks
just lint # Lint and format code
just typing # Type checking
just check-all # Run all quality checks
# Lifecycle
just install # Install/update dependencies
just update # Update dependencies to latest versions
just clean # Remove all temporary files (.venv, caches, dist)
just clean-cache # Clean caches only (keep .venv)
just fresh # Clean + fresh install
# Running
just run # Run HTTP server
just run-stdio # Run stdio mode
just dev-http # Run HTTP server with MCP Inspector
just dev-stdio # Run stdio server with MCP Inspector
> 注用于开发,请使用 uv pip install -e . 用于可编辑安装。
支持的传输方式
- HTTP 流媒体对于像Claude Web这样的远程客户端。终端
/mcp使用HTTP流进行运行uv run http。
JWT 配置
JWT 中间件支持两种验证策略:
“local”策略
- 在MCP服务器上直接验证JWT。
- 从JWKS端点下载公钥(在配置中指定)
jwks_uri)。 - 支持可配置的缓存和CEL(可能是指某种条件表达式语言或逻辑)条件,以实现高级权限管理。
- MCP工具检查所需的范围(例如。,
tool:user(用于 hello_world)。 - 要求带有JWKS端点的OAuth服务器(例如Keycloak)。
“外部”策略
- 将验证委托给上游代理(如Istio、Envoy等)。
- JWT 被转发到一个特定的头部(
forwarded_header)。 - 代理验证并提取声明,将其注入到请求中。
- 要求已配置代理用于JWT验证和头部转发。
示例在 config.toml。
配置
请看 config.toml 作为配置示例。
认证配置
对于OAuth流程,请配置auth部分:```toml
[auth]
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_uri = "http://localhost:8080/callback"
### CORS 配置
配置跨域资源共享:```toml
[middleware.cors]
allow_origins = ["https://yourdomain.com", "http://localhost:3000"]
allow_credentials = true
allow_methods = ["GET", "POST", "PUT", "DELETE"]
allow_headers = ["*"]
JWT声明泄露
控制哪些JWT声明可供MCP工具访问:```toml
Expose all claims (not recommended for production)
jwt_exposed_claims = "all"
Or expose only specific claims
jwt_exposed_claims = ["user_id", "email", "roles"]
注: `roles` 并且 `scope` 声明总是为了授权目的而公开。
**安全注意事项**默认情况下,服务器运行在 `127.0.0.1` 以避免不必要的暴露。配置主机和端口 `config.toml` 在……下面 `[server.transport.http]`改为 `0.0.0.0` 仅在必要时,并采取适当的安全措施。
## 安全考虑因素
此模板实施了多项安全措施,以防范常见漏洞。作为模板,它被设计为可针对不同部署场景进行配置。
### JWT声明泄露
为了最小化数据暴露,配置哪些JWT声明可供MCP工具访问:```toml
jwt_exposed_claims = ["user_id", "roles"] # Only expose specific claims
# or
jwt_exposed_claims = "all" # Expose all claims (not recommended for production)
注: roles 并且 scope 无论此配置如何,声明始终会为授权目的而公开。
访问日志记录
敏感头信息在日志中会自动进行遮蔽处理:```toml
[logging]
redacted_headers = ["Authorization", "X-API-Key", "Cookie"]
max_body_size = 1024 # Limit logged body size
### 速率限制
为JWT(JSON Web Token)验证实施了基本速率限制,以防止暴力破解攻击。
### URI验证
OAuth和JWKS URI会与白名单域名进行验证,以防止SSRF攻击。
### 确保依赖项安全
依赖项会定期更新以修复已知漏洞。运行 `uv lock --upgrade` 更新到最新的安全版本。
### 生产检查清单
- 使用适当的代理(Istio、Envoy)与“外部”JWT 策略
- 配置最小暴露声明
- 启用带有内容遮蔽的访问日志记录
- 验证所有URI是否属于受信任的域名
- 保持依赖项更新
- 定期进行安全测试
## 文档
- 完整文档 - 完整指南,涵盖开发、配置及贡献指南。
- 开发指南 - 如何将此用作模板。
- 做出贡献 - 贡献者指南。
## 项目架构```
src/mcp_app/
├── main.py # Application entry point and FastAPI setup
├── config.py # Pydantic configuration models
├── context.py # JWT context management for secure claim sharing
├── handlers/ # OAuth endpoints handlers (RFC 8414 & RFC 9728)
├── middlewares/ # Custom middlewares (JWT, access logs, CORS)
└── tools/ # MCP tools and registration router
核心组件
- main.py(主程序文件)初始化FastMCP服务器、FastAPI应用、中间件以及OAuth端点
- config.py(配置文件)基于 TOML 的配置与 Pydantic 模型
- 处理程序/OAuth授权服务器和受保护资源的元数据端点
- 中间件/JWT验证、访问日志记录和CORS处理
- 工具/MCP工具实现及注册系统
发展
贡献;助力
我们欢迎投稿!请参阅 CONTRIBUTING.md(贡献指南文件) 关于如何为该项目做出贡献的指南。
更新日志
许可证
这个项目采用无许可协议(Unlicense)授权——详见 许可证 详情请查阅文件。
