graph-arch
Installs Git hooks that trigger review of graph change intents on push/merge, ensuring declared graph changes match actual code changes.
Allows Hermes agents to register and use the MCP server for graph-aware development workflows, such as impact analysis and task management.
Provides tools to query and update a Neo4j graph representing code architecture, including impact analysis, context lookup, and graph change intents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@graph-arch What's the impact of changing dataset_b?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
graph-arch
Graph database-driven code architecture management system — use Neo4j to maintain a three-layer dependency graph of "requirements / code modules / data", with Agent development auto-fill, one-click change impact queries, and Hook reactive linkage for multi-Agent collaboration.
One-sentence configuration instruction for AI: "Read this README and complete the installation and configuration of this project according to the 'Quick Start' section."
What this project is
Existing tools cannot answer "if I change a data structure, what are all the places that need updating" — IDEs only recognize code imports, build systems only recognize compile dependencies, and data lineage only recognizes data pipelines. This project puts code, data, tools, and requirements into the same graph:
AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
└──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端Impact analysis: for any node change, one Cypher query finds all downstream nodes
Strong gating: Agent declares graph changes (intent request) → git commit triggers review verification → only writes to graph after passing; failures can't even get a commit in
Reactive Hook: graph changes are distributed to relevant Agents according to subscriptions; propagation naturally converges when there are no changes
Desktop client: visualize graph data + view in-progress tasks
Design details: docs/design-v1.1.md, program structure: docs/architecture.md.
Related MCP server: codemap
Quick Start
Prerequisites
Windows 10/11 (Git Bash available)
Python ≥ 3.11 (verify with
python --version)Optional: OpenAI-compatible LLM API (for review / nightly maintenance agent, defaults to
http://localhost:8642/v1, configurable or skippable)
One-command configuration (hand off to AI)
Say to any AI assistant after cloning this project:
"Read README.md, execute the quick start installation process, and complete this project's configuration."
The only core command the AI should execute:
python setup/setup.pyThis script fully automatically completes the following steps (each step provides clear manual takeover instructions on failure):
Step | Action | Artifact |
1 | Check Python version | Exit with prompt if version mismatch |
2 | Download and extract JDK 21 (Temurin, multi-mirror) |
|
3 | Download and extract Neo4j Community 5.x (multi-mirror) |
|
4 | Start Neo4j service and initialize password | Password defaults to |
5 | Create |
|
6 | Apply graph schema (constraints + indexes + sample pipeline seed data) | Three-layer graph in Neo4j |
7 | Register MCP server to | WorkBuddy can directly call 6 tools |
8 | Smoke test: run impact query once | Should return 8 downstream nodes |
9 | Output next-step instructions | Desktop client startup / git hooks / exe packaging |
Estimated time: 5–15 minutes on first run (depends on download speed of JDK + Neo4j, ~380MB total). Resumable: the script is idempotent at each step; fix the issue and rerun, completed steps are automatically skipped.
Manual step-by-step (if you don't want the one-command script)
# 1. 依赖
python -m venv .venv && .venv/Scripts/pip install -e .
# 2. Neo4j(手动下载 zip 解压到 runtime/neo4j/,需要 JDK 21)
runtime/neo4j/bin/neo4j.bat install-service
runtime/neo4j/bin/neo4j.bat start
# 3. 初始化密码(首次默认 neo4j/neo4j,登录后强制改)
runtime/neo4j/bin/cypher-shell.bat -u neo4j -p neo4j \
"ALTER CURRENT USER SET PASSWORD FROM 'neo4j' TO 'graph123';"
# 4. 应用 schema 与种子数据
.venv/Scripts/python -m graph_arch.setup_db
# 5. 注册 MCP(见下方「接入 Agent Harness」)
# 6. 验证
.venv/Scripts/python -c "from graph_arch.graph.queries import impact; \
print(len(impact('data:dataset_b')), '个下游节点') # 应输出 8"Desktop client (visualization + activity monitoring)
# 开发运行
.venv/Scripts/python desktop/main.py
# 打包为独立 exe(产物在 desktop/dist/)
.venv/Scripts/python desktop/build_exe.pyFeatures:
Graph visualization: color-coded by layer (requirements/modules/data), click a node for details (summary, pointers, status, neighborhood)
Activity panel: pending intent requests, task queue, recent changelog stream, stale node list
Auto-refresh every 5 seconds
Integrating with Agent Harness
WorkBuddy
setup.py automatically writes to ~/.workbuddy/mcp.json. After restarting WorkBuddy, the following appear in the tools directory:
submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks
Hermes
If Hermes supports MCP: register this server the same way (python -m graph_arch.mcp_server, working directory is the repository root).
If it only supports OpenAI function calling: tool definitions are in the docstring of src/graph_arch/mcp_server.py and can be directly converted to OpenAI tools format.
Agent workflow instructions (paste into system prompt or make into a skill)
开发工作流(必须遵守):
1. 接到任何修改类任务,先调 query_context 加载目标节点邻域(摘要+指针+状态)
2. 若涉及已有数据结构/模块,必须调 query_impact 确认影响范围
3. 按指针从源头(git/文档/schema)加载细节后开工
4. 完成后必须 submit_graph_intent 声明图变更,再创建 git 提交
5. review 失败则按返回原因修正,重新提交Directory structure
graph-arch/
├── README.md # 本文件
├── pyproject.toml # 包定义与依赖
├── docs/ # 设计文档(v1.1)+ 结构文档
├── setup/setup.py # 一键安装脚本
├── config/
│ ├── settings.yaml # Neo4j/LLM/路径/超时(setup 自动生成)
│ ├── hooks.yaml # Hook 规则注册
│ └── skill_routes.yaml # skill 路由表(harness 层)
├── schema/ # Cypher:约束 + 种子数据
├── src/graph_arch/
│ ├── graph/ # client / writer / queries / merger
│ ├── hooks/ # engine / cycle_guard / actions
│ ├── review/ # 核验协议 + LLM 调用
│ ├── tasks/ # 任务队列 + 死信队列
│ ├── mcp_server.py # 入口 1: MCP server(常驻)
│ ├── git_hook.py # 入口 2: git hooks(pre-receive/post-merge)
│ ├── nightly.py # 入口 3: 夜间维护(定时)
│ └── setup_db.py # schema 初始化
├── desktop/ # 桌面端(PySide6 + vis-network)
├── git-hooks/ # 仓库钩子 + 安装脚本
├── changelog/ # append-only 变更日志(JSONL)
├── runtime/ # JDK / Neo4j(setup 下载,不入 git)
└── tests/Configuration (config/settings.yaml)
Key | Default | Description |
|
| Neo4j connection |
|
| Written after setup initialization |
|
| OpenAI-compatible endpoint (for review/maintenance, can be left empty to skip) |
|
| Model name |
|
| Max trigger count for the same node in the same Hook chain (loop prevention) |
|
| Task claim timeout (reassign/dead-letter on timeout) |
|
| Changelog directory |
Installing git hooks (target code repository)
bash git-hooks/install.sh /path/to/your/code-repoAfter that, push/merge on that repository will trigger review verification and graph merging.
Troubleshooting
Symptom | Resolution |
Neo4j download failed (403/timeout) | Manually download |
| Confirm |
bolt connection refused | Check service status with |
LLM connection failure during review step | LLM can be left empty: set |
MCP tools not appearing | Restart harness; confirm |
License
MIT (modify as needed)
Available Tools
7 toolsclaim_taskClaim TaskA
认领一个 Hook 分发的任务(多 Agent 防撞车的排他锁定)。
何时必须调用:
收到任务通知、评估后确认需要响应时,开发之前先认领
认领成功才开工;返回 rejected 说明他人已认领,直接放弃
何时不需要:
评估后确认无需变更时(不认领,让任务自然超时或被他人处理)
参数:
task_id: 任务 id(来自 get_pending_tasks)
agent_id: 你的 Agent 角色 id(稳定命名,与订阅关系关联)
返回: {status: claimed|rejected, task_id, ...}
Inputs: task_id (required), agent_id (required). Returns: object
get_pending_intentsGet Pending IntentsA
查看待核验的意图请求(review agent 专用)。
何时调用:
你是 Review Agent,git hook 触发你执行核验时
排查「为什么图没更新」时检查是否有滞留的 pending
何时不需要:
普通开发任务(你不应该消费别人的意图请求)
返回: 意图请求列表(完整 JSON)
Inputs: no named parameters. Returns: result
get_pending_tasksGet Pending TasksA
拉取任务队列(被动触达的 pull 端)。harness 执行循环中每轮调用。
何时必须调用:
Agent 执行循环的每轮迭代开始时(检查是否有 Hook 分发给你的任务)
何时不需要:
正在处理一个任务的中间(先完成当前任务)
参数:
status: pending(待认领)/ claimed(已认领)/ completed
返回: 任务列表 [{task_id, source_node, message, subscribers, status, ...}] 对订阅了你的任务: 先 query_impact 评估 → 需响应则 claim_task 后开工
Inputs: status. Returns: result
graph_revisionGraph RevisionA
查询当前图版本号(写意图请求时填入 base_revision,用于过期检测)。
Inputs: no named parameters. Returns: object
query_contextQuery ContextA
图导航:查询节点的邻域导航信息,用于 Agent 诞生后构建工作上下文。
何时必须调用:
接到任何涉及已有节点(数据结构/模块/需求)的任务时,第一步调用
收到 Hook 任务通知、需要了解变更节点的宏观环境时
何时不需要:
已经持有该节点邻域信息的连续会话中(避免重复调用)
参数:
node_id: 图节点 id
返回: {id, type, layer, name, summary, path, status, skill_hint, neighborhood} 返回的是导航信息而非内容本身——按 path 指针从源头(git/文档/schema)加载细节。 skill_hint 是处理建议,实际路由由 harness 的 skill_routes.yaml 决定。
Inputs: node_id (required). Returns: object
query_impactQuery ImpactA
查询一个图节点的变更影响范围(谁会被这个节点的变更波及)。
何时必须调用:
修改任何已有数据结构、模块或需求之前
收到图变更通知、评估自己负责区域是否需要更新时
规划跨模块任务、需要完整依赖上下文时
何时不需要:
纯新增且明确无下游依赖的独立模块
参数:
node_id: 图节点 id(命名规范: data:user_table / module:auth_svc / req:login)
direction: "downstream"=谁被我影响 / "upstream"=我依赖谁
返回: [{id, layer, type, status, summary, path, hops}] 按传播距离排序。 返回的 path 是指针——细节由 skill 按指针从源头加载,不要向本工具索要内容全文。
Inputs: node_id (required), direction. Returns: result
submit_graph_intentSubmit Graph IntentA
提交图变更意图请求(开发完成后的必经步骤)。缓存为 pending,git 提交后由 review 核验。
何时必须调用:
完成任何涉及图变更的开发任务后、创建 git commit 之前
变更包括: 新增/修改节点(模块/数据结构/需求)、新增/删除依赖边
何时不需要:
未产生任何结构变更的纯阅读/查询任务
参数:
intent_json: JSON 字符串,结构: {task_id, base_revision, nodes_to_create:[{id,label,props}], nodes_to_update:[{id,props}], edges_to_create:[{from,type,to,props}], edges_to_remove:[{from,type,to}], work_notes, summary, actor} work_notes 必填工作过程状态: 为什么这么改、考虑过什么备选(下一个实例靠它重建场景)
返回: {status: "pending", task_id, path} 注意: 本工具只缓存不写入——review 失败(git 提交被拒)时 pending 不会进图。
Inputs: intent_json (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
query_impact and query_context are clearly differentiated by their focus (propagation vs. navigation), and the core command/voting tools are distinct. However, get_pending_intents and get_pending_tasks share a similar prefix and both return lists, so an agent could initially confuse them; descriptions mitigate but do not fully eliminate this.
Most tools follow a snake_case verb_noun pattern (query_impact, submit_graph_intent, claim_task, get_pending_tasks, get_pending_intents). graph_revision deviates as a noun-only identifier, and there is minor verb variance (query vs. get vs. submit), but the overall pattern is readable and predictable.
Seven tools is well within the ideal range for a specialized graph/context server. Each tool serves a distinct part of the investigate-assess-claim-submit-review workflow with no obvious redundancy or bloat.
The tool surface covers the core lifecycle: context discovery, impact analysis, task retrieval/claiming, intent submission, pending-intent review, and revision tracking. Minor gaps exist—such as no explicit intent-cancellation or node-detail tool—but query_context and query_impact fill most needs and the workflow appears functional.
Maintenance
Related MCP Connectors
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI-native code intelligence graph that builds a persistent knowledge graph of your codebase in Neo4j and exposes it to AI assistants via MCP, enabling contextual code analysis, impact analysis, and dependency tracking.23MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.2MIT
- FlicenseNot gradedqualityBmaintenanceMCP server for indexing source code from repositories into a Neo4j graph database and enabling Graph RAG-based search and traversal of functions via natural language queries.-
- AlicenseNot gradedqualityBmaintenanceLocal-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.1MIT