Neo4j Yass MCP

Neo4j YASS MCP

    

   ](https://hub.docker.com/)   

](https://github.com/hdjebar/neo4j-yass-mcp/releases) ](https://github.com/hdjebar/neo4j-yass-mcp/stargazers) ](https://github.com/hdjebar/neo4j-yass-mcp/network/members) ](https://github.com/hdjebar/neo4j-yass-mcp/graphs/contributors)

另一个安全服务器（YASS） -一个生产就绪、安全增强的模型上下文协议（MCP）服务器，使用LangChain的GraphCypherQAChain提供Neo4j图形数据库查询功能，用于自然语言到Cypher的查询转换。

将自然语言转化为具有企业级安全性和合规性的图形洞察。

v1.4.0的新增功能🚀

性能和异步迁移 -2025年11月发布

v1.4.0提供 性能提升11-13% 通过原生异步Neo4j驱动程序支持：

• ⚡ 顺序查询速度提高11.9%：本机异步消除了线程池开销（每次查询节省1.48ms）
• ⚡ 并行执行速度提高12.8%：4个工具中有3个具有真正的异步并行性
• 🔄 本机异步驱动程序：具有完整安全层的AsyncNeo4jGraph（AsyncSecureNeo4jGraph）
• 🧹 更干净的代码库：删除了ThreadPoolExecutor（约135行）-现在完全是本机异步
• ✅ 100%测试覆盖率：559/559测试通过，所有CI/CD检查均为绿色
• 🔒 安全得到保护：所有净化、复杂性限制和只读功能都完好无损

基准测试：运行 uv run python benchmark_async_performance.py 看看改进！

对于现有用户： 无需更改！插入式替换v1.3.0。

上一个版本：v1.3.0

主要建筑改进 -2025年1月发布

• 🔧 集中式配置：替换26个分散的 os.getenv() Pydantic调用已验证 RuntimeConfig
• 📝 强类型：添加了TypedDict响应类型，以获得更好的IDE支持和类型检查
• 🏗️ Bootstrap模块：多实例部署和更好的测试隔离的基础

请参阅： RELEASE_NOTES_v1.3.0.md | Bootstrap迁移指南

______________________________________________________________________

特性

核心能力

• 🔍 自然语言查询：用简单的英语提问，并从Neo4j图中获得答案
• ⚡ 异步和并行执行：使用async/await支持处理多个并发查询
• 🔌 多个传输：stdio（本地）、HTTP（现代网络）或SSE（传统）模式
• 🎯 自动端口分配：智能地查找可用端口以避免冲突

安全与合规

• 🛡️ 查询消毒（SISO预防）：阻止Cypher注入、UTF-8攻击和恶意模式
• 🔒 只读访问控制：限制为只读查询以获得最大安全性
• 📝 全面的审计日志记录：GDPR、HIPAA、SOC 2、PCI-DSS的完整合规记录
• 🚫 UTF-8攻击防御：阻止同形词、零宽度字符、方向覆盖

性能和规模

• ⚡ 本机异步操作：AsyncNeo4jGraph（v1.4.0）的性能提高了11-13%
• 🚀 真正平行：多个查询并发执行，无线程阻塞
• 📊 响应大小限制：自动截断以管理LLM上下文限制
• 🎛️ 基于令牌的截断：智能响应大小，实现最佳LLM性能
• 🔄 连接池：高效的Neo4j连接管理

🎯 旗舰功能：查询计划分析工具

• 📊 性能分析：使用EXPLAIN/PROFILE分析Neo4j查询执行计划
• 🔍 瓶颈检测：自动识别性能问题（缺少索引、笛卡尔积、昂贵的操作）
• 💡 智能推荐：获取具有严重性评分的可操作优化建议
• ⚡ 成本估算：在运行查询之前预测执行时间和资源使用情况
• 🛡️ 生产就绪：完全安全集成、速率限制和审计日志记录

开发者体验

• 🤖 多个LLM提供商：OpenAI、Anthropic（克劳德）、谷歌生成人工智能
• 🚀 FastMCP框架：使用现代FastMCP和装饰器构建
• 📦 UV包装管理器：快速、现代的Python包管理
• 📚 MCP资源：访问数据库架构和连接信息
• 🛠️ MCP工具：使用自然语言查询，执行原始Cypher，刷新模式

快速开始

先决条件

必修的：

• Python 3.13+（用于Python模式）或Docker（用于容器化模式）
• Neo4j 5.x数据库 （单独实例-参见 Neo4j设置 在......下面

- APOC插件已安装并启用 （高级操作所需） - Bolt协议可访问（默认端口7687）

• 您选择的LLM提供商（OpenAI、Anthropic或Google）的API密钥

可选：

• UV包管理器 （对于Python模式，推荐）

Neo4j设置

此MCP服务器需要 单独的Neo4j实例 随着 APOC插件 （强制性）以及 GDS插件 （推荐）已启用。

所需插件

为什么需要这些插件

APOC核心（必填）

此MCP服务器使用 LangChain的Neo4jGraph 用于模式自省和查询生成。LangChain内部调用APOC过程来检索图模式：

• apoc.meta.nodeTypeProperties() -检索节点标签及其属性
• apoc.meta.relTypeProperties() -检索关系类型及其属性
• 模式信息对于LLM生成的Cypher查询至关重要

没有APOC会发生什么：

❌ Neo4jError: There is no procedure with the name `apoc.meta.nodeTypeProperties`
❌ Schema retrieval fails → LLM cannot generate accurate Cypher queries
❌ MCP server tools will fail to execute

GDS-图形数据科学（推荐）

GDS插件支持增强查询功能的高级图形算法：

• 寻路：最短路径，所有简单路径，A\*算法
• 中心性：PageRank、介数、亲密度（识别重要节点）
• 社区发现：Louvain，标签传播（发现集群）
• 相似性：节点相似性、余弦相似性（推荐）
• 图形嵌入：Node2Vec、GraphSAGE（机器学习功能）

没有GDS会发生什么：

⚠️  Advanced graph algorithms are unavailable
⚠️  Limited to basic Cypher pattern matching
✅  Basic MCP server functionality still works

安装优先级

1. APOC核心 -先安装（服务器操作必须安装）
2. 全球分销系统 -安装第二个（建议用于高级分析）

______________________________________________________________________

选项1：将neo4j堆栈与neo4j_插件一起使用⭐ 推荐

这 neo4j-stack/neo4j 该服务使用内置的自动下载APOC和GDS插件 NEO4J_PLUGINS 环境变量：

# Navigate to neo4j-stack directory
cd ../neo4j

# Start Neo4j (plugins download automatically on first startup)
docker compose up -d

# Verify plugins are installed (wait 30-60s for Neo4j to start)
docker compose exec neo4j cypher-shell -u neo4j -p password123 \
  "RETURN apoc.version() AS apoc, gds.version() AS gds;"

它是如何工作的：

• 用途 NEO4J_PLUGINS='["apoc", "graph-data-science"]' 在
• 插件在容器启动时自动从Neo4j的官方存储库下载
• 下载被缓存在 ./plugins 提高重启速度
• 无需自定义Dockerfile或手动下载

docker-compose.yml中的配置：

environment:
  NEO4J_PLUGINS: '["apoc", "graph-data-science"]'
volumes:
  - ./plugins:/plugins  # Persists downloaded plugins

优点：

• ✅ 零配置-开箱即用
• ✅ Neo4j官方特性（由Neo4j实验室维护）
• ✅ 自动版本匹配（下载兼容的插件版本）
• ✅ 插件缓存在卷中（容器重新启动时无需重新下载）
• ✅ 无需自定义映像构建
• ✅ 首次下载后脱机工作（插件保留在 ./plugins 体积）

当它需要互联网时：

• ⚠️ 第一个容器创建（下载插件一次）
• ⚠️ 删除后 ./plugins 文件夹
• ✅ 插件缓存在卷中后不需要互联网

______________________________________________________________________

选项2：手动将插件下载到插件/文件夹

如果您喜欢手动控制，请将插件下载到 plugins/ 目录：

# Navigate to neo4j-stack/neo4j directory
cd ../neo4j

# Create plugins directory
mkdir -p plugins

# Download APOC Core (MANDATORY)
curl -L https://github.com/neo4j/apoc/releases/download/5.25.1/apoc-5.25.1-core.jar \
  -o plugins/apoc-5.25.1-core.jar

# Download GDS (RECOMMENDED)
curl -L https://graphdatascience.ninja/neo4j-graph-data-science-2.12.1.jar \
  -o plugins/neo4j-graph-data-science-2.12.1.jar

# Start Neo4j (will mount plugins/ folder)
docker compose up -d

插件来源：

• APOC核心：
• GDS： 图形数据科学忍者

何时使用：

• 您需要特定的插件版本（不兼容最新版本）
• 您希望完全控制插件下载
• 您正在离线或在气隙环境中工作

______________________________________________________________________

选项3：使用内置插件自定义Docker构建

使用预装的插件构建自定义Neo4j映像（替代 NEO4J_PLUGINS):

