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 脚手架