Daniel Lightrag MCP

🚀 Daniel LightRAG MCP Server

このサーバーは、LightRAG APIと100%機能的に統合された包括的なMCP（Model Context Protocol）サーバーです。文書管理、クエリ、知識グラフ操作、システム管理の4つのカテゴリーにわたる22の完全に動作するツールを提供します。

🚀 クイックスタート

1. サーバーをインストールする：

   pip install -e .
   

2. LightRAGサーバーを起動する（http://localhost:9621 で実行されていることを確認）

3. MCPクライアントを設定する（例：Claude Desktop）：

   {
     "mcpServers": {
       "daniel-lightrag": {
         "command": "python",
         "args": ["-m", "daniel_lightrag_mcp"]
       }
     }
   }
   

4. 接続をテストする： get_healthツールを使用してすべてが正常に動作していることを確認します。

✨ 主な機能

• 文書管理：文書の挿入、アップロード、スキャン、取得、管理を行う6つのツール
• クエリ操作：通常応答とストリーミング応答を伴うテキストクエリ用の2つのツール
• 知識グラフ：エンティティと関係のアクセス、チェック、更新、管理を行う6つのツール
• システム管理：ヘルスチェック、ステータス監視、キャッシュ管理を行う4つのツール
• 包括的なエラーハンドリング：詳細なエラーメッセージを伴う堅牢なエラーハンドリング
• 完全なAPIカバレッジ：LightRAG API 0.1.96+との完全な統合

📦 インストール

# 基本的なインストール
pip install -e .

# 開発用の依存関係を含むインストール
pip install -e ".[dev]"

💻 使用例

コマンドライン

MCPサーバーを起動する：

daniel-lightrag-mcp

環境変数

環境変数を使用してサーバーを設定する：

export LIGHTRAG_BASE_URL="http://localhost:9621"
export LIGHTRAG_API_KEY="your-api-key"  # オプション
export LIGHTRAG_TIMEOUT="30"            # オプション
export LOG_LEVEL="INFO"                 # オプション

daniel-lightrag-mcp

📚 ドキュメント

サーバーの設定

サーバーはデフォルトでLightRAGがhttp://localhost:9621で実行されていることを想定しています。このMCPサーバーを実行する前に、LightRAGサーバーが起動していることを確認してください。

MCPクライアントの設定

MCPクライアント（例：Claude Desktop）に追加する：

{
  "mcpServers": {
    "daniel-lightrag": {
      "command": "python",
      "args": ["-m", "daniel_lightrag_mcp"],
      "env": {
        "LIGHTRAG_BASE_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "lightragsecretkey"
      }
    }
  }
}

詳細な設定オプションについては、MCP_CONFIGURATION_GUIDE.mdを参照してください。

🔧 技術詳細

このサーバーは、包括的なテストと最適化を経て、100%の機能性を実現しています。主要な改善点は以下の通りです：

• HTTPクライアントの修正：JSONボディを伴う適切なDELETEリクエストの処理
• リクエストパラメータの検証：すべてのリクエストモデルがLightRAG APIと一致
• レスポンスモデルの整合性：すべてのレスポンスモデルが実際のサーバーレスポンスと一致
• ファイルソースの実装：データベースの破損を防ぐ重要な修正
• 知識グラフのアクセス：完全なグラフアクセスのための最適化されたラベルパラメータ

完全な技術詳細については、IMPLEMENTATION_GUIDE.mdを参照してください。

利用可能なツール（合計22個 - すべて正常動作✅）

文書管理ツール（6つのツール）

insert_text

LightRAGにテキストコンテンツを挿入します。

パラメーター：

• text（必須）：挿入するテキストコンテンツ

例：

{
  "text": "This is important information about machine learning algorithms and their applications in modern AI systems."
}

insert_texts

LightRAGに複数のテキスト文書を挿入します。

パラメーター：

• texts（必須）：オプションのタイトルとメタデータを持つテキスト文書の配列

例：

{
  "texts": [
    {
      "title": "AI Overview",
      "content": "Artificial Intelligence is transforming industries...",
      "metadata": {"category": "technology", "author": "researcher"}
    },
    {
      "content": "Machine learning algorithms require large datasets..."
    }
  ]
}

upload_document

LightRAGに文書ファイルをアップロードします。

パラメーター：

• file_path（必須）：アップロードするファイルのパス

例：

{
  "file_path": "/path/to/document.pdf"
}

scan_documents

LightRAG内の新しい文書をスキャンします。

パラメーター：なし

例：

{}

get_documents

LightRAGからすべての文書を取得します。

パラメーター：なし

例：

{}

get_documents_paginated

ページングを使用して文書を取得します。

パラメーター：

• page（必須）：ページ番号（1から始まる）
• page_size（必須）：1ページあたりの文書数（1 - 100）

例：

{
  "page": 1,
  "page_size": 20
}

