loading…
Search for a command to run...
loading…
A production-grade, extensible Python template for building Model Context Protocol servers with support for Streamable HTTP and stdio transports. It provides a
A production-grade, extensible Python template for building Model Context Protocol servers with support for Streamable HTTP and stdio transports. It provides a structured framework for implementing tools, resources, and prompts with built-in authentication, observability, and background task management.
一个偏生产级、可扩展、可直接二次开发的 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。server.json、Docker、CI、类型检查和测试。src/mcp_template/appsrc/mcp_template/servicessrc/mcp_template/modulestools/resources/prompts。src/mcp_template/securitysrc/mcp_template/transportsrc/mcp_template/typessystemworkspacejobsdesignStreamable HTTP 与 stdio 双传输。Origin/Host allowlist。healthz、readyz、metrics、manifest、server.json。ruff + mypy + pytest + GitHub Actions。Dockerfile、.env.example、Makefile、server.json。这份模版刻意吸收了近一段时间 MCP 官方和社区里最值得保留的思路：
FastMCP 稳定能力，而不是依赖不确定封装。Streamable HTTP，并保留 stdio，适配本地 host 与远程部署双场景。elicitation 和 sampling 作为未来高级能力保留入口。uv sync --all-groups
cp .env.example .env
uv run mcp-template doctor
uv run mcp-template run --transport streamable-http
默认监听：
127.0.0.18000/mcpuv run mcp-template run --transport stdio
claude mcp add --transport http mcp-template http://localhost:8000/mcp
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_TRANSPORTstdio / sse / streamable-httpMCP_TEMPLATE_JSON_RESPONSEMCP_TEMPLATE_STATELESS_HTTPMCP_TEMPLATE_EVENT_STORE_BACKENDnone / sqliteMCP_TEMPLATE_EVENT_STORE_PATHMCP_TEMPLATE_ENABLED_MODULESMCP_TEMPLATE_AUTH_MODEnone / static-bearer / jwtMCP_TEMPLATE_AUTH_ISSUER_URLMCP_TEMPLATE_AUTH_RESOURCE_SERVER_URLMCP_TEMPLATE_JWT_JWKS_URL.
├── .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
src/mcp_template/modules/ 下新增模块文件。register(server, container) -> ModuleDescriptor。services/，不要直接堆在 tool 函数里。src/mcp_template/modules/__init__.py 注册。推荐路径：
services/ 新增客户端或仓储层。tenacity 包装重试。推荐路径：
AuthSettings 与 verifier 解耦。GET /healthzGET /readyzGET /metricsGET /manifestGET /server.json已验证：
ruff checkmypy srcpytest如果你要把这个模版推进到更重的企业场景，建议继续演进：
ui:// 资源这份模版主要基于以下官方资料与实现方向：
v1.x）：https://github.com/modelcontextprotocol/python-sdk2025-11-25，Streamable HTTP 与安全要求）：https://modelcontextprotocol.io/specification/2025-11-25/basic/transportsserver.json：https://modelcontextprotocol.io/registry/remote-servers如果你希望，我还可以在这份模版上继续扩展：
Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"production-mcp-template": {
"command": "npx",
"args": []
}
}
}