# Navigate to neo4j-stack directory
cd ../neo4j

# Update docker-compose.yml to use the custom Dockerfile:
# Uncomment the 'build' section and comment out 'image' line
# See Dockerfile.custom-build-alternative for details

# Build custom image
docker compose build

# Start Neo4j (plugins already in image)
docker compose up -d

配置参考： 看

何时使用：

• 您需要特定的插件版本（不兼容最新版本）
• 您希望插件嵌入到映像中（不可变的基础架构）
• 您正在为气隙环境（运行时没有互联网）构建
• 你想要更快的容器启动（插件已预先下载）

权衡：

• ✅ 更快的启动（插件预装在镜像中）
• ✅ 脱机工作（启动时不下载）
• ❌ 需要自定义映像构建步骤
• ❌ 更复杂的更新（为新插件版本重建映像）

______________________________________________________________________

选项4：使用Docker的独立Neo4j

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
  -v $PWD/data/neo4j/data:/data \
  neo4j:5.25-community

什么 NEO4J_PLUGINS 做：

这 NEO4J_PLUGINS 环境变量是 内置Neo4j Docker功能 在容器启动期间自动下载和安装插件。

• 格式：插件名称的JSON数组： '["plugin1", "plugin2"]'
• 当它运行时：容器启动时（Neo4j启动之前）
• 从哪里下载：Neo4j官方插件库
• 支持的插件: apoc, apoc-core, graph-data-science, bloom, streams, n10s
• 版本匹配：自动下载与Neo4j版本匹配的插件版本

