NeoCoder: Neo4j-Guided AI Coding Workflow

NeoCoder：Neo4j 引导的 AI 编码工作流

一种 MCP 服务实现，使 Claude 等 AI 助手能够将 Neo4j 知识图谱用作主要的动态“操作手册”和项目记忆，以实现标准化编码工作流。

NeoCoder：混合 AI 推理与工作流系统

一种高级 MCP 服务实现，结合 Neo4j 知识图谱、Qdrant 向量数据库和复杂的 AI 编排，构建用于知识管理、研究分析和标准化工作流的混合推理系统。

概述

NeoCoder 实现了一种革命性的上下文增强推理系统，其能力远超传统 RAG（检索增强生成），具体方式如下：

核心架构：

1. Neo4j 知识图谱——权威的结构化事实、关系和工作流
2. Qdrant 向量数据库——语义搜索、相似性检测和上下文理解
3. MCP 编排——在数据源之间智能路由，并进行综合和引用
4. F-Contraction 综合——动态合并知识，同时保留来源归属信息

主要功能：

• 混合知识推理：无缝结合结构化事实与语义上下文
• 动态知识提取：将文档、代码和对话处理为相互关联的知识结构
• 基于引用的分析：在多个数据库中追踪每项声明的来源
• 多形态系统：为编码、研究、决策支持和知识管理提供专用模式
• 智能工作流模板：由 Neo4j 引导的流程，并包含强制验证步骤

革命性特性：

🧠 智能查询路由：AI 自动确定最佳数据源（图、向量或混合） 🔬 研究分析引擎：处理学术论文，并构建引用图谱和语义内容 ⚡ F-Contraction 处理：动态合并相似概念，同时保留来源信息 🎯 上下文增强推理：生成单一数据源无法实现的洞见 📊 完整审计跟踪：完整追踪知识综合和工作流执行 🛡️ 可用于生产环境的进程管理：自动清理、信号处理和资源追踪，以防止进程泄漏 🔧 增强的工具处理：稳健的异步初始化，并妥善管理后台任务

源自我的一个想法—— Lotka-Volterra 生态框架集成到知识图谱形态中

进程管理与可靠性

NeoCoder 遵循 MCP 最佳实践，实现了全面的进程管理：

• 信号处理器：妥善处理 SIGTERM/SIGINT，实现优雅关闭
• 资源追踪：自动追踪进程、Neo4j 连接和后台任务
• 僵尸进程清理：主动检测并清理孤立的服务实例
• 内存管理：通过妥善的清理模式防止资源泄漏
• 后台任务管理：安全处理异步初始化和并发操作
• 连接池：高效管理 Neo4j 驱动，并自动清理

监控命令

使用以下工具监控服务状态：

• get_cleanup_status() - 查看资源使用情况和清理状态
• check_connection() - 验证 Neo4j 连接和权限

快速开始

前置条件

• Neo4j：本地运行或远程实例（用于结构化知识图谱）

• Qdrant：用于语义搜索和嵌入的向量数据库（用于混合推理）

• Python 3.10+：用于运行 MCP 服务

• uv：MCP 服务的 Python 包管理器

• Claude Desktop：用于搭配 Claude AI 使用

• MCP-Desktop-Commander：对命令行和文件系统操作非常有用

• 用于 Lotka-Volterra 生态系统及增强整体能力——

• wolframalpha-llm-mcp：非常棒！

• mcp-server-qdrant-enhanced：我增强版的 Qdrant MCP 服务

• 可选，可提供更多实用功能

• arxiv-mcp-server

此版本仍在开发中

• 代码分析版本：AST/ASG：目前仍需开发并重写此版本

• 获取免费的 WolframAlpha API 密钥：

要获取免费的 Wolfram|Alpha API 密钥（AppID），你需要注册 Wolfram ID，然后在 Wolfram|Alpha Developer Portal 上注册一个应用程序。

创建 Wolfram ID：如果你还没有 Wolfram ID，请前往 https://account.wolfram.com/login/create 创建一个

前往 Developer Portal：拥有 Wolfram ID 后，登录 Wolfram|Alpha Developer Portal https://developer.wolframalpha.com/portal/myapps

注册你的第一个 AppID：点击“Sign up to get your first AppID”按钮。

填写 AppID 创建对话框：为你的应用程序提供名称和简单描述。

获取 AppID：填写所需信息后，系统会向你显示 API 密钥，也称为 AppID。

Wolfram|Alpha API 可免费用于非商业用途，每月最多可发起 2,000 次请求。

每个应用程序都需要单独的 AppID。

MCP 服务运行 Python 代码，连接 Neo4j 图数据库与 AI 助手（例如 Claude）

安装

1. 克隆仓库

git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git
cd NeoCoder-neo4j-ai-workflow

2. 设置 Python 和虚拟环境

确保已安装 pyenv 和 uv。

pyenv install 3.11.12  # if not already installed
pyenv local 3.11.12
uv venv
source .venv/bin/activate

