MCP Vector Sync

🚀 MCP ベクトル同期サービス

このサービスは、イベントベースの多テナントリアルタイムベクトル検索自動同期サービスです。Supabase を使用してデータを保存し、OpenAI を通じてベクトル生成機能を提供します。

🚀 クイックスタート

このサービスを使用するには、以下の環境が必要です。

• Node.js >= 18
• Supabase データベースに proyectos と proyecto_vector テーブルが含まれていること
• OpenAI API Key
• Docker のインストール（デプロイ用）

✨ 主な機能

• 完全なイベント駆動：Supabase から直接リアルタイム webhooks 通知を受け取ります。
• OpenAI ベクトル生成：OpenAI API を利用してテキスト埋め込みを生成します。
• リアルタイムプロジェクト変更処理：プロジェクトの作成または更新操作に即座に応答します。
• 自動リトライ機能：指数バックオフアルゴリズムを採用し、最大3回までリトライします。
• 監査ログ記録：すべての操作を詳細に記録し、トラブルシューティングや監視に利用できます。
• 多テナント対応：データを完全に分離します。
• MCP プロトコル対応：MCP プロトコルを通じて同期ツールやリソースにアクセスできます。
• ヘルスチェックサーバーエンドポイント：サービスの状態を監視するために使用します。
• Docker コンテナ化：迅速なデプロイを容易にします。
• Railway 互換性：Railway プラットフォームでのデプロイをサポートします。

🔧 技術詳細

イベントアーキテクチャ

システムはイベントベースのアーキテクチャで設計されています。

1. Supabase トリガー：プロジェクトが作成または更新されると、トリガーが webhooks をサーバーに送信します。
2. 挿入遅延制御：新しいレコードが挿入された後、20秒の遅延を適用して競合状態を回避します。
3. 自動リトライ機能：エラーが発生した場合、指数バックオフ戦略（2、4、8秒）を使用して最大3回自動的にリトライします。
4. 監査ログ：すべての操作は webhook_logs テーブルに記録され、デバッグや監視に便利です。

📦 インストール

ローカル開発

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 設定
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 インターフェースに認証を追加することをお勧めします。
• サービス拒否攻撃を防止するためにレート制限を有効にします。