delete_document

特定の文書をIDで削除します。

パラメーター：

• document_id（必須）：削除する文書のID

例：

{
  "document_id": "doc_12345"
}

clear_documents

LightRAGからすべての文書を削除します。

パラメーター：なし

例：

{}

クエリツール（2つのツール）

query_text

LightRAGにテキストでクエリを行います。

パラメーター：

• query（必須）：クエリテキスト
• mode（オプション）：クエリモード - "naive", "local", "global", または "hybrid"（デフォルト: "hybrid"）
• only_need_context（オプション）：生成なしでコンテキストのみを返すかどうか（デフォルト: false）

例：

{
  "query": "What are the main concepts in machine learning?",
  "mode": "hybrid",
  "only_need_context": false
}

query_text_stream

LightRAGからクエリ結果をストリーミングします。

パラメーター：

• query（必須）：クエリテキスト
• mode（オプション）：クエリモード - "naive", "local", "global", または "hybrid"（デフォルト: "hybrid"）
• only_need_context（オプション）：生成なしでコンテキストのみを返すかどうか（デフォルト: false）

例：

{
  "query": "Explain the evolution of artificial intelligence",
  "mode": "global"
}

知識グラフツール（6つのツール）

get_knowledge_graph

LightRAGから知識グラフを取得します。

パラメーター：なし

例：

{}

get_graph_labels

知識グラフからラベルを取得します。

パラメーター：なし

例：

{}

check_entity_exists

知識グラフ内にエンティティが存在するかどうかを確認します。

パラメーター：

• entity_name（必須）：確認するエンティティの名前

例：

{
  "entity_name": "Machine Learning"
}

update_entity

知識グラフ内のエンティティを更新します。

パラメーター：

• entity_id（必須）：更新するエンティティのID
• properties（必須）：更新するプロパティ

例：

{
  "entity_id": "entity_123",
  "properties": {
    "description": "Updated description for machine learning",
    "category": "AI Technology"
  }
}

update_relation

知識グラフ内の関係を更新します。

パラメーター：

• relation_id（必須）：更新する関係のID
• properties（必須）：更新するプロパティ

例：

{
  "relation_id": "rel_456",
  "properties": {
    "strength": 0.9,
    "type": "implements"
  }
}

delete_entity

知識グラフからエンティティを削除します。

パラメーター：

• entity_id（必須）：削除するエンティティのID

例：

{
  "entity_id": "entity_789"
}

delete_relation

知識グラフから関係を削除します。

パラメーター：

• relation_id（必須）：削除する関係のID

例：

{
  "relation_id": "rel_101"
}

システム管理ツール（4つのツール）

get_pipeline_status

LightRAGからパイプラインのステータスを取得します。

パラメーター：なし

例：

{}

get_track_status

IDでトラックのステータスを取得します。

パラメーター：

• track_id（必須）：ステータスを取得するトラックのID

例：

{
  "track_id": "track_abc123"
}

get_document_status_counts

文書のステータスのカウントを取得します。

パラメーター：なし

例：

{}

clear_cache

LightRAGのキャッシュをクリアします。

パラメーター：なし

例：

{}

get_health

LightRAGサーバーのヘルスをチェックします。

パラメーター：なし

例：

{}

サンプルワークフロー

完全な文書管理ワークフロー

1. サーバーのヘルスを確認する：

   {"tool": "get_health", "arguments": {}}
   

2. 文書を挿入する：

   {
     "tool": "insert_texts",
     "arguments": {
       "texts": [
         {
           "title": "AI Research Paper",
           "content": "Recent advances in transformer architectures have shown remarkable improvements in natural language understanding tasks...",
           "metadata": {"category": "research", "year": 2024}
         }
       ]
     }
   }
   

3. 知識ベースをクエリする：

   {
     "tool": "query_text",
     "arguments": {
       "query": "What are the recent advances in transformer architectures?",
       "mode": "hybrid"
     }
   }
   

4. 知識グラフを探索する：

   {"tool": "get_knowledge_graph", "arguments": {}}
   

5. エンティティの存在を確認する：

   {
     "tool": "check_entity_exists",
     "arguments": {"entity_name": "transformer architectures"}
   }
   

知識グラフ管理ワークフロー

1. 現在のグラフ構造を取得する：

   {"tool": "get_knowledge_graph", "arguments": {}}
   

2. 利用可能なラベルを取得する：

   {"tool": "get_graph_labels", "arguments": {}}
   

3. エンティティのプロパティを更新する：

   {
     "tool": "update_entity",
     "arguments": {
       "entity_id": "transformer_arch_001",
       "properties": {
         "description": "Advanced neural network architecture for sequence processing",
         "applications": ["NLP", "computer vision", "speech recognition"],
         "year_introduced": 2017
       }
     }
   }
   

