🔍 Neo4j查询优化器MCP服务器

](https://badge.fury.io/py/mcp-neo4j-query-optimizer) ![Python 3.8+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT) ![Neo4j](https://neo4j.com/) ![MCP](https://modelcontextprotocol.io/)

⚠️ 进行中：该储存库正在积极开发中。您可以随时尝试并提供反馈，但随着我们的开发继续，预计会有一些变化和改进。

一个全面的MCP（模型上下文协议）服务器，从Neo4j查询计划中提取结构化运算符数据，并为MCP客户端提供丰富的上下文，以解释和提供智能优化建议。非常适合与Claude Desktop和其他MCP客户端集成。

✨ 特性

🔍 结构化数据抽取：从Neo4j查询计划中提取全面的运算符数据
📊 性能分析：确定绩效指标和特征
🎯 操作员分类：基于官方 Neo4j操作员文档
🧠 MCP客户端智能：为智能推荐提供丰富的上下文
⚡ 查询优化：通过前后比较进行基本优化
🧪 综合测试：38个单元测试，确保可靠性
🔗 通用兼容性：适用于任何MCP客户端（Claude Desktop等）
📈 丰富的上下文：用于智能对话的结构化数据
🚀 快速可靠：没有外部API依赖项，脱机工作

🚀 快速开始

先决条件

Python 3.8+
Neo4j数据库（本地或云端）
Claude Desktop或其他MCP客户端

安装

克隆存储库:

   git clone 
   cd mcp-query-optimizer

安装依赖项:

   pip install -e .

配置Neo4j连接:

在MCP客户端配置中设置Neo4j凭据（请参阅下面的配置部分）

配置MCP客户端:

将服务器添加到您的Claude Desktop或其他MCP客户端配置中

🎯 用法

可用工具

MCP服务器提供两个主要工具：

optimize-neo4j-query：完整的优化工作流程，具有前后比较和丰富的对话上下文
analyze-query-plan：具有丰富讨论背景的单查询计划分析

Claude桌面集成

配置MCP服务器 在Claude桌面设置中
让Claude优化查询:

   Can you optimize this Cypher query: MATCH (n) WHERE n.name = 'test' RETURN n LIMIT 10

获取详细分析:

   What performance issues does this query have: MATCH (p:Product)-[:HAS_SKU]->(s:SKU) WHERE p.category = 'Electronics' RETURN p, s

直接MCP使用

直接测试服务器：

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | python src/mcp_neo4j_optimizer/agent.py

# Optimize a query
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "optimize-neo4j-query", "arguments": {"query": "MATCH (n) RETURN n"}}}' | python src/mcp_neo4j_optimizer/agent.py

📊 分析输出

优化器提供：

性能问题

关键的：完整数据库扫描，笛卡尔积
高：缺少索引，扫描效率低下
中等：后期筛选、排序问题
低：优化操作

建议

具体优化策略
实施指南
基于优先级的建议

指数建议

精确的CREATE INDEX语句
针对具体财产的建议
综合指数建议

查询重写

查询前/后示例
改进的查询结构
以性能为重点的替代方案

🏗️ 建筑

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   MCP Server     │    │   Neo4j         │
│ (Claude, etc.)  │◄──►│                  │◄──►│   Database      │
│                 │    │                  │    │                 │
│ • Interprets    │    │ • Extracts       │    │ • Query Plans   │
│   operators     │    │   operator data  │    │ • Execution     │
│ • Provides      │    │ • Classifies     │    │   Stats         │
│   recommendations│    │   operators      │    │                 │
│ • Generates     │    │ • Structures     │    │                 │
│   optimizations │    │   data           │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🎯 正确的MCP架构

MCP服务器职责：

从Neo4j查询计划中提取结构化运算符数据
根据官方Neo4j文档对运算符进行分类
提供性能指标和特征
用于MCP客户端解释的结构数据

MCP客户责任：

使用Neo4j运算符的知识解释运算符数据
提供智能建议和优化
生成教育内容和最佳实践
创建前后比较和解释

🔄 最近的重构（v2.0）-正确的MCP架构

主要变化：

✅ 结构化数据抽取：MCP服务器提取操作员数据，客户端提供情报
✅ 操作员分类：基于 Neo4j操作员文档
✅ 综合测试：增加了38个单元测试，涵盖所有功能

