MCP 向量同步

MCP 服务，用于通过 100% 基于事件的系统，将多租户搜索向量自动与 Supabase 同步。

描述

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

特性

• 100% 基于事件的系统（直接来自 Supabase 的 Webhook）
• 使用 OpenAI 生成嵌入
• 立即处理项目更改
• 具有指数退避的自动重试系统
• 用于调试和监控的审计日志
• 具有完全数据隔离的多租户同步
• 用于控制和监控的 MCP 工具公开
• 用于监控的健康检查服务器
• 使用 Docker 进行容器化，易于部署
• 兼容 Railway，可在生产环境中部署

事件架构

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

1. Supabase 中的触发器：当创建或修改项目时，触发器会将 Webhook 直接发送到服务
2. 受控延迟处理：对于新的插入，应用 20 秒的延迟以避免竞争条件
3. 自动重试：如果发生故障，系统将使用指数退避（2、4、8 秒）重试最多 3 次
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

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 上创建一个存储库并上传代码：

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

2. 如果还没有，请在 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 端点

系统在以下端点接收 Webhook：

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

Webhook 的预期有效负载应包括：

{
  "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 的服务角色密钥仅具有必要的权限
• 在生产环境中，考虑为 Webhook 实施身份验证
• 配置速率限制以防止 DoS 攻击