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 接口添加身份驗證。
• 啟用速率限制以防止拒絕服務攻擊。