正确的MCP架构：

🎯 MCP服务器：从Neo4j查询计划中提取结构化运算符数据
🧠 MCP客户端：利用Neo4j运算符的知识提供智能建议
📊 结构化数据：具有操作员详细信息、性能指标和元数据的丰富上下文
🔗 官方参考：链接到Neo4j文档，以便操作员理解

🔍 实例分析

输入查询:

MATCH (n) WHERE n.name = 'test' RETURN n LIMIT 10

结构化数据输出:

{
  "query": "MATCH (n) WHERE n.name = 'test' RETURN n LIMIT 10",
  "query_type": "read",
  "complexity": "medium",
  "query_patterns": ["node matching", "property filtering", "result limiting"],
  "operators": [
    {
      "operator": "NodeByLabelScan",
      "clean_operator": "NodeByLabelScan",
      "estimated_rows": 1000,
      "db_hits": 1000,
      "is_leaf": true,
      "is_updating": false,
      "is_eager": false,
      "performance_characteristics": {
        "operator_type": "NodeByLabelScan",
        "estimated_rows": 1000,
        "db_hits": 1000,
        "performance_indicators": ["high_row_count"]
      }
    }
  ],
  "summary": {
    "total_operators": 3,
    "leaf_operators": 1,
    "updating_operators": 0,
    "eager_operators": 0,
    "estimated_total_rows": 1000,
    "estimated_db_hits": 1000
  },
  "performance_indicators": ["high_row_count"],
  "query_metadata": {
    "has_where_clause": true,
    "has_order_by": false,
    "has_limit": true,
    "has_aggregation": false,
    "has_relationships": false
  }
}

MCP客户端解释: 基于此结构化数据，MCP客户端可以提供：

性能分析：高行数表示潜在的性能问题
优化建议：在筛选的属性上创建索引
索引建议: CREATE INDEX FOR (n:Node) ON (n.name)
最佳实践：在MATCH子句中使用标签以获得更好的性能

🛠️ MCP工具

工具	说明	参数
`optimize-neo4j-query`	使用前后比较分析和优化Neo4j查询	`query` （必填）， `database` （可选）
`analyze-query-plan`	获取查询执行计划的详细结构化分析	`query` （必填）， `database` （可选）

📋 工具输出

这两种工具都提供：

结构化操作员数据 具有性能特征
查询元数据 和图案
绩效指标 用于MCP客户端解释
丰富的上下文 用于智能推荐
参考文献 到官方Neo4j文档

🎨 MCP代理功能

结构化数据抽取：从Neo4j查询计划中提取全面的运算符数据
操作员分类：基于官方 Neo4j操作员文档
性能分析：确定绩效指标和特征
丰富的上下文生成：为MCP客户端解释提供结构化数据
通用兼容性：适用于任何MCP客户端（Claude Desktop等）
离线操作：没有外部API依赖项，完全脱机工作

🔧 配置

MCP客户端配置

将此添加到您的Claude Desktop或其他MCP客户端配置中：

适用于克劳德桌面 （macOS）：