3. 安装依赖项

uv pip install -e '.[dev,docs,gpu]'

4. 启动 Neo4j 和 Qdrant

• Neo4j： 启动 Neo4j 服务（本地或远程）。 默认连接地址：bolt://localhost:7687

Neo4j 连接参数：

• URL：bolt://localhost:7687（默认）

• 用户名：neo4j（默认）

• 密码：你的 Neo4j 数据库密码

• 数据库：neo4j（默认）

  如有需要，可通过环境变量设置凭据：

  • NEO4J_URL
  • NEO4J_USERNAME
  • NEO4J_PASSWORD
  • NEO4J_DATABASE

• Qdrant： 要使用持久化 Qdrant 存储，请使用此 Docker 命令（推荐）：

  docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant
  

  这会将 Qdrant 数据存储在项目目录下的 qdrant_storage 文件夹中。

5.（可选）VS Code 用户

• 打开命令面板（Ctrl+Shift+P），选择 Python: Select Interpreter，然后选择 .venv/bin/python。

1. 使用配置时应该会自动安装——我不太确定了，最近没试过，而且有些依赖项相当大。

潜在的快速入门——哈哈，抱歉

推荐：Claude Desktop 集成：

在 claude-app-config.json 中添加以下内容，以配置 Claude Desktop：

