MCP Vector Sync

🚀 MCP 向量同步服务

这是一个基于事件的多租户实时向量搜索自动同步服务。它借助 Supabase 进行数据存储，利用 OpenAI 来提供向量生成能力，能高效、稳定地处理多租户的向量同步需求。

🚀 快速开始

环境要求

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

本地开发

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. 根据提示设置必要的环境变量。

✨ 主要特性

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

🔧 技术细节

事件架构

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

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

📦 安装指南

配置参数

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

# 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

💻 使用示例

接口定义

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 接口添加身份验证。
• 启用速率限制以防止拒绝服务攻击。