AI导哈

MCP服务器框架

一个用于构建具有Supabase集成、认证和模块化架构的MCP（模型上下文协议）服务器的生产就绪框架。

  • by NavtejDhillon
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 navtejdhillon/barebones-mcp-server

使用说明

骨架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. 令牌验证失败：可能需要临时处理缓存的令牌

许可证

麻省理工学院

相关 MCP