{
  "mcpServers": {
    "neocoder": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/NeoCoder-neo4j-ai-workflow",
        "run",
        "mcp_neocoder"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-neo4j-password-here",
        "NEO4J_DATABASE": "neo4j",
        "LOG_LEVEL": "INFO",
        "MCP_TRANSPORT": "stdio",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

重要：此配置中的密码必须与 Neo4j 数据库密码一致。

否则，请安装依赖项： 快速故障排查：

• 如果看到有关缺少软件包的错误，请仔细检查 .venv 是否已激活，以及是否使用了正确的 Python 版本。
• 如果需要重置环境，可以删除 .venv，然后重复上述步骤。
• 无法连接到数据库？请安装 neo4j Desktop 和 QDRANT，并确保它们正在运行。NEO4J 需要设置密码。

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

---

现在，你已经准备好使用 NeoCoder，体验完整的 Neo4j 和 Qdrant 混合 Lotka-Volterra 生态系统推理！

建议的系统提示词

> **System Instruction:** You are an AI assistant integrated with a Neo4j knowledge graph that defines our standard procedures and tracks project changes.
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Keyword:** Determine the action required (e.g., fix a bug -> `FIX`).
> 2.  **Consult the Hub:** If unsure about keywords or process, start by querying `:AiGuidanceHub {id: 'main_hub'}` for guidance and links to best practices or other guides.
> 3.  **Retrieve Instructions:** Formulate a Cypher query to fetch the `steps` from the current `:ActionTemplate` matching the keyword (e.g., `MATCH (t:ActionTemplate {keyword: 'FIX', isCurrent: true}) RETURN t.steps`). Execute this query.
> 4.  **Execute Guided Workflow:** Follow the retrieved `steps` meticulously. This includes reviewing project READMEs, implementing changes, and critically:
> 5.  **Perform Verification:** Execute the testing steps defined in the template. **ALL required tests MUST pass before you consider the task complete.**
> 6.  **Record Completion (Post-Testing):** Only if tests pass, formulate and execute the Cypher query specified in the template to create a `:WorkflowExecution` node, linking it appropriately. Do NOT record if tests failed.
> 7.  **Finalize Updates:** Update the project's README content (in Neo4j or the file) as per the template's instructions.
>
> **Strict Rule:** Always prioritize instructions retrieved from the Neo4j graph over your general knowledge for workflow procedures. Use the graph as your single source of truth for *how* tasks are done here.

---

> **knowledge_graph_incarnation with integrated Lotka Volterra Special System Instruction:** You are an AI assistant integrated with a sophisticated hybrid reasoning system that combines Neo4j knowledge graphs, Qdrant vector databases, and MCP orchestration for advanced knowledge management and workflow execution.
>
> **Your Core Capabilities:**
> 1. **Standard Coding Workflows:** Use Neo4j-guided templates for structured development tasks
> 2. **Hybrid Knowledge Reasoning:** Combine structured facts (Neo4j) with semantic search (Qdrant) for comprehensive analysis
> 3. **Dynamic Knowledge Synthesis:** Apply F-Contraction principles to merge and consolidate knowledge from multiple sources
> 4. **Multi-Modal Analysis:** Process research papers, code, documentation, and conversations into interconnected knowledge structures
> 5. **Citation-Based Reasoning:** Provide fully attributed answers with source tracking across databases
>
> **Your Core Interaction Loop:**
> 1.  **Identify Task & Context:** Determine the required action and select appropriate incarnation/workflow
> 2.  **Consult Guidance Hubs:** Query incarnation-specific guidance hubs for specialized capabilities and procedures
> 3.  **Execute Hybrid Workflows:** For knowledge tasks, use KNOWLEDGE_QUERY template for intelligent routing between graph and vector search
> 4.  **Apply Dynamic Synthesis:** Use KNOWLEDGE_EXTRACT template to process documents into both structured (Neo4j) and semantic (Qdrant) representations
> 5.  **Ensure Quality & Citations:** All knowledge claims must be properly cited with source attribution
> 6.  **Record & Learn:** Log successful executions for system optimization and learning
>
> **Hybrid Reasoning Protocol:**
> - **Graph-First**: Use Neo4j for authoritative facts, relationships, and structured data
> - **Vector-Enhanced**: Use Qdrant for semantic context, opinions, and nuanced information
> - **Intelligent Synthesis**: Combine both sources with conflict detection and full citation tracking
> - **F-Contraction Merging**: Dynamically merge similar concepts while preserving source attribution
>
> **Strict Rules:**
> - Always prioritize structured facts from Neo4j over semantic information
> - Every claim must include proper source citations
> - Use incarnation-specific tools and templates as single source of truth for procedures
> - Apply F-Contraction principles when processing multi-source information

---

Instructions for WolframAlpha use
- WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more.
- WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc.
- Convert inputs to simplified keyword queries whenever possible (e.g. convert "how many people live in France" to "France population").
- Send queries in English only; translate non-English queries before sending, then respond in the original language.
- Display image URLs with Markdown syntax: ![URL]
- ALWAYS use this exponent notation: `6*10^14`, NEVER `6e14`.
- ALWAYS use {"input": query} structure for queries to Wolfram endpoints; `query` must ONLY be a single-line string.
- ALWAYS use proper Markdown formatting for all math, scientific, and chemical formulas, symbols, etc.:  '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline.
- Never mention your knowledge cutoff date; Wolfram may return more recent data.
- Use ONLY single-letter variable names, with or without integer subscript (e.g., n, n1, n_1).
- Use named physical constants (e.g., 'speed of light') without numerical substitution.
- Include a space between compound units (e.g., "Ω m" for "ohm*meter").
- To solve for a variable in an equation with units, consider solving a corresponding equation without units; exclude counting units (e.g., books), include genuine units (e.g., kg).
- If data for multiple properties is needed, make separate calls for each property.
- If a WolframAlpha result is not relevant to the query:
 -- If Wolfram provides multiple 'Assumptions' for a query, choose the more relevant one(s) without explaining the initial result. If you are unsure, ask the user to choose.
 -- Re-send the exact same 'input' with NO modifications, and add the 'assumption' parameter, formatted as a list, with the relevant values.
 -- ONLY simplify or rephrase the initial query if a more relevant 'Assumption' or other input suggestions are not provided.
 -- Do not explain each step unless user input is needed. Proceed directly to making a better API call based on the available assumptions.

多种化身

NeoCoder 支持多种“化身”——不同的运行模式，可在保留核心 Neo4j 图结构的同时，适配专用用例。在图原生技术栈中，只需更换模板和执行策略，同一个 Neo4j 核心就能呈现出截然不同的“思维”。

核心架构原则

NeoCoder 的拆分方式具有很强的适应性，因为：

• Neo4j 将事实存储为一等图对象
• 工作流存储在模板节点中
• 执行引擎只需遍历图

由于这三个层级彼此正交，你可以冻结一个层级，同时改变其他层级——今天将代码调试器变成实验记录本，明天又变成学习管理系统。这种设计呼应了 Neo4j 自身从“图”走向“知识图谱”的成熟路径，在这一路径中，架构、语义和操作被有意解耦。

常见图架构模式

所有化身都共享以下核心元素：

元素	始终存在	典型标签 / 关系
参与者	人类 / Agent / 工具	(:Agent)-[:PLAYS_ROLE]->(:Role)
意图	假设、决策、经验、场景	(:Intent {type})
证据	文档、指标、观察结果	(:Evidence)-[:SUPPORTS]->(:Intent)
结果	通过 / 失败、收益、评分、状态向量	(:Outcome)-[:RESULT_OF]->(:Intent)

可用的化身：

• base_incarnation（默认）- 原始 NeoCoder、工具、模板和化身工作流管理
• research_incarnation - 用于假设跟踪和实验的科学研究平台
  • 注册假设、设计实验、记录实验过程并发布结果
  • Neo4j 为实验室工作流中的溯源试点提供支持，并支持谱系查询
• decision_incarnation - 决策分析和证据跟踪系统
  • 创建带有期望值指标的决策备选方案
  • 新证据到来时，贝叶斯更新 Agent 会重新计算指标的后验分布
  • 透明、可解释的推理流水线
• data_analysis_incarnation - 复杂系统建模与仿真
  • 使用状态向量和物理耦合关系对组件建模
  • 使用路径查询模拟故障传播
  • 可选的量子启发式调度器，用于参数测试
• knowledge_graph_incarnation - 高级混合推理系统
  • 混合知识查询：结合 Neo4j 结构化数据与 Qdrant 语义搜索
  • 动态知识提取：将文档处理为图和向量两种表示形式
  • F-Contraction 综合：智能合并相似概念，同时保留来源归属
  • 基于引用的推理：跨多个数据库完整跟踪来源
  • 研究分析引擎：用于学术论文处理的专用工作流
  • 智能查询路由：AI 自动确定最佳数据源策略
  • 跨数据库导航：无缝关联结构化事实与语义内容
  • 冲突检测：识别并标记来源之间的不一致
  • 实时知识综合：根据对话和文档动态构建图
• code_analysis_incarnation - 使用抽象语法树进行代码分析
  • 使用 AST 和 ASG 工具解析并分析代码结构
  • 跟踪代码复杂度和质量指标
  • 比较不同版本的代码
  • 根据代码分析生成文档
  • 识别代码异味和潜在问题

每种化身都提供一组专用工具，这些工具会在服务启动时自动注册。连接到 MCP 服务的 Claude 或其他 AI 助手均可使用这些工具。

实施路线图

NeoCoder 的实施路线图包括：

1. LevelEnv ↔ Neo4j 适配器：将事件映射为图结构并处理批量操作
2. 振幅寄存器（量子层）：用于叠加态的可选量子启发式层
3. 调度器：根据熵和影响评分确定任务优先级
4. 重用 TAG 资产：利用现有抽象实现垂直信息隐藏

从特定化身开始

# List all available incarnations
python -m mcp_neocoder.server --list-incarnations

# Start with a specific incarnation
python -m mcp_neocoder.server --incarnation continuous_learning

也可以在运行时使用 switch_incarnation() 工具切换化身：

switch_incarnation(incarnation_type="complex_system")

动态加载化身

NeoCoder 具有完全动态的化身加载系统，可自动发现并加载 incarnations 目录中的化身。这意味着：

1. 无需硬编码导入：无需修改 server.py 即可添加新化身
2. 自动发现：只需将符合 *_incarnation.py 格式的文件添加到 incarnations 目录
3. 所有工具均可用：所有化身中的工具都会注册并可供使用，即使相应化身未处于活动状态
4. 轻松扩展：使用提供的模板创建新化身

创建新 Incarnation

若要创建新的 Incarnation：

1. 在 src/mcp_neocoder/incarnations/ 目录中创建一个新文件，文件名遵循 your_incarnation_name_incarnation.py 的命名模式
2. 使用此模板结构：

"""
Your incarnation name and description
"""

import json
import logging
import uuid
from typing import Dict, Any, List, Optional, Union

import mcp.types as types
from pydantic import Field
from neo4j import AsyncTransaction

from .polymorphic_adapter import BaseIncarnation, IncarnationType

logger = logging.getLogger("mcp_neocoder.incarnations.your_incarnation_name")


class YourIncarnationNameIncarnation(BaseIncarnation):
    """
    Your detailed incarnation description here
    """

    # Define the incarnation type - must match an entry in IncarnationType enum
    incarnation_type = IncarnationType.YOUR_INCARNATION_TYPE

    # Metadata for display in the UI
    description = "Your incarnation short description"
    version = "0.1.0"

    # Initialize schema and add tools here
    async def initialize_schema(self):
        """Initialize the schema for your incarnation."""
        # Implementation...

    # Add more tool methods below
    async def your_tool_name(self, param1: str, param2: Optional[int] = None) -> List[types.TextContent]:
        """Tool description."""
        # Implementation...

3. 在 polymorphic_adapter.py 中的 IncarnationType 枚举中添加你的 Incarnation 类型
4. 重启服务，新 Incarnation 将自动被发现

有关使用和创建 Incarnation 的详细文档，请参阅 incarnations.md。

可用模板

NeoCoder 附带以下标准模板：

1. FIX - 修复已报告错误的指南，包括强制测试和日志记录
2. REFACTOR - 在保持功能不变的同时重构代码的结构化方法
3. DEPLOY - 在安全检查的前提下将代码部署到生产环境的指南
4. FEATURE - 以结构化方式实现新功能，并进行适当的测试和编写文档
5. TOOL_ADD - 向 NeoCoder MCP 服务添加新工具功能的流程
6. CYPHER_SNIPPETS - 管理和使用 Neo4j 查询的 Cypher 片段
7. CODE_ANALYZE - 使用 AST 和 ASG 工具分析代码的结构化工作流
8. KNOWLEDGE_QUERY - 用于智能多源推理的混合知识查询系统
9. KNOWLEDGE_EXTRACT - 通过 F-Contraction 合并进行动态知识提取与综合

高级混合推理系统

NeoCoder 采用革命性的 上下文增强推理 架构，结合多个数据源，实现前所未有的知识综合能力。

混合查询架构

KNOWLEDGE_QUERY 模板实现了复杂的 3 步推理流程：

第 1 步：智能查询路由器

• 意图分类：AI 分析查询，以确定最佳数据源策略
• 查询类型：
  • 图中心型：“谁与谁共事？”、“显示依赖链”
  • 向量中心型：“关于 X 的观点是什么？”、“查找关于 Y 的讨论”
  • 混合型：“[图谱中的某人] 对 [语义主题] 说了什么？”
• 执行规划：为复杂的混合查询设计多步计划

第 2 步：并行数据检索

• Neo4j 查询：执行 Cypher 查询，以获取结构化事实和关系
• Qdrant 搜索：对文档集合执行语义搜索
• 顺序优化：对于混合查询，使用图谱结果来优化向量搜索

第 3 步：跨数据库综合器

• 智能综合：将结构化事实与语义上下文相结合
• 来源优先级：Neo4j 事实为权威来源，Qdrant 用于补充细节和观点
• 强制引用：每项主张都必须注明具体来源
• 冲突检测：识别并标记不同数据源之间的不一致

动态知识提取（F-Contraction）

KNOWLEDGE_EXTRACT 模板实现了受图收缩原理启发的动态知识综合：

F-Contraction 核心概念：

• 顶点即概念：每个不同的概念都会成为一个图实体
• 边即关系：跟踪共现和显式连接
• 动态合并：通过 LLM 检测重复或相似概念
• 保留来源：合并后保留所有原始来源的指针

知识处理流水线：

1. 文档导入：解析 PDF、文本、代码和对话
2. 双重存储：将文本分块存入 Qdrant，将实体提取到 Neo4j
3. 实体提取：识别论文、作者、概念、方法等
4. 关系发现：查找引用、依赖和语义连接
5. F-Contraction 合并：智能整合相似实体
6. 交叉引用映射：将图实体链接到向量文档分块
7. 质量验证：确保一致性和完整性

研究分析引擎

用于处理学术和技术文档的专业能力：

• 引文图构建：构建论文关系网络
• 多跳推理：“通过引文链接追溯 Transformer 架构的演变”
• 冲突分析：“论文 A 对 X 的定义与论文 B 有何不同？”
• 时间综合分析：追踪概念在不同时间和来源中的演变
• 跨领域整合：整合多个研究领域的发现

混合推理的优势

1. 前所未有的综合分析能力：回答单一数据源无法解答的问题
2. 来源透明度：从原始数据到结论的完整审计跟踪
3. 冲突感知：明确处理相互矛盾的信息
4. 语义增强：为结构化事实补充上下文理解
5. 动态学习：通过 F-Contraction 合并改进知识库
6. 加速研究：快速分析复杂的学术文献

架构

知识图谱结构

• :AiGuidanceHub：AI 的中央导航中心
• :ActionTemplate：标准工作流模板（FIX、REFACTOR 等）
• :Project：项目数据，包括 README 和结构
• :File/Directory：项目文件结构表示
• :WorkflowExecution：已完成工作流的审计跟踪
• :BestPracticesGuide：编码标准和指南
• :TemplatingGuide：如何创建／修改模板
• :SystemUsageGuide：如何使用图系统

MCP 服务工具

MCP 服务向 AI 助手提供以下工具：

核心工具

• check_connection：验证 Neo4j 连接状态
• get_guidance_hub：AI 导航的入口点
• get_action_template：获取指定的工作流模板
• list_action_templates：查看所有可用模板
• get_best_practices：查看编码标准
• get_project：查看项目详情，包括 README
• list_projects：列出系统中的所有项目
• log_workflow_execution：记录成功完成的工作流
• get_workflow_history：查看已完成工作的审计跟踪
• add_template_feedback：提供模板反馈
• run_custom_query：运行直接的 Cypher 查询
• write_neo4j_cypher：在图上执行写入操作

化身管理工具

• get_current_incarnation：获取当前激活的化身
• list_incarnations：列出所有可用的化身
• switch_incarnation：切换到其他化身
• suggest_tool：根据任务描述获取工具建议

每个化身都会提供额外的专业工具，这些工具会在化身激活时自动注册。

知识图谱与混合推理工具

知识图谱版本提供了先进的混合推理能力，将结构化图数据与语义向量搜索相结合：

核心知识管理：

• create_entities：创建多个实体，包含观察记录并正确设置 Neo4j 标签
• create_relations：使用带类型的关系和时间戳连接实体
• add_observations：向现有实体添加带时间戳的观察记录
• delete_entities：删除实体，并级联删除相关关系
• delete_observations：定向删除特定观察内容
• delete_relations：删除特定关系，同时保留实体
• read_graph：查看包含实体、观察记录和关系的完整知识图谱
• search_nodes：在实体名称、类型和观察内容中进行全文搜索
• open_nodes：获取实体详细信息，包括传入和传出的关系

高级混合推理工具：

• KNOWLEDGE_QUERY 工作流：智能混合查询系统

  • 智能查询路由（以图谱为中心、以向量为中心或混合模式）
  • 从 Neo4j 和 Qdrant 并行检索数据
  • 跨数据库综合分析，并强制追踪引用
  • 冲突检测和来源优先级排序

• KNOWLEDGE_EXTRACT 工作流：使用 F-Contraction 动态提取知识

  • 摄取文档并提取元数据
  • 双重存储：在 Qdrant 中存储文本块，在 Neo4j 中存储实体
  • 由大模型驱动的实体提取和关系发现
  • 使用 F-Contraction 合并相似概念，同时保留来源
  • 建立图数据与向量数据之间的交叉引用映射
  • 质量验证和提取报告

研究分析能力：

• 引用图谱构建：构建论文、作者和机构网络
• 多跳综合分析：通过相互关联的来源追踪概念演变
• 时间分析：追踪随时间发生的变化和发展
• 冲突解决：处理多个来源之间相互矛盾的信息
• 来源归属：从原始数据到结论，全程追踪信息来源

集成功能：

• Qdrant 集合：与向量数据库无缝集成，实现语义搜索
• 跨数据库导航：在结构化数据与语义数据之间实现双向链接
• 记忆集成：连接长期记忆系统，保持连续性
• MCP 编排：高级工具协调和工作流管理

Cypher 代码片段工具包

MCP 服务包含一个用于管理和搜索 Cypher 查询代码片段的工具包：

• list_cypher_snippets：列出所有可用的 Cypher 代码片段，并支持可选筛选
• get_cypher_snippet：根据 ID 获取指定的 Cypher 代码片段
• search_cypher_snippets：按关键字、标签或模式搜索 Cypher 代码片段
• create_cypher_snippet：向数据库添加新的 Cypher 代码片段
• update_cypher_snippet：更新现有的 Cypher 代码片段
• delete_cypher_snippet：从数据库中删除 Cypher 代码片段
• get_cypher_tags：获取 Cypher 代码片段使用的所有标签

此工具包提供了一个可搜索的 Cypher 查询模式和示例库，可用作参考和学习工具。

工具提案系统

MCP 服务包含一个用于提议和申请新工具的系统：

• propose_tool：为 NeoCoder 系统提议新工具
• request_tool：以用户身份申请新的工具功能
• get_tool_proposal：获取指定工具提案的详细信息
• get_tool_request：获取指定工具申请的详细信息
• list_tool_proposals：列出所有工具提案，并支持可选筛选
• list_tool_requests：列出所有工具申请，并支持可选筛选

此系统允许 AI 助手提议新工具，也允许用户申请新功能，从而以结构化的方式管理和跟踪功能请求。

自定义模板

模板以 .cypher 文件的形式存储在 templates 目录中。你可以编辑现有模板，也可以创建新模板。

添加新模板的方法：

1. 在 templates 目录中创建新文件（例如，custom_template.cypher）
2. 遵循现有模板的格式
3. 初始化数据库，将模板加载到 Neo4j 中

“Cypher Snippet Toolkit”工具基于以下图结构运行

下面是一套整合后的 适用于 Neo4j 5 系列工具包，可直接粘贴到 Neo4j Browser、Cypher shell 或任何驱动程序中。 它会创建一个微型文档图，其中每个 (:CypherSnippet) 节点都存储一段 Cypher 语法、一个示例和元数据；文本索引和（可选的）向量索引可让你通过普通关键词或嵌入向量即时搜索代码片段。

---

1 · 架构与安全约束

// 1-A Uniqueness for internal IDs
CREATE CONSTRAINT cypher_snippet_id IF NOT EXISTS
FOR   (c:CypherSnippet)
REQUIRE c.id IS UNIQUE;            // Neo4j 5 syntax

// 1-B Optional tag helper (one Tag node per word/phrase)
CREATE CONSTRAINT tag_name_unique IF NOT EXISTS
FOR   (t:Tag)
REQUIRE t.name IS UNIQUE;

2 · 为搜索提供支持的索引

// 2-A Quick label/property look-ups
CREATE LOOKUP INDEX snippetLabelLookup IF NOT EXISTS
FOR (n) ON EACH labels(n);

// 2-B Plain-text index (fast prefix / CONTAINS / = queries)
CREATE TEXT INDEX snippet_text_syntax IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.syntax);

CREATE TEXT INDEX snippet_text_description IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.description);

// 2-C Full-text scoring index (tokenised, ranked search)
CREATE FULLTEXT INDEX snippet_fulltext IF NOT EXISTS
FOR (c:CypherSnippet) ON EACH [c.syntax, c.example];

// 2-D (OPTIONAL) Vector index for embeddings ≥Neo4j 5.15
CREATE VECTOR INDEX snippet_vec IF NOT EXISTS
FOR (c:CypherSnippet) ON (c.embedding)
OPTIONS {indexConfig: {
  `vector.dimensions`: 384,
  `vector.similarity_function`: 'cosine'
}};

如果你的版本为 ≤5.14，请改用 db.index.vector.createNodeIndex。

3 · 存储代码片段的模板

:params {
  snippet: {
    id:         'create-node-basic',
    name:       'CREATE node (basic)',
    syntax:     'CREATE (n:Label {prop: $value})',
    description:'Creates a single node with one label and properties.',
    example:    'CREATE (p:Person {name:$name, age:$age})',
    since:      5.0,
    tags:       ['create','insert','node']
  }
}

// 3-A MERGE guarantees idempotence
MERGE (c:CypherSnippet {id:$snippet.id})
SET   c += $snippet
WITH  c, $snippet.tags AS tags
UNWIND tags AS tag
  MERGE (t:Tag {name:tag})
  MERGE (c)-[:TAGGED_AS]->(t);

参数映射可让代码重复使用，并避免重新编译查询计划。

4 · 搜索方法

4-A 通过 TEXT 索引进行精确／前缀匹配

MATCH (c:CypherSnippet)
WHERE c.name STARTS WITH $term      // fast TEXT index hit
RETURN c.name, c.syntax, c.example
ORDER BY c.name;

4-B 排序全文搜索

CALL db.index.fulltext.queryNodes(
  'snippet_fulltext',               // index name
  $q                                // raw search string
) YIELD node, score
RETURN node.name, node.syntax, score
ORDER BY score DESC
LIMIT 10;

4-C 嵌入相似度（向量搜索）

WITH $queryEmbedding AS vec
CALL db.index.vector.queryNodes(
  'snippet_vec', 5, vec            // top-5 cosine hits
) YIELD node, similarity
RETURN node.name, node.syntax, similarity
ORDER BY similarity DESC;

5 · 更新或删除代码片段

// 5-A Edit description
MATCH (c:CypherSnippet {id:$id})
SET   c.description = $newText,
      c.lastUpdated = date()
RETURN c;

// 5-B Remove a snippet cleanly
MATCH (c:CypherSnippet {id:$id})
DETACH DELETE c;

这两种操作都会自动维护索引一致性，无需额外操作。

6 · 批量导出／导入（APOC）

CALL apoc.export.cypher.all(
  'cypher_snippets.cypher',
  {useOptimizations:true, format:'cypher-shell'}
);

这会生成可供分享的 Cypher 代码，可通过 cypher-shell < cypher_snippets.cypher 重新执行。

---

快速入门回顾

1. 每个数据库运行一次第 1 节和第 2 节，以设置约束和索引。
2. 使用第 3 节（由参数驱动）添加新的文档条目。
3. 使用第 4 节进行查询；如果存储了嵌入向量，还可以添加向量搜索。
4. 使用第 6 节进行备份或发布。

有了这些构建模块，你现在就拥有了一份动态的“Cypher 中的 Cypher 速查表”，它始终保留在本地，可进行版本管理并且易于扩展。随着查询技巧不断丰富，你可以轻松回顾！

注意：此文档的完整参考版本保留了所有原始格式，可在 /docs/cypher_snippets_reference.md 文件中查看。

由 angrysky56 创建 Claude 3.7 Sonnet Gemini 2.5 Pro Preview 3-25 ChatGPT o3

代码分析

/analysis 目录中提供了 NeoCoder 代码库的全面分析。内容包括：

• 架构概览
• Incarnation 系统分析
• 代码指标与结构
• 工作流模板分析
• 集成点
• 未来开发建议

最近更新

2025-06-24：革命性的混合推理系统（v2.0.0）

• 重大突破：实现上下文增强推理架构，结合 Neo4j、Qdrant 和 LLM 综合分析
• 新增：KNOWLEDGE_QUERY 操作模板——3 步混合推理系统：
  • 智能查询路由器：AI 对意图进行分类并规划执行策略
  • 并行数据检索：无缝查询 Neo4j 和 Qdrant
  • 跨数据库综合器：智能综合，并强制跟踪引用
• 新增：KNOWLEDGE_EXTRACT 操作模板——F-Contraction 知识综合：
  • 将文档动态处理为图和向量两种表示形式
  • 由 LLM 驱动的实体提取和关系发现
  • 智能合并概念，同时保留来源归属信息
  • 在结构化数据与语义数据之间建立交叉引用映射
• 增强：知识图谱化身，具备先进的混合能力：
  • 修复指导中心的事务错误，带来流畅的用户体验
  • 实现复杂的研究分析工作流
  • 添加冲突检测和来源优先级排序
  • 与 Qdrant 向量数据库全面集成，实现语义搜索
• 架构：为上下文增强推理奠定基础，能力远超传统 RAG
• 验证：使用真实研究论文语料成功测试，展示了引文图谱与语义分析能力
• 影响：实现了依靠单一数据源无法完成的突破性知识综合

2025-06-14：修复关键的异步／事件循环管理问题（v1.4.1）

• 关键修复：解决 safe_neo4j_session 函数中的异步上下文管理器协议错误
• 根本原因：测试中的 AsyncMock 和某些驱动配置返回的是协程，而非异步上下文管理器
• 解决方案：添加 _handle_session_creation 辅助函数，用于检测并正确处理协程和上下文管理器
• 影响：消除“TypeError: 'coroutine' object does not support the asynchronous context manager protocol”错误
• 测试：新增全面的测试套件（test_event_loop_fix.py），以防止问题复发
• 兼容性：与现有 Neo4j 驱动用法保持完全向后兼容
• 修改文件：src/mcp_neocoder/event_loop_manager.py、tests/test_event_loop_fix.py

2025-04-27：新增支持 AST/ASG 的代码分析化身（v1.4.0）

• 新增 code_analysis_incarnation.py，使用 AST 和 ASG 工具进行深度代码分析
• 实现用于存储代码结构和分析结果的 Neo4j 架构
• 添加 CODE_ANALYZE 操作模板，提供分步工作流
• 创建用于代码分析的专用工具：
  • analyze_codebase：分析整个目录结构
  • analyze_file：深度分析单个文件
  • compare_versions：比较不同版本的代码
  • find_code_smells：识别潜在的代码问题
  • generate_documentation：自动生成代码文档
  • explore_code_structure：浏览代码结构
  • search_code_constructs：查找特定模式的代码
• 与外部 AST/ASG 工具集成
• 在指导中心添加适当的文档
• 更新 IncarnationType 枚举，加入 CODE_ANALYSIS 类型

2025-04-27：消除知识图谱事务错误消息（v1.3.2）

• 完全消除了知识图谱函数中与事务作用域问题相关的错误消息
• 实现服务端错误消息拦截与替换，带来更顺畅的用户体验
• 为所有数据库操作新增了更安全的执行模式：
  • 创建 _safe_execute_write 方法，消除写入操作中的事务作用域错误
  • 创建 _safe_read_query 方法，确保正确处理读取操作的事务
  • 改进实体计数跟踪，确保操作反馈准确
• 增强错误恢复能力，即使 JSON 解析失败也能继续执行操作
• 简化并改进了所有知识图谱工具的实现
• 完全兼容现有知识图谱数据
• 改进指南中心，提供更清晰的使用示例

2025-04-27：修复知识图谱事务作用域问题（v1.3.1）

• 修复了知识图谱函数返回“事务超出作用域”错误的严重问题
• 为所有知识图谱操作实现了事务安全的处理方式
• 更新所有知识图谱工具，使其能够正确处理事务上下文：
  • 修复 create_entities，使其能够正确返回结果
  • 采用简化的处理方式修复 create_relations
  • 修复 add_observations，确保数据已提交
  • 修复 delete_entities、delete_observations 和 delete_relations 函数
  • 修复 read_graph，通过多个安全事务获取数据
  • 采用更稳健的查询方式修复 search_nodes
  • 修复 open_nodes，以安全方式查询实体详情
• 改进指南中心，清晰展示知识图谱工具的使用示例
• 改进知识图谱操作中的错误处理
• 保持与现有知识图谱数据的向后兼容性

2025-04-26：修复知识图谱 API 函数（v1.3.0）

• 修复知识图谱 API 函数无法与 Neo4j 节点标签系统正确集成的问题
• 实现带有正确标签 :Entity 的实体，而非通用的 :KnowledgeNode
• 添加了完整的知识图谱管理函数：
  • create_entities：创建带有正确标签和观察信息的实体
  • create_relations：通过类型化关系连接实体
  • add_observations：为现有实体添加观察信息
  • delete_entities：移除实体及其连接
  • delete_observations：从实体中移除指定观察信息
  • delete_relations：移除实体之间的关系
  • read_graph：查看完整的知识图谱结构
  • search_nodes：按名称、类型或观察内容查找实体
  • open_nodes：获取特定实体的详细信息
• 添加了全文搜索支持，并为不支持全文搜索的环境提供回退方案
• 为知识图谱添加了正确的模式初始化，包括约束和索引
• 更新指南中心内容，添加新 API 函数的使用说明

2025-04-25：扩展化身文档（v1.2.0）

• 添加了关于多个化身背后架构原则的详细文档
• 扩展了对各化身类型的说明，补充了运行模式和用例
• 添加了关于各化身共有图模式的说明
• 纳入了集成量子启发方法的实施路线图

2025-04-24：修复 Incarnation 工具注册问题（v1.1.0）

• 修复服务器启动时 Incarnation 工具未能正确注册的问题
• 修复重复类定义导致的循环依赖问题
• 支持通过 _tool_methods 类属性显式声明工具方法
• 改进工具发现机制，确保正确检测每个 Incarnation 中的所有工具
• 改进事件循环处理，避免服务器初始化期间出现问题
• 增加全面的日志记录，帮助排查问题
• 修复模式初始化，使其延迟到需要时再执行

详细的实现说明请参阅 CHANGELOG.md 文件。

许可证

MIT 许可证