MCP Vector Sync

用于通过完全基于事件的系统与Supabase进行多租户搜索向量自动同步的MCP服务。

描述

当proyectos表发生变化时，此服务会实时接收来自Supabase的通知，使用OpenAI生成向量嵌入，并更新proyecto_vector表，为每个租户保持高效的向量搜索。它实现了MCP（模型上下文协议）以暴露同步工具和资源。

特性

• 完全基于事件的系统（直接从Supabase发出webhook）
• 使用OpenAI生成嵌入
• 对项目变更即时处理
• 带有指数退避的自动重试机制
• 用于调试和监控的审计日志
• 具有完整数据隔离的多租户同步
• 暴露MCP工具以实现控制和监控
• 用于监控的健康检查服务器
• Docker容器化以便于部署
• 支持Railway进行生产环境部署

事件架构

该系统采用完全基于事件的架构：

1. Supabase触发器：当创建或修改一个项目时，触发器直接将webhook发送给服务。
2. 受控延迟处理：对于新插入的数据，应用20秒的延迟以避免竞态条件。
3. 自动重试：在失败情况下，系统最多重试3次，每次间隔时间按指数增加（2、4、8秒）。
4. 审计日志记录：所有尝试都会被记录在webhook_logs表中，以便于调试和监控。

要求

• Node.js >= 18
• 包含proyectos表和proyecto_vector表的Supabase
• OpenAI API密钥
• Docker（用于部署）

配置

服务使用环境变量进行配置：

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

# OpenAI
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=text-embedding-ada-002

# Rate Limiting
RATE_LIMIT_PER_TENANT=100
CONCURRENT_REQUESTS=5

# Logging
LOG_LEVEL=info

本地开发

1. 安装依赖项：

npm install

1. 配置环境变量（在项目根目录下创建.env文件）

2. 以开发模式运行：

npm run dev

Docker

要使用Docker运行服务：

# Construir la imagen
docker build -t mcp-vector-sync .

# Ejecutar el contenedor
docker run -p 3000:3000 --env-file .env mcp-vector-sync

或者使用Docker Compose：

docker-compose up

在Railway上部署

准备

1. 在GitHub上创建一个仓库并上传代码：

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/tu-usuario/mcp-vector-sync.git
git push -u origin main

1. 如果还没有账户，请在Railway上创建一个账户。

部署

1. 在Railway上，从GitHub创建一个新的项目。
2. 选择mcp-vector-sync仓库。
3. Railway将自动检测到Dockerfile。
4. 在“变量”部分配置环境变量。
5. 部署服务。

Railway将使用railway.json文件来配置部署，并使用Dockerfile构建镜像。

监控

一旦部署完成，你可以使用/health端点来监控服务：

https://tu-proyecto.railway.app/health

Webhook端点

系统在以下端点接收webhooks：

https://tu-proyecto.railway.app/webhook/project-update

预期的 webhook payload 应包括：

{
  "inmobiliaria_id": "uuid-del-tenant",
  "project_id": "uuid-del-proyecto",
  "event": "INSERT|UPDATE", 
  "timestamp": "2025-03-22T17:45:00Z"
}

MCP 工具

该服务公开了以下 MCP 工具：

• sync-tenant: 强制同步特定租户
• get-sync-status: 获取租户的同步状态
• control-monitor: 启动或停止同步监控

故障排除

• 如果生成嵌入时出现错误，请检查你的 OpenAI API 密钥
• 对于与 Supabase 连接的问题，请确保 URL 和服务密钥是正确的
• 检查 webhook_logs 中的日志以诊断 webhook 问题
• 可以通过设置 LOG_LEVEL=debug 来启用详细日志

维护

要更新服务：

1. 在代码中进行更改
2. 更新 package.json 中的版本号
3. 将更改提交并推送到 GitHub
4. Railway 将自动检测到更改并重新部署

安全注意事项

• 永远不要在源代码中包含凭证或 API 密钥
• 使用环境变量来存储所有敏感配置
• 确保 Supabase 的服务角色密钥仅具有必要的权限
• 在生产环境中，考虑为 webhooks 实现身份验证
• 设置速率限制（rate limiting）以防止 DoS 攻击