丹尼尔轻量级MCP

Name: 丹尼尔轻量级MCP
Author: desimpkins

作者：desimpkins13 星标更新：2025-08-22

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Daniel LightRAG MCP Server

一个全面的MCP（模型上下文协议）服务器，提供与LightRAG API的100%功能集成，提供涵盖文档管理、查询操作、知识图谱操作和系统管理四个类别的22个完全工作的工具。

🎉 状态：100% 功能

经过全面测试和优化后，所有22个工具均工作正常：

✅ 文档管理：6/6工具工作（100%）
✅ 查询操作：2/2工具工作（100%）
✅ 知识图谱：6/6工具工作（100%）
✅ 系统管理：4/4工具工作（100%）
✅ 健康检查：1/1工具工作（100%）

特性

文档管理：6个工具用于插入、上传、扫描、检索和管理文档
查询操作：2个工具用于文本查询，支持常规和流式响应
知识图谱：6个工具用于访问、检查、更新和管理实体及关系
系统管理：4个工具用于健康检查、状态监控和缓存管理
全面错误处理：强大的错误处理机制，带有详细的错误消息
完整的API覆盖：与LightRAG API 0.1.96+完全集成

快速开始

安装服务器：
```
pip install -e .
```
启动LightRAG服务器（确保其在http://localhost:9621上运行）

配置您的MCP客户端（例如，Claude Desktop）：

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

测试连接：使用get_health工具验证一切是否正常工作。

安装

# 基本安装
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": "这是关于机器学习算法及其在现代AI系统中的应用的重要信息。"
}

`insert_texts`

将多个文本文档插入LightRAG。

参数：

texts（必需）：带有可选标题和元数据的文本文档数组

示例：

{
  "texts": [
    {
      "title": "AI概述",
      "content": "人工智能正在改变行业...",
      "metadata": {"category": "technology", "author": "researcher"}
    },
    {
      "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": "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服务器健康状况。

**参数：**无

示例：

{}

示例工作流程

完整文档管理工作流程

检查服务器健康状况：

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

插入文档：

{
  "tool": "insert_texts",
  "arguments": {
    "texts": [
      {
        "title": "AI研究论文",
        "content": "最近在Transformer架构方面的进展已经在自然语言理解任务中显示出显著的改进...",
        "metadata": {"category": "research", "year": 2024}
      }
    ]
  }
}

查询知识库：

{
  "tool": "query_text",
  "arguments": {
    "query": "Transformer架构的最新进展是什么？",
    "mode": "hybrid"
  }
}

探索知识图谱：

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

检查实体存在情况：

{
  "tool": "check_entity_exists",
  "arguments": {"entity_name": "Transformer架构"}
}

知识图谱管理工作流程

获取当前图结构：

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

获取可用标签：

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

更新实体属性：

{
  "tool": "update_entity",
  "arguments": {
    "entity_id": "transformer_arch_001",
    "properties": {
      "description": "用于序列处理的高级神经网络架构",
      "applications": ["NLP", "计算机视觉", "语音识别"],
      "year_introduced": 2017
    }
  }
}

更新关系属性：

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

系统监控工作流程

检查整体健康状况：

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

监控管道状态：

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

检查文档处理状态：

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

跟踪特定操作：

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

需要时清除缓存：

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

错误处理

服务器提供了带有详细错误消息的全面错误处理：

连接错误：当无法连接到LightRAG服务器时
认证错误：当API密钥无效或缺失时
验证错误：当输入参数无效时
API错误：当LightRAG API返回错误时
超时错误：当请求超过超时限制时
服务器错误：当LightRAG服务器返回5xx状态代码时

所有错误都包含：

错误类型和消息
HTTP状态代码（适用时）
时间戳
导致错误的工具名称
当可用时的附加上下文数据

错误响应格式

{
  "tool": "insert_text",
  "error_type": "LightRAGConnectionError",
  "message": "无法连接到http://localhost:9621上的LightRAG服务器",
  "timestamp": 1703123456.789,
  "status_code": null,
  "response_data": {}
}

常见错误场景

连接错误

{
  "error_type": "LightRAGConnectionError",
  "message": "连接被拒绝到http://localhost:9621",
  "status_code": null
}

验证错误

{
  "error_type": "LightRAGValidationError", 
  "message": "缺少查询文本所需的参数：['query']",
  "validation_errors": [
    {
      "loc": ["query"],
      "msg": "字段必填",
      "type": "value_error.missing"
    }
  ]
}

API错误

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

故障排除

快速诊断

检查LightRAG服务器状态：
```
curl http://localhost:9621/health
```

测试MCP服务器：

python -m daniel_lightrag_mcp &
sleep 2
pkill -f daniel_lightrag_mcp

验证安装：

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

常见问题

服务器无法启动

检查Python版本：需要Python 3.8+
验证依赖项：运行pip install -e .
检查端口可用性：确保没有标准I/O冲突

连接被拒绝

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

获取帮助

检查服务器日志以获取详细错误消息
使用最小示例测试各个工具
验证LightRAG服务器是否正确响应
查看配置指南以了解设置详情

开发

安装开发依赖项：

pip install -e ".[dev]"

运行测试：

pytest

运行带覆盖率的测试：

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

格式化代码：

black src/ tests/
isort src/ tests/

许可证

MIT许可证