MCP 向量同步服务

项目描述

这是一个基于事件的多租户实时向量搜索自动同步服务，使用 Supabase 进行数据存储，并通过 OpenAI 提供向量生成能力。

功能特性

• 完全基于事件驱动：直接从 Supabase 接收实时 webhooks 通知
• OpenAI 向量生成：利用 OpenAI API 生成文本嵌入
• 实时项目变更处理：立即响应项目创建或更新操作
• 自动重试机制：采用指数退避算法，最多重试3次
• 审计日志记录：详细记录所有操作以备排查和监控
• 多租户支持：确保数据完全隔离
• MCP 协议支持：通过 MCP 协议提供同步工具和资源的访问
• 健康检查服务器端点：用于服务状态监控
• Docker 容器化：便于快速部署
• Railway 兼容性：支持在 Railway 平台上线

事件架构

系统采用基于事件的架构设计：

1. Supabase 触发器：项目创建或更新时，触发器发送 webhooks 到服务端
2. 插入延迟控制：新插入记录后应用20秒延迟以避免竞态条件
3. 自动重试机制：发生错误时自动重试，最多3次，采用指数退避策略（2、4、8秒）
4. 审计日志：所有操作记录在 webhook_logs 表中，便于调试和监控

环境要求

• Node.js >= 18
• Supabase 数据库包含 proyectos 和 proyecto_vector 表
• OpenAI API Key
• Docker 安装（用于部署）

配置参数

服务通过环境变量进行配置：

# Supabase 配置
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# OpenAI 配置
OPENAI_API_KEY=你的 OpenAI API 密钥
OPENAI_MODEL=text-embedding-ada-002

# 限流配置
RATE_LIMIT_PER_TENANT=100
CONCURRENT_REQUESTS=5

# 日志记录
LOG_LEVEL=info

本地开发

1. 安装依赖：

npm install

2. 创建并编辑 .env 文件，包含所有必要的环境变量。

3. 启动开发模式：

npm run dev

Docker 部署

使用 Docker 构建和运行服务：

# 构建镜像
docker build -t mcp-vector-sync .

# 启动容器
docker run -p 3000:3000 --env-file .env mcp-vector-sync

或使用 Docker Compose：

docker-compose up

Railway 上线

1. 将代码推送到 GitHub 仓库。
2. 配置项目，选择合适的运行环境和依赖管理工具（如 Yarn）。
3. 根据提示设置必要的环境变量。

接口定义

Webhook 数据格式

{
  "event": "sync_project",
  "data": {
    "tenant_id": "string",
    "project_id": "string",
    "timestamp": "2025-03-22T17:45:00Z"
  }
}

MCP 工具

服务提供以下 MCP 工具：

• sync-tenant：强制同步指定租户的数据
• get-sync-status：获取租户的同步状态
• control-monitor：启动或停止同步监控服务

故障排除

• OpenAI 错误：检查 OpenAI API Key 是否有效
• Supabase 连接问题：确认 URL 和 service key 正确性
• Webhook 问题：查看 webhook_logs 表中的日志信息
• 详细日志：设置 LOG_LEVEL=debug 获取更多信息

维护更新

1. 在代码仓库中提交更改。
2. 更新 package.json 中的版本号。
3. 推送修改到 GitHub 仓库，Railway 平台将自动检测并重新部署。

安全注意事项

• 避免在代码中直接嵌入敏感信息如 API 密钥
• 使用环境变量管理所有配置信息
• 确保 Supabase 的 service key 权限最小化
• 在生产环境中建议为 Webhook 接口添加身份验证
• 启用速率限制以防止拒绝服务攻击