Barebones MCP Server (Navtejdhillon)

骨架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

快速开始

1. 克隆存储库
2. 复制 .env.example 向 .env 并配置
3. 安装依赖项： pip install -r requirements.txt
4. 运行服务器： 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.模块化架构

• 独立关注点：工具（接口）与处理程序（逻辑）
• 无需修改核心服务器即可轻松添加新工具
• 集中错误处理

添加新工具

1. 在中定义工具架构 tools/your_tools.py
2. 在中实现处理程序 handlers/your_handlers.py
3. 分别注册 __init__.py 文件
4. 重新启动服务器

环境变量

看 .env.example 对于所有必需的变量：

• SUPABASE_URL：您的Supabase实例URL
• SUPABASE_SERVICE_KEY：服务角色密钥（完全访问）
• SUPABASE_ANON_KEY：匿名密钥（公共访问）
• DATABASE_URL：直接数据库连接（如果需要）
• SERVER_PORT：运行服务器的端口（默认值：8080）

数据库设置

1. 确保您的Supabase表存在
2. 启用RLS策略以确保安全
3. 在中记录您的架构 docs/SCHEMA_GUIDE.md

部署

看 systemd/mcp-server.service 用于systemd的生产部署。

常见问题及解决方案

1. “找不到列”错误：检查实际数据库架构与处理程序字段
2. 身份验证失败：确保为Claude.ai配置了CORS
3. SSE连接中断：检查响应标头并保持活动设置
4. 令牌验证失败：可能需要临时处理缓存的令牌

许可证

麻省理工学院