MCP Memory Server with Qdrant Persistence

Qdrant 永続化機能を備えた MCP Memory Server

この MCP サーバーは、Qdrant ベクトルデータベースを活用したセマンティック検索機能を備えるナレッジグラフを実装しています。

機能

• エンティティと関係によるグラフベースのナレッジ表現
• ファイルベースの永続化（memory.json）
• Qdrant ベクトルデータベースを使ったセマンティック検索
• セマンティック類似性のための OpenAI 埋め込み
• HTTPS 対応とリバースプロキシとの互換性
• 簡単にデプロイできる Docker 対応

環境変数

次の環境変数が必要です。

# OpenAI API key for generating embeddings
OPENAI_API_KEY=your-openai-api-key

# Qdrant server URL (supports both HTTP and HTTPS)
QDRANT_URL=https://your-qdrant-server

# Qdrant API key (if authentication is enabled)
QDRANT_API_KEY=your-qdrant-api-key

# Name of the Qdrant collection to use
QDRANT_COLLECTION_NAME=your-collection-name

セットアップ

ローカルセットアップ

1. 依存関係をインストールします。

npm install

2. サーバーをビルドします。

npm run build

Docker セットアップ

1. Docker イメージをビルドします。

docker build -t mcp-qdrant-memory .

2. 必要な環境変数を指定して Docker コンテナを実行します。

docker run -d \
  -e OPENAI_API_KEY=your-openai-api-key \
  -e QDRANT_URL=http://your-qdrant-server:6333 \
  -e QDRANT_COLLECTION_NAME=your-collection-name \
  -e QDRANT_API_KEY=your-qdrant-api-key \
  --name mcp-qdrant-memory \
  mcp-qdrant-memory

MCP 設定に追加する：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/zsh",
      "args": ["-c", "cd /path/to/server && node dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "QDRANT_URL": "http://your-qdrant-server:6333",
        "QDRANT_COLLECTION_NAME": "your-collection-name"
      },
      "alwaysAllow": [
        "create_entities",
        "create_relations",
        "add_observations",
        "delete_entities",
        "delete_observations",
        "delete_relations",
        "read_graph",
        "search_similar"
      ]
    }
  }
}

ツール

エンティティ管理

• create_entities：複数の新しいエンティティを作成します
• create_relations：エンティティ間の関係を作成します
• add_observations：エンティティに観察事項を追加します
• delete_entities：エンティティとその関係を削除します
• delete_observations：特定の観察事項を削除します
• delete_relations：特定の関係を削除します
• read_graph：ナレッジグラフ全体を取得します

セマンティック検索

• search_similar：意味的に類似したエンティティと関係を検索します

  interface SearchParams {
    query: string;     // Search query text
    limit?: number;    // Max results (default: 10)
  }
  

実装の詳細

サーバーは、次の2つの形式で永続化します。

1. ファイルベース（memory.json）：

   • ナレッジグラフの完全な構造
   • グラフ全体への高速アクセス
   • グラフ操作に使用

2. Qdrant ベクトル DB：

   • エンティティと関係のセマンティック埋め込み
   • 類似性検索を可能にします
   • ファイルストレージと自動的に同期されます

同期

エンティティまたは関係が変更されると：

1. 変更内容が memory.json に書き込まれます
2. OpenAI を使って埋め込みが生成されます
3. ベクトルが Qdrant に保存されます
4. 2つのストレージシステムの一貫性が保たれます

検索プロセス

検索時：

1. クエリテキストが埋め込みに変換されます
2. Qdrant が類似性検索を実行します
3. 結果にはエンティティと関係の両方が含まれます
4. 結果はセマンティック類似性に基づいてランク付けされます

使用例

// Create entities
await client.callTool("create_entities", {
  entities: [{
    name: "Project",
    entityType: "Task",
    observations: ["A new development project"]
  }]
});

// Search similar concepts
const results = await client.callTool("search_similar", {
  query: "development tasks",
  limit: 5
});

HTTPS とリバースプロキシの設定

このサーバーは、HTTPS およびリバースプロキシ経由で Qdrant に接続できます。特に次の場合に便利です。

• Nginx や Apache などのリバースプロキシの背後で Qdrant を実行する場合
• 自己署名証明書を使用する場合
• カスタム SSL/TLS 設定が必要な場合

リバースプロキシの設定

1. リバースプロキシを設定します（Nginx を使用した例）：

server {
    listen 443 ssl;
    server_name qdrant.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:6333;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. 環境変数を更新します。

QDRANT_URL=https://qdrant.yourdomain.com

セキュリティに関する考慮事項

このサーバーは、次の機能を備えた堅牢な HTTPS 処理を実装しています。

• カスタム SSL/TLS 設定
• 適切な証明書検証オプション
• 接続プーリングとキープアライブ
• 指数バックオフによる自動再試行
• 設定可能なタイムアウト

HTTPS 接続のトラブルシューティング

接続に問題が発生した場合：

1. 証明書を確認します。

openssl s_client -connect qdrant.yourdomain.com:443

2. 直接接続をテストします。

curl -v https://qdrant.yourdomain.com/collections

3. プロキシ設定を確認します。

env | grep -i proxy

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. プルリクエストを送信します

ライセンス

MIT