Python MCP Server Kit

这是一个后端专用的入门套件，用于构建安全、类型化且可测试的 Model Context Protocol 服务器。它通过官方 Python SDK v2 面向 MCP 2026-07-28 协议，并使用无状态的 Streamable HTTP 进行部署。

Features

• 类型化工具，带结构化 Pydantic 输出

• 通用计算器和确定性目录示例

• MCP 工具、资源和提示词

• Bearer-token 边界与工具级作用域

• 请求大小、主机和进程内速率限制

• 关联 ID 和结构化请求日志

• 公开的健康与就绪探针

• 单元测试和 HTTP 集成测试

• 生产风格的非 root Docker 镜像

• 用于 lint、格式化、类型检查、测试、镜像构建、密钥和工作流的 CI

Related MCP server: MCP TypeScript SDK

Architecture

HTTP request
  -> SecurityMiddleware (host, size, auth, rate limit, request ID)
  -> MCP Streamable HTTP transport
  -> typed tool/resource/prompt
  -> scope check
  -> deterministic domain function

协议注册位于 src/mcp_server_kit/server.py；可复用的领域逻辑保留在独立模块中。TokenStore 有意设计为可替换的部署边界，而不是完整的授权服务器。

快速开始

需要 Python 3.11 或更高版本。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\scripts\dev.ps1

MCP 端点为 http://127.0.0.1:8000/mcp。健康探针位于 /health 和 /ready。仅限本地的演示令牌如下：

• demo-reader — catalog:read

• demo-operator — catalog:read, calculator:use

使用 npx -y @modelcontextprotocol/inspector 运行 MCP Inspector，并设置 Authorization: Bearer demo-operator 请求头。在 examples/client.json 中提供了免凭据的客户端配置模板；可在本地注入 MCP_CLIENT_TOKEN。

命令

.\scripts\dev.ps1    # development server with reload
.\scripts\check.ps1  # lint, format check, mypy, and tests
docker compose up --build

配置

切勿提交 .env。在进行面向互联网的部署之前，请参阅安全和部署；在扩展注册表时，请参阅添加工具。

部署说明

请设置 MCP_ENVIRONMENT=production、MCP_AUTH_MODE=bearer、由密钥管理的 MCP_BEARER_TOKENS 值，以及精确的公共主机白名单。在受信任的反向代理处终止 TLS。当需要用户委托或令牌生命周期管理时，请将入门套件中的令牌存储替换为你自己的 OAuth 2.1 资源服务器验证器。

许可证

MIT