它在内部是如何工作的：

1. 集装箱启动→ 检查 NEO4J_PLUGINS 环境变量
2. 从下载每个插件JAR https://dist.neo4j.org/ （官方存储库）
3. 将JAR文件放入 /var/lib/neo4j/plugins/ 目录
4. 配置Neo4j以启用这些插件
5. 加载插件启动Neo4j

赞成的意见：

• 无需手动下载
• 保证版本兼容性（与Neo4j版本匹配）
• 简单的单线配置
• Neo4j官方特性（由Neo4j实验室维护）

欺骗：

• 容器启动时需要互联网连接
• 每次创建容器时都会进行下载（如果没有卷装载，则不会持久化）
• 仅限于Neo4j官方存储库中可用的插件
• 无法指定特定的插件版本（始终使用最新兼容版本）

坚持技巧：

# Mount plugins directory to persist downloads across container restarts
docker run -d \
  --name neo4j \
  -e NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
  -v $PWD/data/neo4j/data:/data \
  -v $PWD/data/neo4j/plugins:/plugins \  # ⭐ Persist plugins
  neo4j:5.25-community

______________________________________________________________________

选项5:Neo4j桌面

1. 下载自 neo4j.com/下载
2. 创建数据库
3. 通过桌面UI安装插件：

- 转到数据库→ 插件选项卡 - 点击“安装”以获取APOC和图形数据科学

______________________________________________________________________

选项6:Neo4j AuraDB（云）

• 注册地址： neo4j.com/cloud/aura
• APOC是 预装 在AuraDB
• GDS在企业层可用
• 集 NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io 在.env中

______________________________________________________________________

验证插件安装

// Check APOC version (should return 5.25.1 or similar)
RETURN apoc.version() AS apoc_version;

// Check GDS version (should return 2.12.1 or similar)
RETURN gds.version() AS gds_version;

// List all APOC procedures (should return 100+ procedures)
SHOW PROCEDURES YIELD name WHERE name STARTS WITH 'apoc' RETURN count(name);

// List all GDS procedures (should return 50+ procedures)
SHOW PROCEDURES YIELD name WHERE name STARTS WITH 'gds' RETURN count(name);

预期产量：

╒══════════════╕
│apoc_version  │
╞══════════════╡
│"5.25.1"      │
└──────────────┘

╒═════════════╕
│gds_version  │
╞═════════════╡
│"2.12.1"     │
└─────────────┘

自动设置（推荐）

最快的入门方法：

# Run the automated startup script
./run-server.sh

# This will:
# 1. Create/configure .env automatically
# 2. Allocate free port
# 3. Let you choose: Python/UV or Docker
# 4. Start the server

手动安装

选项1:Python/UV

# 1. Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Setup environment
cd neo4j-yass-mcp
cp .env.example .env
nano .env  # Edit configuration (set MCP_SERVER_PORT if needed)

# 3. Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 5. Install dependencies
uv pip install -e .

# 6. Run server
python server.py

选项2：Docker编写

# 1. Setup environment
cd neo4j-yass-mcp
cp .env.example .env
nano .env  # Edit configuration (set MCP_SERVER_PORT if needed)

# 2. Start with Docker
docker compose up -d

# 4. View logs
docker compose logs -f

基本配置

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

# LLM Provider
LLM_PROVIDER=openai  # or "anthropic", "google-genai"
LLM_MODEL=gpt-4
LLM_API_KEY=your-api-key-here

# Security (Recommended)
SANITIZER_ENABLED=true           # Query injection protection
NEO4J_READ_ONLY=false            # Set to 'true' for read-only mode
AUDIT_LOG_ENABLED=true           # Compliance logging

运行服务器

对于克劳德桌面（stdio）：

# .env configuration
MCP_TRANSPORT=stdio

# Run
python server.py

对于HTTP模式（建议用于网络）：

# .env configuration
MCP_TRANSPORT=http
MCP_SERVER_PORT=8000
MCP_SERVER_PATH=/mcp/

# Run
python server.py
# Server will start at http://127.0.0.1:8000/mcp/

对于SSE模式（传统）：

# .env configuration
MCP_TRANSPORT=sse
MCP_SERVER_PORT=8000

# Run
python server.py
# Server will start at http://127.0.0.1:8000

可用工具

1. query_graph(query: str)

使用自然语言查询Neo4j图。LLM会自动将您的问题翻译成Cypher。

例子：

query_graph(query="Who starred in Top Gun?")

答复：

{
  "question": "Who starred in Top Gun?",
  "answer": "Tom Cruise starred in Top Gun",
  "generated_cypher": "MATCH (a:Actor)-[:ACTED_IN]->(m:Movie {title: 'Top Gun'}) RETURN a.name",
  "success": true
}

2. execute_cypher(cypher_query: str, parameters: Optional[Dict])

完全控制执行原始Cypher查询。 以只读模式隐藏。

例子：

execute_cypher(
  cypher_query="MATCH (n:Person {name: $name}) RETURN n",
  parameters={"name": "Tom Cruise"}
)

3. refresh_schema()

结构更改后刷新缓存的Neo4j模式。

4. analyze_query_performance(query: str, mode: str = "explain", include_recommendations: bool = True) ⭐ 新

分析Cypher查询性能并获得优化建议。 最高投资回报率功能！

特征：

• 执行计划分析：使用Neo4j的EXPLAIN/PROFILE进行详细分析
• 瓶颈检测：识别性能问题（笛卡尔积、缺少索引等）
• 优化建议：可采取行动的建议，严重程度评分（1-10）
• 成本估算：预测执行时间、内存使用情况和资源需求
• 风险评估：在执行之前评估查询风险级别（低/中/高）

分析模式：

• “解释”：无需执行查询即可快速分析- 默认 （安全，建议验证）
• “个人资料”：使用运行时统计数据进行详细分析（执行查询-谨慎使用）

例子：

# Quick performance check
result = await analyze_query_performance(
  query="MATCH (n:Person) WHERE n.age > 25 RETURN n.name",
  mode="explain"
)

print(f"Risk: {result['risk_level']}")  # low/medium/high
print(f"Cost Score: {result['cost_score']}/10")  # 1-10 severity
print(f"Bottlenecks: {result['bottlenecks_found']}")
print(f"Recommendations: {result['recommendations_count']}")

# Get detailed optimization report
if result['recommendations_count'] > 0:
    print(result['analysis_report'])

样本输出：

Query Performance Analysis Report
================================

Query: MATCH (n:Person) WHERE n.age > 25 RETURN n.name
Mode: explain
Overall Severity: 7/10
Estimated Impact: high

Bottlenecks Detected: 2
Recommendations: 3

Performance Bottlenecks:
1. missing_index: Missing index on property filter
   Severity: 8/10
   Impact: High - full scan of ~1000 nodes
   Suggestion: Create index on Person.age

Optimization Recommendations:
1. Create index on age property
   CREATE INDEX person_age FOR (p:Person) ON (p.age)
   Priority: high | Effort: low | Impact: high

常见用例：

• 查询验证：在生产部署之前检查用户查询
• 性能调整：识别并修复慢速查询
• 模式优化：发现缺失的索引和改进
• 风险评估：执行前评估查询安全性

最佳实践：

• 使用 "explain" 快速验证模式（更快）
• 使用 "profile" 详细优化模式（较慢但更准确）
• 关注严重程度7+的问题，以产生立竿见影的效果
• 生产前开发中的测试优化

可用资源

1. neo4j://schema

访问当前的Neo4j数据库模式（节点标签、关系、属性）。

2. neo4j://database-info

获取数据库连接信息和服务器详细信息。

安全功能

SISO：“该死，该死” -如果你接受恶意输入，你的输出就会受到损害。

查询消毒

全面防御注射攻击：

# Enable (highly recommended!)
SANITIZER_ENABLED=true
SANITIZER_STRICT_MODE=false
SANITIZER_BLOCK_NON_ASCII=false

保护层：

• ✅ Cypher注射检测
• ✅ 危险模式阻塞（文件操作、系统命令）
• ✅ 参数验证
• ✅ UTF-8/Unicode攻击防御（同形异义词、零宽度字符）
• ✅ 查询复杂性限制

📖 详细文件： docs/SECURITY.md

审计日志

监管要求的完整合规记录：

# Enable
AUDIT_LOG_ENABLED=true
AUDIT_LOG_FORMAT=json
AUDIT_LOG_ROTATION=daily
AUDIT_LOG_RETENTION_DAYS=90
AUDIT_LOG_PII_REDACTION=false

使用案例：

• GDPR、HIPAA、SOC 2、PCI-DSS合规性
• 安全取证和事件响应
• 性能监控
• 使用情况分析

📖 详细文件： 请参阅中的“审核日志”部分 docs/SECURITY.md

只读模式

通过隐藏可写工具来防止写操作：

NEO4J_READ_ONLY=true

• execute_cypher MCP客户端隐藏的工具
• LLM生成的写入查询被阻止
• 生产环境的最大安全性

🎯 查询计划分析工具-旗舰功能

这 查询计划分析工具 是我们最强大的功能——一个生产就绪的查询性能分析器，它将Neo4j查询优化从艺术转变为科学。

为什么这个功能正在改变游戏规则

传统方法：DBA花费数小时手动分析执行计划、识别瓶颈和编写优化报告。

我们的方法: 即时自动化分析 随着 可操作的建议 和 严重性评分.

核心能力

🔍 自动性能分析

• 解释/简介集成：深入分析Neo4j执行计划
• 瓶颈检测：自动识别15种以上的性能问题
• 严重性评分：1-10级优先考虑关键问题
• 风险评估：在执行之前评估查询安全性

💡 智能推荐

• 指数建议：创建具有估计影响的INDEX语句
• 查询重写：优化了Cypher模式和结构
• 架构改进：节点标签和关系优化
• 成本效益分析：每项建议的努力与影响

📊 生产就绪功能

• 安全集成：全面清理和审计记录
• 速率限制：可配置的限制防止滥用
• 错误处理：优雅的降级，带有经过净化的错误消息
• 性能监控：内置指标和警报

现实世界影响

分析工具之前

User: "Why is my query slow?"
DBA Response: "Let me manually check the execution plan..."
[30 minutes later]
DBA: "You need an index on User.email"

事后分析工具

User: "Analyze this query"
Tool Response: 
✅ **Missing Index Detected** (Severity: 8/10)
📋 **Recommendation**: CREATE INDEX user_email FOR (u:User) ON (u.email)
📈 **Estimated Impact**: 95% performance improvement
⏱️ **Analysis Time**: 0.3 seconds

检测到性能瓶颈

用法示例

快速性能检查

# Validate before production deployment
result = await analyze_query_performance(
    query="MATCH (u:User)-[:FRIENDS_WITH*1..5]->(friend) WHERE u.email = 'alice@example.com' RETURN friend",
    mode="explain"  # Fast, no execution
)

print(f"Risk Level: {result['risk_level']}")  # low/medium/high
print(f"Issues Found: {result['bottlenecks_found']}")

深度性能分析

# Full optimization analysis
result = await analyze_query_performance(
    query="MATCH (p:Product)-[:CATEGORY]->(c:Category) WHERE c.name = 'Electronics' AND p.price > 100 RETURN p",
    mode="profile",  # Detailed with statistics
    include_recommendations=True
)

# Get actionable optimization plan
for rec in result['recommendations']:
    print(f"{rec['priority'].upper()}: {rec['description']}")
    print(f"Impact: {rec['estimated_benefit']}")

批次分析

# Analyze multiple queries efficiently
queries = [
    "MATCH (n) RETURN n LIMIT 10",
    "MATCH (u:User)-[:POSTED]->(p:Post) WHERE u.name = 'Alice' RETURN p",
    "MATCH (p:Product) WHERE p.price > 100 RETURN p.name, p.price"
]

for query in queries:
    result = await analyze_query_performance(query, mode="explain")
    if result['severity_score'] >= 7:
        print(f"HIGH PRIORITY: {query[:50]}...")

分析模式

解释模式（快速验证）

• 速度：每次查询小于100ms
• 用例：部署前验证
• 信息：计划结构、估计费用
• 最适合：快速检查，CI/CD集成

剖面模式（深度分析）

• 速度：每次查询1-5秒
• 用例：生产优化
• 信息：运行时统计数据，实际成本
• 最适合：性能调优、详细分析

集成示例

CI/CD管道

# GitHub Actions integration
- name: Query Performance Check
  run: |
    for query in queries/*.cypher; do
      result=$(python analyze_query.py "$query")
      if [[ "$result" == *"severity.*[7-9]"* ]]; then
        echo "High severity issues found in $query"
        exit 1
      fi
    done

监控仪表盘

# Prometheus metrics integration
analysis_duration.observe(result['analysis_time_ms'])
severity_histogram.observe(result['severity_score'])
recommendations_counter.inc(len(result['recommendations']))

配置

环境变量

# Rate limiting (prevent abuse)
MCP_ANALYZE_QUERY_LIMIT=30        # requests per minute
MCP_ANALYZE_QUERY_WINDOW=60        # window duration

# Performance tuning
MCP_ANALYZE_TIMEOUT=30             # analysis timeout (seconds)
MCP_ANALYZE_MAX_MEMORY=500         # memory limit (MB)

# Security
SANITIZE_ERRORS=true               # hide internal errors
ENABLE_AUDIT_LOGGING=true          # log all analysis requests

生产设置

# High-traffic environment
MCP_ANALYZE_QUERY_LIMIT=100        # higher rate limit
MCP_ANALYZE_TIMEOUT=15              # faster timeout
MCP_ANALYZE_MAX_MEMORY=250          # lower memory usage

成功案例

电子商务平台

• 问题：产品搜索查询耗时8+秒
• 分析：缺少产品类别+价格范围的指数
• 解决方案：创建了综合指数
• 结果：查询时间减少到0.2秒（提高了40倍）

社交网络

• 问题：朋友推荐查询超时
• 分析：无边界可变长度路径 [*] 导致指数级增长
• 解决方案：添加了路径长度界限 [*1..3]
• 结果：查询完成率从60%提高到99%

金融服务

• 问题：事务分析查询消耗了太多内存
• 分析：聚合模式效率低下
• 解决方案：通过早期过滤优化查询结构
• 结果：内存使用量减少85%，每月节省成本2000美元

最佳实践

面向开发者

1. 始终在生产前进行分析：使用EXPLAIN模式进行快速验证
2. 关注严重程度7+：这些提供了最大的性能提升
3. 测试建议：首先验证开发中的优化
4. 监控趋势：随时间跟踪分析结果

DevOps

1. 设置适当的费率限制：平衡用户需求和资源使用
2. 监控内存使用情况：对于复杂的查询，分析可能会占用大量内存
3. 配置超时：防止长时间运行的分析阻止请求
4. 设置警报：监控高错误率或性能下降

对于DBA

1. 谨慎使用PROFILE模式：它执行查询，因此用于代表性数据
2. 批判性地审查建议：并非所有建议都适用于每个用例
3. 考虑权衡：一些优化可以提高读取速度，但写入速度较慢
4. 文档更改：跟踪哪些建议得到执行

文档

📚 完整的文件:

• 用户指南 -综合使用示例
• API 参考 -完整的API文件
• 示例 -现实世界场景
• 生产指南 -部署和行动
• 快速参考 -命令参考

______________________________________________________________________

准备好优化Neo4j查询了吗？ 从 快速入门指南 然后潜入 用户指南 对于高级功能。

配置

运输方式

stdio（默认为本地） -对于Claude Desktop和CLI工具：

MCP_TRANSPORT=stdio

HTTP（建议用于网络） ⭐ - 现代流式HTTP（MCP 2025）：

MCP_TRANSPORT=http
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
MCP_SERVER_PATH=/mcp/
MCP_SERVER_ALLOWED_HOSTS=localhost,127.0.0.1

• 完全双向通信
• 多个并发客户端
• 负载平衡和自动扩展支持
• 为Docker部署做好生产准备

SSE（传统） -服务器发送事件以实现向后兼容性：

MCP_TRANSPORT=sse
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
MCP_SERVER_ALLOWED_HOSTS=localhost,127.0.0.1

• 单向（服务器→ 客户）
• 考虑迁移到HTTP以进行新部署

LLM提供商

OpenAI：

LLM_PROVIDER=openai
LLM_MODEL=gpt-4
LLM_API_KEY=sk-...

人类学（克劳德）：

LLM_PROVIDER=anthropic
LLM_MODEL=claude-3-5-sonnet-20241022
LLM_API_KEY=sk-ant-...

谷歌生成人工智能：

LLM_PROVIDER=google-genai
LLM_MODEL=gemini-1.5-flash
LLM_API_KEY=...

多数据库支持

Neo4j 企业版 支持多个命名数据库。使用连接到特定数据库 NEO4J_DATABASE 环境变量。

⚠️ 注： Neo4j社区版只支持一个用户数据库(neo4j).

单个数据库选择

启动时连接到特定数据库：

# Default database (works in both Community & Enterprise)
NEO4J_DATABASE=neo4j

# Custom database (Enterprise Edition only)
NEO4J_DATABASE=analytics
NEO4J_DATABASE=production

多实例模式（推荐）

运行多个MCP服务器实例，每个实例连接到不同的数据库：

使用docker-compose.multi-instance.yml：

# Start all instances (analytics, production, dev)
docker compose -f docker-compose.multi-instance.yml up -d

# Access different databases:
# - Analytics:  http://localhost:8001/mcp/
# - Production: http://localhost:8002/mcp/ (read-only)
# - Development: http://localhost:8003/mcp/

手动多实例：

# Instance 1: Analytics database
NEO4J_DATABASE=analytics MCP_SERVER_PORT=8001 python server.py

# Instance 2: Production database (read-only)
NEO4J_DATABASE=production NEO4J_READ_ONLY=true MCP_SERVER_PORT=8002 python server.py

# Instance 3: Development database
NEO4J_DATABASE=dev MCP_SERVER_PORT=8003 python server.py

社区版解决方案

选项1：基于标签的分离（在单个数据库内）

// Separate data using labels
CREATE (:Analytics:Product {name: "Widget"})
CREATE (:Production:Product {name: "Gadget"})

// Query specific domain
MATCH (p:Analytics:Product) RETURN p

选项2:DozerDB插件

• 为CommunityEdition添加多数据库支持
• 安装：添加 dozerdb 到Neo4j插件
• 请参阅： DozerDB文档

性能调整

# Response size limiting
NEO4J_RESPONSE_TOKEN_LIMIT=10000  # Truncate large responses

# Async workers
MCP_MAX_WORKERS=10  # Concurrent query execution threads

# Neo4j timeout
NEO4J_READ_TIMEOUT=30  # Query timeout in seconds

日志记录

LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s

MCP工具和资源速率限制

所有MCP工具和资源现在共享相同的装饰器堆栈，用于结构化日志记录和每个会话限制（通过键控 ctx.session_id).使用以下环境变量独立调整或禁用每个入口点：

当达到限制时，装饰器返回结构化JSON（用于工具）或纯文本消息（用于资源），并在元数据后重试。

完整配置参考

看 .env.示例 所有可用的配置选项都有详细的注释。

建筑

高级概述

MCP Client (Claude Desktop, web apps, etc.)
    ↓
FastMCP Server (stdio/HTTP/SSE transport)
    ↓
Security Layer (Sanitizer + Read-Only Check)
    ↓
Audit Logger (Compliance)
    ↓
LangChain GraphCypherQAChain (NL → Cypher)
    ↓
Neo4j Graph Database

关键组件

• FastMCP：使用装饰器实现MCP协议
• LangChain：自然语言到Cypher的翻译（GraphCypherQAChain）
• 查询消毒剂：多层注射预防(src/neo4j_yass_mcp/安全/消毒.py)
• 审计记录器：合规性记录(src/neo4j_yass_mcp/security/audit_logger.py)
• 异步执行器：用于并行Neo4j查询的线程池
• 响应限制器：LLM上下文管理的基于令牌的截断

安全架构

📖 详细文件： docs/SECURITY.md

纵深防御：

1. 输入消毒（注射预防）
2. 访问控制（只读模式）
3. 运行时验证（Cypher分析）
4. 审计日志记录（取证）
5. 响应限制（防止数据泄露）

示例工作流

自然语言查询

User: "Show me all actors who worked with Tom Cruise"
    ↓
query_graph() tool
    ↓
Sanitizer validates query
    ↓
LangChain generates: MATCH (a:Actor)-[:ACTED_IN]->(:Movie)<-[:ACTED_IN]-(tc:Actor {name: 'Tom Cruise'}) RETURN a.name
    ↓
Sanitizer validates generated Cypher
    ↓
Execute in Neo4j
    ↓
Return results + generated Cypher

直接密码执行

User: Execute custom Cypher with parameters
    ↓
execute_cypher(query, parameters)
    ↓
Sanitizer validates query + parameters
    ↓
Read-only check (if enabled)
    ↓
Execute in Neo4j
    ↓
Audit log: query + response + execution time
    ↓
Return results

发展

安装开发依赖项

uv pip install -e ".[dev]"

运行测试

pytest tests/

格式码

black .
ruff check .

故障排除

Neo4j连接问题

1. 验证Neo4j是否正在运行： neo4j status
2. 检查URI格式： bolt://localhost:7687
3. 验证中的凭据 .env
4. 检查防火墙设置

LLM API问题

1. 验证API密钥设置是否正确
2. 检查提供商和型号名称
3. 审查LLM提供者配额/限制
4. 检查网络连接

架构未加载

1. 跑 refresh_schema() 工具
2. 检查Neo4j数据库是否有数据
3. 验证中的数据库名称 NEO4J_DATABASE
4. 检查Neo4j用户权限

消毒剂阻止有效查询

1. 查看错误消息中的阻塞模式
2. 调整 SANITIZER_STRICT_MODE 如果过于严格
3. 启用特定功能： SANITIZER_ALLOW_APOC=true
4. 检查审核日志以了解详细信息

项目结构

neo4j-yass-mcp/
├── src/
│   └── neo4j_yass_mcp/          # Main package
│       ├── server.py            # MCP server entry point
│       ├── config/              # Configuration modules
│       │   ├── llm_config.py    # LLM provider configuration
│       │   └── utils.py         # General utilities
│       └── security/            # Security & compliance
│           ├── sanitizer.py     # Query sanitization
│           └── audit_logger.py  # Audit logging
├── tests/                       # Test suite
├── docs/                        # Documentation
├── Dockerfile                   # Container image definition
├── docker-compose.yml           # Multi-container orchestration
├── .dockerignore                # Docker build exclusions
├── run-server.sh                # Automated startup script
├── .env.example                 # Configuration template
├── pyproject.toml               # Package dependencies
└── README.md                    # This file

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

资源

• 模型上下文协议（MCP）
• FastMCP文档
• Neo4j文档
• LangChain文档

安全披露

关于安全问题，请发送电子邮件至security@\[您的域名\]，而不是使用公共问题跟踪器。

______________________________________________________________________

📖 详细文档：

• 文档_INDEX.md -完整的文档指南
• 安全架构： docs/SECURITY.md
• 软件架构： 文档/软件_建筑.md
• Docker部署： 医生.md
• 配置参考： .env.示例
• 速率限制示例： 示例/README_RATE_LIMITING.md
• 开发文件： 文档/开发/