Daniel Lightrag MCP

🚀 Daniel LightRAG MCP服務器

Daniel LightRAG MCP服務器是一個全面的MCP（模型上下文協議）服務器，它與LightRAG API實現了100%功能集成。提供涵蓋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。

可用工具（共22個 - 全部可用 ✅）

文檔管理工具（6個工具）

insert_text

將文本內容插入到LightRAG中。 參數：

• text（必需）：要插入的文本內容

示例：

{
  "text": "這是關於機器學習算法及其在現代人工智能系統中的應用的重要信息。"
}

insert_texts

將多個文本文檔插入到LightRAG中。 參數：

• texts（必需）：文本文檔數組，可包含可選的標題和元數據

示例：

{
  "texts": [
    {
      "title": "人工智能概述",
      "content": "人工智能正在改變各個行業...",
      "metadata": {"category": "技術", "author": "研究員"}
    },
    {
      "content": "機器學習算法需要大量的數據集..."
    }
  ]
}

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 - 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": "機器學習的主要概念有哪些？",
  "mode": "hybrid",
  "only_need_context": false
}

query_text_stream

從LightRAG流式獲取查詢結果。 參數：

• query（必需）：查詢文本
• mode（可選）：查詢模式 - "naive"、"local"、"global" 或 "hybrid"（默認："hybrid"）
• only_need_context（可選）：是否僅返回上下文而不進行生成（默認：false）

示例：

{
  "query": "解釋人工智能的發展歷程",
  "mode": "global"
}

知識圖譜工具（6個工具）

get_knowledge_graph

從LightRAG中檢索知識圖譜。 參數：無

示例：

{}

get_graph_labels

從知識圖譜中獲取標籤。 參數：無

示例：

{}

check_entity_exists

檢查實體是否存在於知識圖譜中。 參數：

• entity_name（必需）：要檢查的實體名稱

示例：

{
  "entity_name": "機器學習"
}

update_entity

更新知識圖譜中的實體。 參數：

• entity_id（必需）：要更新的實體ID
• properties（必需）：要更新的屬性

示例：

{
  "entity_id": "entity_123",
  "properties": {
    "description": "更新後的機器學習描述",
    "category": "人工智能技術"
  }
}

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": "人工智能研究論文",
        "content": "最近變壓器架構的進展在自然語言理解任務中顯示出顯著的改進...",
        "metadata": {"category": "研究", "year": 2024}
      }
    ]
  }
}

3. 查詢知識庫：

{
  "tool": "query_text",
  "arguments": {
    "query": "變壓器架構最近有哪些進展？",
    "mode": "hybrid"
  }
}

4. 探索知識圖譜：

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

5. 檢查實體是否存在：

{
  "tool": "check_entity_exists",
  "arguments": {"entity_name": "變壓器架構"}
}

知識圖譜管理工作流

1. 獲取當前圖譜結構：

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

2. 獲取可用標籤：

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

3. 更新實體屬性：

{
  "tool": "update_entity",
  "arguments": {
    "entity_id": "transformer_arch_001",
    "properties": {
      "description": "用於序列處理的高級神經網絡架構",
      "applications": ["自然語言處理", "計算機視覺", "語音識別"],
      "year_introduced": 2017
    }
  }
}

4. 更新關係屬性：

{
  "tool": "update_relation",
  "arguments": {
    "relation_id": "rel_improves_002",
    "properties": {
      "improvement_factor": 2.5,
      "confidence": 0.92,
      "evidence": "多項基準研究"
    }
  }
}

系統監控工作流

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": "無法連接到LightRAG服務器 http://localhost:9621",
  "timestamp": 1703123456.789,
  "status_code": null,
  "response_data": {}
}

常見錯誤場景

連接錯誤

{
  "error_type": "LightRAGConnectionError",
  "message": "拒絕連接到 http://localhost:9621",
  "status_code": null
}

驗證錯誤

{
  "error_type": "LightRAGValidationError", 
  "message": "query_text缺少必需的參數: ['query']",
  "validation_errors": [
    {
      "loc": ["query"],
      "msg": "字段必填",
      "type": "value_error.missing"
    }
  ]
}

API錯誤

{
  "error_type": "LightRAGAPIError",
  "message": "未找到文檔",
  "status_code": 404,
  "response_data": {
    "detail": "ID為 'doc_123' 的文檔不存在"
  }
}

故障排除

快速診斷

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 .
• 檢查端口可用性：確保標準輸入輸出端口沒有衝突

連接被拒絕

• 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. 查看 配置指南 以獲取設置詳細信息

🔧 技術細節

本服務器經過全面測試和優化，實現了100%的功能。主要改進包括：

• HTTP客戶端修復：正確處理帶有JSON主體的DELETE請求
• 請求參數驗證：所有請求模型與LightRAG API保持一致
• 響應模型對齊：所有響應模型與實際服務器響應匹配
• 文件源實現：關鍵修復，防止數據庫損壞
• 知識圖譜訪問：優化標籤參數，實現全圖訪問

有關完整的技術細節，請參閱 IMPLEMENTATION_GUIDE.md。

📄 許可證

本項目採用MIT許可證。