🔍 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. サーバーを起動する

   # Activate virtual environment
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   
   # Start the FastMCP server in development mode
   mcp dev server.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 キー	✅	text-embedding-small

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 descriptionIndex FOR (n:Label) 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 ファイルを参照してください。

🙏 謝辞

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

---