Production MCP Template

一个偏生产级、可扩展、可直接二次开发的 Python MCP 服务模版。它不是单文件 demo，而是围绕最新 MCP 官方 Python SDK、当前 Streamable HTTP 规范、远程发布形态、认证钩子、可观测性、后台任务、资源/提示/工具分层做出的完整工程骨架。

设计目标

• 使用官方 mcp Python SDK 的稳定 v1.x 能力，而不是临时 API。
• 默认面向远程部署：Streamable HTTP + json_response + stateless_http。
• 保留 stdio 兼容，方便本地接入 Claude / Inspector / 其他 MCP host。
• 工具、资源、提示、服务层、传输层、认证层清晰分离。
• 提供健康检查、readiness、Prometheus metrics、server.json、Docker、CI、类型检查和测试。
• 演示 MCP 新能力的落点：structured output、elicitation、sampling、resource templates、completion、event replay。

已实现能力

1. 核心工程骨架

• src/mcp_template/app
  • 容器、生命周期、Server Factory。
• src/mcp_template/services
  • 纯服务层，承载业务逻辑，不直接依赖传输协议。
• src/mcp_template/modules
  • MCP capability 层，负责注册 tools/resources/prompts。
• src/mcp_template/security
  • Token verifier 与认证装配。
• src/mcp_template/transport
  • SQLite event store，用于 Streamable HTTP 的重放与恢复准备。
• src/mcp_template/types
  • 所有结构化返回模型。

2. 内置模块

• system
  • 健康检查、echo、能力目录、构建信息资源、系统提示。
• workspace
  • 安全的只读工作区扫描、文本读取、资源清单。
• jobs
  • 后台任务提交、状态查询、任务资源模板、postmortem prompt。
• design
  • 功能 brief 采集、工具契约设计、host sampling 示例、生产准备模板资源。

3. 生产配套

• Streamable HTTP 与 stdio 双传输。
• DNS rebinding 防护与 Origin/Host allowlist。
• JWT / static bearer 两种 verifier 装配路径。
• healthz、readyz、metrics、manifest、server.json。
• SQLite event replay store。
• ruff + mypy + pytest + GitHub Actions。
• Dockerfile、.env.example、Makefile、server.json。

为什么这套模版偏“当前最优实践”

这份模版刻意吸收了近一段时间 MCP 官方和社区里最值得保留的思路：

• 优先使用官方 SDK 的 FastMCP 稳定能力，而不是依赖不确定封装。
• 默认使用 Streamable HTTP，并保留 stdio，适配本地 host 与远程部署双场景。
• 把“协议层”与“业务层”拆开，避免工具函数直接长成不可测试的业务体。
• 让 structured output 成为默认，而不是把一切结果都塞进字符串。
• 把认证、事件重放、后台任务、可观测性当成一等公民，而不是上线前才补。
• 把 elicitation 和 sampling 作为未来高级能力保留入口。

快速开始

1. 安装

uv sync --all-groups

2. 配置

cp .env.example .env

3. 运行诊断

uv run mcp-template doctor

4. 运行 HTTP 模式

uv run mcp-template run --transport streamable-http

默认监听：

• Host: 127.0.0.1
• Port: 8000
• MCP endpoint: /mcp

5. 运行 stdio 模式

uv run mcp-template run --transport stdio

与 Host / Inspector 联调

Claude Code / Claude

claude mcp add --transport http mcp-template http://localhost:8000/mcp

MCP Inspector

npx -y @modelcontextprotocol/inspector

然后连接：

http://localhost:8000/mcp

常用命令

uv run mcp-template show-config
uv run mcp-template doctor
uv run mcp-template run --transport stdio
uv run mcp-template run --transport streamable-http
uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest

或者：

make sync
make fmt
make lint
make test
make run-http
make run-stdio
make doctor

配置说明

关键环境变量如下：

• MCP_TEMPLATE_DEFAULT_TRANSPORT
  • stdio / sse / streamable-http
• MCP_TEMPLATE_JSON_RESPONSE
  • 是否为 Streamable HTTP 返回 JSON response
• MCP_TEMPLATE_STATELESS_HTTP
  • 是否启用 stateless 模式
• MCP_TEMPLATE_EVENT_STORE_BACKEND
  • none / sqlite
• MCP_TEMPLATE_EVENT_STORE_PATH
  • SQLite 事件库路径
• MCP_TEMPLATE_ENABLED_MODULES
  • 启用哪些 capability 模块
• MCP_TEMPLATE_AUTH_MODE
  • none / static-bearer / jwt
• MCP_TEMPLATE_AUTH_ISSUER_URL
  • 认证发行方
• MCP_TEMPLATE_AUTH_RESOURCE_SERVER_URL
  • 资源服务器 URL
• MCP_TEMPLATE_JWT_JWKS_URL
  • JWT 验签 JWKS 地址

项目结构

.
├── .github/workflows/ci.yml
├── CLAUDE.md
├── Dockerfile
├── Makefile
├── server.json
├── src/mcp_template
│   ├── app
│   ├── core
│   ├── modules
│   ├── security
│   ├── services
│   ├── transport
│   ├── types
│   ├── cli.py
│   └── config.py
└── tests

如何扩展

新增一个业务模块

1. 在 src/mcp_template/modules/ 下新增模块文件。
2. 在模块里实现 register(server, container) -> ModuleDescriptor。
3. 把工具逻辑放入 services/，不要直接堆在 tool 函数里。
4. 在 src/mcp_template/modules/__init__.py 注册。
5. 写对应测试。

接入真实外部系统

推荐路径：

1. 在 services/ 新增客户端或仓储层。
2. 用 tenacity 包装重试。
3. 设定 timeout、错误分类和结构化输出。
4. 如果有副作用，明确 tool annotation 和鉴权边界。

增加远程认证

推荐路径：

1. 保持 AuthSettings 与 verifier 解耦。
2. 优先接入标准 issuer + JWKS。
3. 作用域设计要贴近真实操作边界。
4. 不要把“静态 token”当成真正生产方案。

健康与运维接口

• GET /healthz
  • 进程级健康与模块状态。
• GET /readyz
  • 就绪探针。
• GET /metrics
  • Prometheus 指标。
• GET /manifest
  • 运行时 manifest。
• GET /server.json
  • Registry 风格输出。

当前测试状态

已验证：

• ruff check
• mypy src
• pytest

后续建议

如果你要把这个模版推进到更重的企业场景，建议继续演进：

• OpenTelemetry tracing / metrics exporter
• Redis 或 Postgres event store
• 多租户鉴权与 header variable 注入
• MCP Apps / ui:// 资源
• 更完整的 OAuth Authorization Server provider
• 更强的审计日志与策略引擎

设计依据与参考

这份模版主要基于以下官方资料与实现方向：

• MCP Python SDK（稳定 v1.x）：https://github.com/modelcontextprotocol/python-sdk
• MCP Transport 规范（2025-11-25，Streamable HTTP 与安全要求）：https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
• MCP Registry Remote Servers / server.json：https://modelcontextprotocol.io/registry/remote-servers

如果你希望，我还可以在这份模版上继续扩展：

• 多租户 SaaS 版本
• 接入真实数据库 / Redis / S3 / Queue
• OAuth 资源服务器完整实现
• MCP Apps 前端壳层
• 面向某个具体业务域的企业级 server 脚手架