🔍 MCP Server - Vector Search

🔍 MCP サーバー - ベクトル検索

FastMCP で構築された、超高速な Model Context Protocol（MCP）サーバーです。Neo4j のグラフデータベース機能と、埋め込みを利用した高度なベクトル検索をシームレスに組み合わせます。このサーバーを使うと、ナレッジグラフ全体を対象にインテリジェントなセマンティック検索を行えます。自然言語でクエリを入力するだけで、文脈に関連する情報を瞬時に見つけられます。

🏗️ アーキテクチャ

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│   Vector Search  │◄──►│      Neo4j      │
│   (Claude AI)   │    │      Server      │    │     Database    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │    Embeddings    │
                       └──────────────────┘

🚀 クイックスタート

前提条件

• Python 3.8+
• uv
• Neo4j データベース（v5.0+）と APOC プラグイン
• OpenAI API キー

uv を使ったインストール

1. uv をインストール（まだインストールされていない場合）

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. プロジェクトをクローンしてセットアップ

   git clone https://github.com/omarguzmanm/mcp-server-vector-search.git
   cd mcp-server-vector-search
   
   # Create virtual environment and install dependencies
   uv venv
   uv pip install fastmcp neo4j openai python-dotenv sentence-transformers pydantic
   

3. 環境設定

   # Create .env file
   cp .env.example .env
   

   .env を編集して、設定を記入します：

   NEO4J_URI=bolt://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your_neo4j_password
   NEO4J_DATABASE=neo4j
   OPENAI_API_KEY=your_openai_api_key
   

4. Neo4j のベクトルインデックスをセットアップ

   // Create vector index for 1536-dimensional OpenAI embeddings
   // If does not works
   CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding)
   OPTIONS {indexConfig: {
     `vector.dimensions`: 1536,
     `vector.similarity_function`: 'cosine'
   }}
   

5. サーバーを起動

   # Activate virtual environment
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   
   # Start the FastMCP server
   python main.py
   

🛠️ ツール

このサーバーは、ベクトル検索に最適化された強力なツールを 1 つ公開します。

🔍 ベクトル検索

vector_search_neo4j(
    prompt="Find documents about machine learning and neural networks"
)

機能：

• 自然言語のクエリを OpenAI を使って 1536 次元のベクトルに変換します
• Neo4j のベクトルインデックスを検索し、意味的に最も類似したノードを見つけます
• 類似度スコア付きのランキング結果を返します

⚙️ 設定

環境変数

変数	説明	必須	デフォルト
NEO4J_URI	Neo4j 接続 URI	✅	bolt://localhost:7687
NEO4J_USERNAME	Neo4j ユーザー名	✅	neo4j
NEO4J_PASSWORD	Neo4j パスワード	✅	password
NEO4J_DATABASE	Neo4j データベース名	✅	neo4j
OPENAI_API_KEY	OpenAI API キー	❌	all-MiniLM-L6-v2 model

Neo4j の要件

1. APOC プラグイン：高度なグラフ操作に必須です
2. ベクトルインデックス：OpenAI の埋め込みに対応するため、1536 次元をサポートする必要があります
3. ノード構造：ノードにはベクトル形式の embedding プロパティが必要です

パフォーマンスの最適化

• uv のメリット：pip と比べて依存関係の解決が 10～100 倍高速です
• FastMCP の利点：オーバーヘッドが最小限で、MCP プロトコルに最適化されています
• コネクションプーリング：Neo4j の接続を自動的に管理します
• 非同期処理：ノンブロッキング I/O により、スループットを最大化します

🤝 Claude Desktop との連携

MCP の設定

Claude Desktop の MCP 設定に追加します：

{
  "mcpServers": {
      "mcp-neo4j-vector-search": {
      "command": "python",
      "args": [
        "you\\server.py",
        "--with",
        "mcp[cli]",
        "--with",
        "neo4j",
        "--with",
        "pydantic"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "OPENAI_API_KEY": "your_api_key"
      }
    }
  }
}

🐛 トラブルシューティング

よくある問題

1. 「Module not found」エラー

   # Reinstall dependencies with uv
   uv pip install --force-reinstall fastmcp neo4j openai
   

2. 「Vector index not found」

   // Check existing indexes
   SHOW INDEXES
   
   // Create if missing
   CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding)
   OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}
   

3. OpenAI API エラー

   # Verify API key
   uv run python -c "
   import os
   from openai import OpenAI
   client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))
   print('API key is valid!' if client.api_key else 'API key missing!')
   "
   

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 開発用依存関係をインストールします：uv pip install -e ".[dev]"
4. 変更を加え、テストを追加します
5. コミットします：git commit -m 'Add amazing feature'
6. プッシュします：git push origin feature/amazing-feature
7. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• FastMCP - 優れた MCP フレームワークを提供してくれたことに感謝します
• uv - 非常に高速な Python パッケージ管理を提供してくれたことに感謝します
• Neo4j - 強力なグラフデータベース機能を提供してくれたことに感謝します
• OpenAI - 最先端の埋め込みモデルを提供してくれたことに感謝します
• Model Context Protocol - プロトコル仕様を提供してくれたことに感謝します

---