4. 関係のプロパティを更新する：

   {
     "tool": "update_relation",
     "arguments": {
       "relation_id": "rel_improves_002",
       "properties": {
         "improvement_factor": 2.5,
         "confidence": 0.92,
         "evidence": "Multiple benchmark studies"
       }
     }
   }
   

システム監視ワークフロー

1. 全体のヘルスを確認する：

   {"tool": "get_health", "arguments": {}}
   

2. パイプラインのステータスを監視する：

   {"tool": "get_pipeline_status", "arguments": {}}
   

3. 文書処理のステータスを確認する：

   {"tool": "get_document_status_counts", "arguments": {}}
   

4. 特定の操作を追跡する：

   {
     "tool": "get_track_status",
     "arguments": {"track_id": "upload_batch_001"}
   }
   

5. 必要に応じてキャッシュをクリアする：

   {"tool": "clear_cache", "arguments": {}}
   

エラーハンドリング

サーバーは、詳細なエラーメッセージを伴う包括的なエラーハンドリングを提供します：

• 接続エラー：LightRAGサーバーに到達できない場合
• 認証エラー：APIキーが無効または欠落している場合
• 検証エラー：入力パラメーターが無効な場合
• APIエラー：LightRAG APIがエラーを返す場合
• タイムアウトエラー：リクエストがタイムアウト制限を超える場合
• サーバーエラー：LightRAGサーバーが5xxステータスコードを返す場合

すべてのエラーには以下が含まれます：

• エラーの種類とメッセージ
• HTTPステータスコード（該当する場合）
• タイムスタンプ
• エラーを引き起こしたツールの名前
• 利用可能な場合の追加のコンテキストデータ

エラーレスポンスの形式

{
  "tool": "insert_text",
  "error_type": "LightRAGConnectionError",
  "message": "Failed to connect to LightRAG server at http://localhost:9621",
  "timestamp": 1703123456.789,
  "status_code": null,
  "response_data": {}
}

一般的なエラーシナリオ

接続エラー

{
  "error_type": "LightRAGConnectionError",
  "message": "Connection refused to http://localhost:9621",
  "status_code": null
}

検証エラー

{
  "error_type": "LightRAGValidationError", 
  "message": "Missing required arguments for query_text: ['query']",
  "validation_errors": [
    {
      "loc": ["query"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

APIエラー

{
  "error_type": "LightRAGAPIError",
  "message": "Document not found",
  "status_code": 404,
  "response_data": {
    "detail": "Document with ID 'doc_123' does not exist"
  }
}

トラブルシューティング

迅速な診断

1. LightRAGサーバーのステータスを確認する：

   curl http://localhost:9621/health
   

2. MCPサーバーをテストする：

   python -m daniel_lightrag_mcp &
   sleep 2
   pkill -f daniel_lightrag_mcp
   

3. インストールを確認する：

   python -c "import daniel_lightrag_mcp; print('OK')"
   

一般的な問題

サーバーが起動しない場合

• Pythonバージョンを確認する：Python 3.8以上が必要
• 依存関係を確認する：pip install -e .を実行
• ポートの可用性を確認する：stdioで競合がないことを確認

接続拒否

• LightRAGが実行されていない：まずLightRAGサーバーを起動する
• URLが間違っている：LIGHTRAG_BASE_URL環境変数を確認
• ファイアウォールがブロックしている：ポート9621のファイアウォール設定を確認

認証失敗

• APIキーが欠落している：LIGHTRAG_API_KEY環境変数を設定
• キーが無効：LightRAGサーバーでAPIキーを確認
• キーの形式：キーの形式がLightRAGの期待値と一致することを確認

タイムアウトエラー

• タイムアウトを増やす：LIGHTRAG_TIMEOUT=60環境変数を設定
• サーバーの負荷を確認する：LightRAGサーバーのパフォーマンスを確認
• ネットワークの遅延：curlを使用して直接API呼び出しをテスト

ツールが見つからない場合

• MCPクライアントを再起動する：サーバーの設定を再読み込み
• ツール名を確認する：正確なツール名のスペルを確認
• サーバーの登録：すべての22のツールがリストされていることを確認

デバッグモード

詳細なログを有効にする：

export LOG_LEVEL=DEBUG
python -m daniel_lightrag_mcp

ヘルプを得る

1. サーバーのログを確認して詳細なエラーメッセージを取得する
2. 最小限の例で個々のツールをテストする
3. LightRAGサーバーが正しく応答していることを確認する
4. セットアップの詳細についてConfiguration Guideを確認する

開発

開発用の依存関係をインストールする：

pip install -e ".[dev]"

テストを実行する：

pytest

カバレッジを含めてテストを実行する：

pytest --cov=src/daniel_lightrag_mcp --cov-report=html

コードを整形する：

black src/ tests/
isort src/ tests/

📄 ライセンス

MIT License