骨架MCP服务器
用于构建具有Supabase集成、适当身份验证和模块化架构的MCP（模型上下文协议）服务器的生产就绪框架。
特性
- ✅ 模块化架构（独立的处理程序、工具、实用程序）
- ✅ 使用OAuth流进行Supabase身份验证
- ✅ MCP的SSE（服务器发送事件）传输
- ✅ 正确的错误处理和记录
- ✅ 数据库架构验证
- ✅ RLS（行级安全）支持
- ✅ 系统化服务配置
- ✅ 基于环境的配置
项目结构
skeleton-mcp-server/
├── server.py # Main server file
├── handlers/ # Tool handlers (business logic)
│ ├── __init__.py
│ └── example_handlers.py
├── tools/ # Tool definitions (MCP interface)
│ ├── __init__.py
│ └── example_tools.py
├── utils/ # Utility functions
│ ├── __init__.py
│ ├── auth.py # Authentication utilities
│ └── database.py # Database utilities
├── tests/ # Test files
├── docs/ # Documentation
│ └── SCHEMA_GUIDE.md
├── .env.example # Environment variables template
├── requirements.txt # Python dependencies
└── systemd/ # Systemd service files
└── mcp-server.service快速开始
- 克隆存储库
- 复制
.env.example向.env并配置 - 安装依赖项：
pip install -r requirements.txt - 运行服务器：
python server.py
纳入关键学习内容
1.数据库模式匹配
- 始终验证数据库列名是否与处理程序字段名匹配
- 常见问题：
- name 兽医 company_name 兽医 vendor_name - email 兽医 main_email 兽医 contact_email - tax_amount 兽医 gst_amount - total 兽医 total_amount 兽医 line_total
2.身份验证流程
- 支持OAuth和直接令牌验证
- 处理Claude的令牌缓存行为
- Claude.ai的正确CORS配置
3.SSE实施
- SSE流媒体的正确标头
- 正确的错误响应格式
- 正确处理MCP协议方法
4.模块化架构
- 独立关注点：工具（接口）与处理程序（逻辑）
- 无需修改核心服务器即可轻松添加新工具
- 集中错误处理
添加新工具
- 在中定义工具架构
tools/your_tools.py - 在中实现处理程序
handlers/your_handlers.py - 分别注册
__init__.py文件 - 重新启动服务器
环境变量
看 .env.example 对于所有必需的变量：
SUPABASE_URL：您的Supabase实例URLSUPABASE_SERVICE_KEY：服务角色密钥（完全访问）SUPABASE_ANON_KEY：匿名密钥（公共访问）DATABASE_URL：直接数据库连接（如果需要）SERVER_PORT：运行服务器的端口（默认值：8080）
数据库设置
- 确保您的Supabase表存在
- 启用RLS策略以确保安全
- 在中记录您的架构
docs/SCHEMA_GUIDE.md
部署
看 systemd/mcp-server.service 用于systemd的生产部署。
常见问题及解决方案
- “找不到列”错误：检查实际数据库架构与处理程序字段
- 身份验证失败：确保为Claude.ai配置了CORS
- SSE连接中断：检查响应标头并保持活动设置
- 令牌验证失败：可能需要临时处理缓存的令牌
许可证
麻省理工学院