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许可证。