Python MCP Server Template

🚀 Python MCP 服务模板

几分钟而非几小时，即可创建可用于生产环境的 MCP 服务

使用我们的交互式设置向导，将此模板转换为自定义 MCP 服务。一切都经过集中管理、文档齐全，并已准备好部署到生产环境。

这是一套全面且以安全为先的模板，助你使用 Python 构建 Model Context Protocol (MCP) 服务。借助内置的 Docker 支持、自动化测试和企业级 CI/CD，几分钟即可从零开始构建生产环境就绪的服务。

⚡ 2 分钟搭建 MCP 服务

# 1. Clone and enter directory
git clone https://github.com/aj-geddes/python-mcp-server-template.git
cd python-mcp-server-template

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run interactive setup wizard
python quick_setup.py

# 4. Start your custom MCP server!
python mcp_server.py

就是这样！🎉 你的生产环境就绪的 MCP 服务已启动，并具备：

• ✅ 已配置自定义工具
• ✅ 已启用安全扫描
• ✅ 已准备好通过 Docker 部署
• ✅ 已启用监控和日志记录

---

🎯 非常适合构建

使用场景	工具示例	设置时间
🤖 AI 工具服务	文件处理器、计算器、格式化工具	2 分钟
🔌 API 集成	数据库查询、Web API、云服务	3 分钟
🛠️ 自定义自动化	系统命令、工作流、数据管道	2 分钟
🏢 企业解决方案	安全、可监控、合规的 MCP 服务	5 分钟

✨ 开发者选择此模板的原因

• ⚡ 2 分钟完成设置 - 交互式向导自动配置所有内容
• 🎯 集中式配置 - 所有设置都集中在 config.py 中，而非分散在多个文件里
• 🛠️ 轻松添加工具 - 在 tools/custom_tools.py 中添加工具，并参考示例
• 🔒 内置安全防护 - A+ 级安全保障，支持自动化扫描
• 📊 生产环境就绪 - 内置监控、日志记录、Docker 支持和运行状况检查

🚀 从模板构建你自己的 MCP 服务

交互式设置

python quick_setup.py

向导会询问你：

• 服务名称（例如，“weather-tools-server”）
• 描述（你的服务提供什么功能）
• 品牌信息（名称、电子邮件、代码仓库）
• 工具用途（你要构建哪类工具）

更新项目文件

• config.py - 所有设置都集中在一处
• tools/custom_tools.py - 工具实现模板
• README.md - 已更新为包含你的项目信息

添加工具

# In tools/custom_tools.py
async def my_awesome_tool_impl(param1: str, param2: int) -> Dict[str, Any]:
    # Your tool logic here
    return {"result": f"Processed {param1} with value {param2}"}

随处部署

# Local development
python mcp_server.py

# Production with Docker
docker build -t my-mcp-server .
docker run -p 8080:8080 my-mcp-server

🛠️ 开发

代码质量工具

# Format code
black .
isort .

# Check types
mypy mcp_server/

# Lint code
flake8 mcp_server/

# Security scan
bandit -r mcp_server/

# Run tests
pytest

# Run tests with coverage
pytest --cov=mcp_server --cov-report=html

可用命令

命令	说明
pytest	运行所有测试
pytest -m unit	仅运行单元测试
pytest -m integration	仅运行集成测试
black .	格式化所有 Python 文件
isort .	对导入语句排序
mypy mcp_server/	类型检查
flake8 mcp_server/	代码检查
bandit -r mcp_server/	安全分析
./build.sh	构建并测试 Docker 镜像

🔧 配置

环境变量

变量	默认值	说明
MCP_SERVER_NAME	"template-server"	服务名称标识符
MCP_TRANSPORT	"stdio"	传输类型（stdio、http、sse）
MCP_HOST	"0.0.0.0"	HTTP 传输使用的主机
MCP_PORT	"8080"	HTTP 传输使用的端口
WORKSPACE_PATH	"/workspace"	文件操作的基础路径

安全配置

⚠️ 重要安全说明：

• 默认主机 0.0.0.0 会绑定到所有网络接口。生产环境请使用 127.0.0.1 或特定 IP
• 文件操作仅限于 WORKSPACE_PATH 目录
• 命令执行设有超时限制并进行输入验证
• 所有文件路径都会经过验证，以防止目录遍历攻击

🏗️ 架构

核心组件