{
  "mcpServers": {
    "neo4j-query-optimizer": {
      "command": "python",
      "args": ["/path/to/your/mcp-query-optimizer/src/mcp_neo4j_optimizer/agent.py"],
      "env": {
        "NEO4J_URI": "neo4j+s://your-db-id.databases.neo4j.io",
        "NEO4J_USER": "neo4j", 
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

配置文件位置:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

重要提示:

将Python路径替换为实际的Python可执行路径
将项目路径替换为实际项目位置

环境变量

变量	描述	必填	默认
`NEO4J_URI`	Neo4j数据库URI	否\*	`bolt://localhost:7687`
`NEO4J_USER`	Neo4j用户名	否\*	`neo4j`
`NEO4J_PASSWORD`	Neo4j密码	否\*	`password`

\*实时数据库分析所需。MCP服务器在没有这些凭据的情况下以基于规则的分析模式工作。

🔧 故障排除

常见问题

1.MCP服务器未加载

检查配置中的Python路径是否正确
确保脚本路径指向实际路径 agent.py 文件
验证脚本是否可执行： chmod +x src/mcp_neo4j_optimizer/agent.py

2.“没有可用工具”错误

配置更改后完全重新启动Claude Desktop
使用JSON验证器检查配置文件语法
确保配置中的MCP服务器名称匹配

3.Neo4j连接问题

MCP服务器在没有Neo4j凭据的情况下工作（基于规则的模式）
对于实时数据库分析，请验证您的Neo4j凭据
检查您的Neo4j数据库是否可以从您的计算机访问

4.Python依赖关系

安装所需的依赖项： pip install neo4j python-dotenv
确保你使用的是正确的Python环境

测试MCP服务器

直接测试MCP服务器：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python src/mcp_neo4j_optimizer/agent.py

您应该看到带有可用工具的JSON响应。

🤝 贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

📝 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🤖 Neo4j查询优化代理-MCP服务器

该项目提供了一个 智能Neo4j查询优化代理 可以直接集成到 克劳德桌面！代理分析您的Cypher查询，生成优化版本，并比较执行计划，以准确显示性能是如何提高的。

Claude桌面的快速设置

复制配置:

   {
     "mcpServers": {
       "neo4j-optimizer-agent": {
         "command": "/path/to/your/anaconda3/bin/python",
         "args": ["/path/to/your/neo4j_optimizer_agent.py"]
       }
     }
   }

添加到Claude Desktop MCP设置

在Claude中使用:

- “你能优化这个Cypher查询吗： MATCH (n) RETURN n LIMIT 5" - “分析以下查询计划： MATCH (p:Product)-[:HAS_SKU]->(s:SKU) WHERE p.category = 'Electronics' RETURN p, s" - “比较查询优化前后的性能”

🎯 代理人做什么

核心功能：

📊 分析原始查询：从Neo4j数据库获取执行计划
⚡ 生成优化版本：基于检测到的问题创建改进的查询
📈 比较计划：确切地向您展示改进的内容及其原因
💡 提供见解：解释性能差异和后续步骤

可用的MCP工具

optimize-neo4j-query：完整的优化工作流程-分析原始查询，创建优化版本，比较执行计划
analyze-query-plan：无需优化即可深入了解单个查询的执行计划

测试代理

# Test tools list
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | python neo4j_optimizer_agent.py

# Test query optimization
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "optimize-neo4j-query", "arguments": {"query": "MATCH (n) RETURN n"}}}' | python neo4j_optimizer_agent.py

🚀 代理功能

🔍 真实查询计划分析：连接到实际的Neo4j数据库
⚡ 智能优化：检测所有节点扫描、CartesianProduct和其他昂贵的操作
📊 比较之前/之后：显示运算符更改、行估计和改进
💡 可操作的见解：建议索引、查询重写和性能提示
🎯 生产就绪：使用您的实际数据库进行现实分析

🆘 支持

问题：通过GitHub问题报告错误和功能请求
文档：检查 docs/API_DOCS.md API详细文档
MCP集成：直接在Claude Desktop中与MCP服务器一起使用
测试：使用提供的示例直接测试服务器

📋 故障排除

常见问题

❌ “找不到Neo4j凭据”

确保环境变量设置正确
检查您的MCP客户端配置

❌ “无法解析地址”

验证您的Neo4j数据库是否正在运行
检查您的数据库凭据

❌ “连接超时”

检查您的网络连接
验证Neo4j数据库是否可访问

______________________________________________________________________

快乐查询优化！ 🚀

MCP Neo4j Query Optimizer

快速接入

详细介绍

🔍 Neo4j查询优化器MCP服务器

✨ 特性

🚀 快速开始

先决条件

安装

🎯 用法

可用工具

Claude桌面集成

直接MCP使用

直接测试服务器：

📊 分析输出

性能问题

建议

指数建议

查询重写

🏗️ 建筑

🎯 正确的MCP架构

🔄 最近的重构（v2.0）-正确的MCP架构

🔍 实例分析

🛠️ MCP工具

📋 工具输出

🎨 MCP代理功能

🔧 配置

MCP客户端配置

环境变量

🔧 故障排除

常见问题

测试MCP服务器

🤝 贡献

📝 许可证

🤖 Neo4j查询优化代理-MCP服务器

Claude桌面的快速设置

🎯 代理人做什么

核心功能：

可用的MCP工具

测试代理

🚀 代理功能

🆘 支持

📋 故障排除

常见问题

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP