Daniel LightRAG MCP服务器
一个全面的MCP（模型上下文协议）服务器，提供 100%功能 与LightRAG API集成，提供 22个全功能工具 跨4个类别，用于完成文档管理、查询、知识图操作和系统管理。
🎉 状态：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客户端 （例如，克劳德桌面）：
{
"mcpServers": {
"daniel-lightrag": {
"command": "python",
"args": ["-m", "daniel_lightrag_mcp"]
}
}
}- 测试连接:
使用 get_health 用于验证一切正常的工具。
安装
# Basic installation
pip install -e .
# With development dependencies
pip install -e ".[dev]"用法
命令行
启动MCP服务器：
daniel-lightrag-mcp环境变量
使用环境变量配置服务器：
export LIGHTRAG_BASE_URL="http://localhost:9621"
export LIGHTRAG_API_KEY="your-api-key" # Optional
export LIGHTRAG_TIMEOUT="30" # Optional
export LOG_LEVEL="INFO" # Optional
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一致
- 响应模型对齐：所有响应模型都与实际服务器响应匹配
- 文件源实现：防止数据库损坏的关键修复程序
- 知识图谱访问：优化标签参数以实现完全图形访问
有关完整的技术细节，请参阅 实施\_ GIDE.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-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（可选）：查询模式-“天真”、“本地”、“全局”或“混合”（默认：“混合”）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（可选）：查询模式-“天真”、“本地”、“全局”或“混合”（默认：“混合”）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（必填）：要更新的实体的IDproperties（必填）：要更新的属性
例子：
{
"entity_id": "entity_123",
"properties": {
"description": "Updated description for machine learning",
"category": "AI Technology"
}
}update_relation
更新知识图中的关系。
参数：
relation_id（必填）：要更新的关系的IDproperties（必填）：要更新的属性
例子：
{
"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 Research Paper",
"content": "Recent advances in transformer architectures have shown remarkable improvements in natural language understanding tasks...",
"metadata": {"category": "research", "year": 2024}
}
]
}
}- 查询知识库:
{
"tool": "query_text",
"arguments": {
"query": "What are the recent advances in transformer architectures?",
"mode": "hybrid"
}
}- 探索知识图谱:
{"tool": "get_knowledge_graph", "arguments": {}}- 检查实体是否存在:
{
"tool": "check_entity_exists",
"arguments": {"entity_name": "transformer architectures"}
}知识图谱管理工作流程
- 获取当前图形结构:
{"tool": "get_knowledge_graph", "arguments": {}}- 获取可用标签:
{"tool": "get_graph_labels", "arguments": {}}- 更新实体属性:
{
"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
}
}
}- 更新关系属性:
{
"tool": "update_relation",
"arguments": {
"relation_id": "rel_improves_002",
"properties": {
"improvement_factor": 2.5,
"confidence": 0.92,
"evidence": "Multiple benchmark studies"
}
}
}系统监控工作流程
- 检查整体健康状况:
{"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": "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"
}
}故障排除
快速诊断
- 检查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 . - 检查端口可用性：确保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获取帮助
- 检查服务器日志以获取详细的错误消息
- 用最少的示例测试单个工具
- 验证LightRAG服务器是否正确响应
- 查看 配置指南 有关设置详细信息
发展
安装开发依赖项：
pip install -e ".[dev]"运行测试：
pytest运行覆盖率测试：
pytest --cov=src/daniel_lightrag_mcp --cov-report=html格式代码：
black src/ tests/
isort src/ tests/许可证
MIT许可证