mcp_server/
├── __init__.py          # Main server implementation
├── __main__.py          # Module entry point
└── tools/               # Tool implementations (future)

mcp_server.py            # Application entry point
tests/                   # Comprehensive test suite
docker/                  # Docker configurations
scripts/                 # Build and utility scripts

可用工具

工具	描述	安全特性
health_check()	服务健康状态	只读操作
echo(message)	回显功能	输入验证
list_files(directory)	目录列表	路径验证
read_file(file_path)	文件读取	大小限制、路径验证
write_file(file_path, content)	文件写入	路径验证、编码检查
run_shell_command(command)	命令执行	超时限制、沙箱隔离

可用资源

• file://{path} - 通过路径验证安全访问文件资源

可用提示词

• code_review_prompt(code, language, focus) - 用于结构化代码审查的提示词

🐳 Docker 部署

构建选项

# Standard build
./build.sh

# Build with version tag
./build.sh v1.0.0

# Alternative builds
docker build -f Dockerfile.alternative -t mcp-server-alt .
docker build -f Dockerfile.fixed -t mcp-server-fixed .

生产部署

# Run with volume mount
docker run -v /host/workspace:/workspace \
  -e MCP_TRANSPORT=http \
  -e MCP_PORT=8080 \
  -p 8080:8080 \
  python-mcp-server-template:latest

# Run with docker-compose
docker-compose up -d

🧪 测试

测试结构

tests/
├── test_mcp_server.py   # Comprehensive server tests
├── test_server.py       # Additional server tests
└── conftest.py          # Test configuration

测试类别

• 单元测试：测试单个函数
• 集成测试：端到端工作流
• 安全测试：路径验证和命令注入
• 性能测试：超时和资源限制

运行测试

# All tests
pytest

# With coverage
pytest --cov=mcp_server --cov-report=html

# Specific test types
pytest -m unit
pytest -m integration
pytest -m "not slow"

# Verbose output
pytest -v

# Stop on first failure
pytest -x

🔒 安全

安全特性

• 路径验证：防止目录遍历攻击
• 命令沙箱隔离：限制命令执行并设置超时
• 文件大小限制：防止资源耗尽
• 输入验证：全面净化输入
• 环境配置：不硬编码密钥

安全扫描

# Run security analysis
bandit -r mcp_server/

# Check for known vulnerabilities
safety check

# Generate security report
bandit -r mcp_server/ -f json -o security-report.json

📊 监控与可观测性

健康检查

# Check server health
curl http://localhost:8080/health

# Get server status
python -c "from mcp_server import health_check; import asyncio; print(asyncio.run(health_check()))"

日志记录

• 使用 Rich 控制台输出结构化日志
• 可配置日志级别
• 跟踪请求和响应
• 使用堆栈跟踪报告错误

🤝 贡献

开发环境设置

# Install pre-commit hooks
pre-commit install

# Run full quality check
./scripts/quality-check.sh

# Create feature branch
git checkout -b feature/new-tool

贡献指南

1. 安全优先：所有代码都必须通过安全扫描
2. 测试覆盖率：保持测试覆盖率达到 80% 以上
3. 代码质量：通过所有代码检查和类型检查
4. 文档：为新功能更新文档
5. 向后兼容性：不要破坏现有 API

📝 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

📚 文档

🌐 完整文档

指南	描述
🚀 快速入门	5 分钟内运行起来
🔒 安全指南	A+ 级安全特性和最佳实践
🏗️ API 参考	完整的 API 文档
👨‍💻 开发环境设置	贡献与扩展
🐳 Docker 指南	生产环境 Docker 部署

🎓 质量保证

此模板已达到 Dr. Alexandra Chen 的生产标准：

• 🟢 最终评级：良好（B+）- 78/100
• 💎 安全评级：卓越（A+）
• ✅ 生产状态：已获准部署
• 🧪 测试结果：99 项测试通过
• 🔒 安全扫描：安全（0 个漏洞）

🔗 链接

• Model Context Protocol
• FastMCP Framework
• 文档网站
• GitHub Issues
• 贡献指南

🆘 支持

• 📚 完整文档 - 全面的指南和参考资料
• 🐛 Bug 报告 - 报告问题并提出功能请求
• 💬 讨论 - 社区支持与答疑
• 🔒 安全问题 - 请按照 SECURITY.md 中的负责任披露流程处理

---

⭐ 如果这个仓库助你构建出色的 MCP 服务，请为它点亮 Star！