Python MCP Server Project

MCP 服务项目

一个安全的 Model Context Protocol（MCP）服务，为 AI Agent 工具执行提供 HTTP 端点。使用 Python 3.12+、Starlette 和 FastMCP 构建。

快速开始

# Clone and setup
git clone https://github.com/sdirishguy/mcp_server_project.git
cd mcp_server_project
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Run server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Test
curl http://localhost:8000/health

Docker

docker-compose up -d
curl http://localhost:8000/health

配置

必需的环境变量：

JWT_SECRET="your-secret-key-32-chars-minimum"    # Required for production
ADMIN_USERNAME="admin"                            # Default admin user
ADMIN_PASSWORD="secure-password"                  # Change from default

可选配置：

SERVER_PORT=8000
MCP_BASE_WORKING_DIR="./shared_host_folder"
ENVIRONMENT="development"                         # development|staging|production
ALLOW_ARBITRARY_SHELL_COMMANDS="false"           # Security: disabled by default
CORS_ORIGINS="http://localhost:3000,https://yourdomain.com"

# API Keys for LLM tools
OPENAI_API_KEY="sk-..."
GEMINI_API_KEY="..."

身份验证

获取令牌：

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

使用令牌：

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/protected

可用工具

工具	描述
file_system_create_directory	创建目录（受沙盒限制）
file_system_write_file	写入文本文件
file_system_read_file	读取文本文件
file_system_list_directory	列出目录内容
execute_shell_command	执行 Shell 命令（经过筛选）
llm_generate_code_openai	通过 OpenAI API 生成代码
llm_generate_code_gemini	通过 Gemini API 生成代码

API 端点

• GET /health - 健康检查
• GET /metrics - Prometheus 指标
• POST /api/auth/login - 身份验证
• POST /mcp/mcp.json/ - MCP JSON-RPC（需要身份验证）
• POST /api/adapters/{type} - 创建数据适配器
• GET /docs - 交互式 API 文档

安全功能

• 基于 JWT 的身份验证，支持配置身份验证提供方
• 防止文件操作中的路径遍历
• Shell 命令筛选和沙盒隔离
• 对身份验证端点进行速率限制
• 安全标头（HSTS、CSP 等）
• CORS 配置
• 对所有操作进行审计日志记录

开发

运行测试：

pytest -q  # 53 passing, 21 skipped (FastMCP lifespan issue)

测试

运行测试：pytest -q（53 项通过，21 项因 FastMCP lifespan 集成而跳过）

被跳过的测试需要适当的 ASGI lifespan 管理，而 TestClient 默认不提供此功能。生产服务运行正常。

代码检查：

pre-commit install
pre-commit run --all-files

生产部署

1. 设置强度足够的 JWT_SECRET（32 个字符以上）
2. 更改默认的 ADMIN_PASSWORD
3. 设置 ENVIRONMENT=production
4. 配置适当的 CORS_ORIGINS
5. 在负载均衡器处终止 HTTPS
6. 监控 /health 和 /metrics 端点

详细检查清单请参阅 PRODUCTION_READINESS_REPORT.md。

架构

• FastMCP：通过 Model Context Protocol 执行工具
• Starlette：带中间件的异步 Web 框架
• Pydantic：配置管理和验证
• Prometheus：指标收集
• JWT：无状态身份验证
• 审计日志：结构化事件日志记录

许可证

MIT