Qdrant MCP Server

Qdrant にサービスとしてアクセスするための FastAPI クライアントと MCPServer クライアント

ファイル main.py がエントリーポイントです。コマンドライン引数で、実行するサーバーを選択します。

main.py

import argparse
import uvicorn
from fastapi_server import app as fastapi_app
from fastmcp_server import app as fastmcp_app
from config import settings

def run_fastapi():
    """Run the FastAPI server"""
    print(f"Starting FastAPI server on port {settings.port}")
    uvicorn.run(
        fastapi_app,
        host="0.0.0.0",
        port=settings.port,
        log_level="info"
    )

def run_fastmcp():
    """Run the FastMCP server"""
    print(f"Starting FastMCP server on port {settings.mcp_port}")
    fastmcp_app.run(port=settings.mcp_port)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Run Qdrant MCP Server")
    parser.add_argument(
        "--server-type",
        choices=["fastapi", "fastmcp"],
        default="fastmcp",
        help="Type of server to run (default: fastmcp)"
    )
    args = parser.parse_args()

    if args.server_type == "fastapi":
        run_fastapi()
    else:
        run_fastmcp()

Qdrant MCP サーバー

FastAPI と FastMCP の両方のプロトコルに対応した、Qdrant のナレッジグラフ操作用デュアルプロトコルサーバーです。

プロジェクト構成

src/qdrant_mcpserver/
├── __init__.py
├── config.py          # Configuration settings
├── qdrant_client.py   # Qdrant operations
├── fastapi_server.py  # FastAPI implementation
├── fastmcp_server.py  # FastMCP implementation
└── main.py            # CLI entry point

ファイルの説明

config.py

• 環境変数を読み込みます
• 以下の設定が含まれます：
  • Qdrant 接続（URL、API キー）
  • OpenAI API キー
  • コレクション名
  • サーバーのポート
• 検証には pydantic を使用します

qdrant_client.py

• Qdrant の中核的な操作を実装します：
  • コレクション管理
  • ノードの upsert／削除
  • ベクトル検索
• OpenAI 経由での埋め込み生成を処理します
• 両方のサーバータイプ向けにサービスレイヤーを提供します

fastapi_server.py

• 以下を備えた FastAPI の実装です：
  • RESTful エンドポイント
  • CORS ミドルウェア
  • OpenAPI ドキュメント
• エンドポイント：
  • POST /nodes/upsert
  • POST /nodes/search
  • DELETE /nodes
  • GET /health

fastmcp_server.py

• 以下を備えた FastMCP の実装です：
  • MCP プロトコルへの準拠
  • 認証サポート
  • 標準化されたレスポンス形式
• FastAPI と同じエンドポイントを、MCP エンベロープで提供します

main.py

• CLI エントリーポイントです。以下の機能があります：
  • サーバータイプの選択（--server-type）
  • ログの一元管理
  • ポート設定
• FastAPI または FastMCP サーバーを実行します

インストール

1. Poetry をインストールします（未インストールの場合）：

curl -sSL https://install.python-poetry.org | python3 -

2. リポジトリをクローンします：

git clone https://github.com/your-repo/qdrant-mcpserver.git
cd qdrant-mcpserver

3. 依存関係をインストールします：

poetry install

4. 環境を設定します：

cp .env.example .env
# Edit .env with your actual values

使用方法

サーバーの実行

# Run FastMCP server (default)
poetry run python -m qdrant_mcpserver.main

# Run FastAPI server
poetry run python -m qdrant_mcpserver.main --server-type fastapi

環境変数

変数	必須	説明
QDRANT_URL	はい	Qdrant サーバーの URL
QDRANT_API_KEY	いいえ	Qdrant API キー
OPENAI_API_KEY	はい	OpenAI API キー
COLLECTION_NAME	いいえ	デフォルト："knowledge_graph"
PORT	いいえ	FastAPI のポート（デフォルト：8000）
MCP_PORT	いいえ	FastMCP のポート（デフォルト：8080）
MCP_SECRET	いいえ	認証シークレット

API エンドポイント

どちらのサーバーも同じエンドポイントを提供します：

• POST /nodes/upsert - ナレッジグラフのノードを upsert します
• POST /nodes/search - ノードを対象にセマンティック検索を行います
• DELETE /nodes - ID を指定してノードを削除します
• GET /health - ヘルスチェック

開発

コードフォーマット

以下のコマンドでコードスタイルを統一できます：

# Formats code according to Black's style guide (PEP 8 compliant)
poetry run black .

インポートを適切に整理します（標準ライブラリ、サードパーティ、ローカルの順にグループ化）

poetry run isort .コードをフォーマットします：

poetry run black .
poetry run isort .

テスト

包括的なテストカバレッジには pytest を使用します。テストファイルはメインコードの構成に合わせて配置してください：

テストのセットアップ

poetry install --with test
poetry run pytest --cov --cov-report=html

# Run all tests
poetry run pytest -v

# Run with coverage report
poetry run pytest --cov=qdrant_mcpserver --cov-report=term-missing
Setup tests (one time):

型チェック：

poetry run mypy .

デプロイ

本番用パッケージをビルドします：

poetry build

システム全体にインストールします：

pip install dist/*.whl

サービスとして実行します：

python -m qdrant_mcpserver.main --server-type fastmcp

主な機能：

1. 柔軟なサーバー選択：

   • CLI 引数で FastAPI と FastMCP を切り替えます
   • 設定と Qdrant クライアントを共有します
   • 両方で一貫したエンドポイントを提供します

2. 包括的なドキュメント：

   • 明確なファイル構成の説明
   • インストールと使用方法
   • 環境変数のリファレンス
   • 開発ワークフロー

3. 本番環境対応：

   • 依存関係の管理に Poetry を使用
   • 環境変数による設定
   • ビルドとデプロイの手順

4. 保守しやすい構成：

   • 関心事の分離
   • 共通のコア機能
   • 明確な開発プラクティス

この実装では、基盤となる Qdrant の操作を維持しながら、サーバープロトコルを切り替えられます。