グラフデータベース駆動のコードアーキテクチャ管理システム —— Neo4j で「要件 / コードモジュール / データ」の3層依存グラフを管理し、Agent 開発が自動でデータを投入、変更影響をワンクリックで照会、Hook がリアクティブに複数 Agent の連携を実現します。
AI への一言設定指示：「この README を読み、『クイックスタート』の章に従って本プロジェクトのインストールと設定を完了してください。」
既存のツールでは「データ構造を変更したとき、更新が必要な箇所はどこか」という問いに答えられません——IDE はコードの import しか認識せず、ビルドシステムはコンパイル依存しか認識せず、データリネージはデータパイプラインしか認識しません。本プロジェクトはコード、データ、ツール、要件を1つのグラフにまとめます：
AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
└──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端影響分析：任意ノードの変更に対し、1つの Cypher クエリで全下流を検出
強力なゲート：Agent がグラフ変更を宣言（意図リクエスト）→ git コミットが review 検証をトリガー → 通過時のみグラフに書き込み、失敗時はコミット自体が拒否
リアクティブ Hook：グラフ変更を購読に基づき関連 Agent へ配信、変更がなければ伝播は自然に収束
デスクトップ版：グラフデータの可視化 + 進行中タスクの確認
設計詳細は docs/design-v1.1.md、プログラム構造は docs/architecture.md を参照。
Related MCP server: codemap
Windows 10/11（Git Bash 使用可）
Python ≥ 3.11（python --version で確認）
任意：OpenAI 互換 LLM API（review / 夜間メンテナンス agent 用、デフォルトは http://localhost:8642/v1、設定で変更またはスキップ可）
本プロジェクトをクローンした任意の AI アシスタントに次のように伝えます：
「README.md を読み、クイックスタートのインストール手順を実行し、本プロジェクトの設定を完了してください。」
AI が実行すべき唯一のコアコマンド：
python setup/setup.pyこのスクリプトは以下の手順を全自動で実行します（各ステップで失敗した場合、明確な手動対応手順を表示）：
手順 | 動作 | 成果物 |
1 | Python バージョンの確認 | バージョン不一致の場合は終了し、案内を表示 |
2 | JDK 21 のダウンロードと解凍（Temurin、複数ミラーソース） |
|
3 | Neo4j Community 5.x のダウンロードと解凍（複数ミラーソース） |
|
4 | Neo4j サービスの起動とパスワード初期化 | パスワードはデフォルト |
5 |
|
|
6 | グラフスキーマの適用（制約 + インデックス + サンプルパイプラインのシードデータ） | Neo4j 内の3層グラフ |
7 | MCP server の | WorkBuddy から6つのツールを直接呼び出し可能 |
8 | Smoke test：impact query を1回実行 | 8つの下流ノードが返るべき |
9 | 以降の手順の案内を出力 | デスクトップ版起動 / git hooks / exe パッケージ化 |
想定所要時間：初回は約5〜15分（JDK + Neo4j 合計 ~380MB のダウンロード速度に依存）。途中再開：スクリプトは各ステップが冪等で、失敗後に修正して再実行すれば、完了済みのステップは自動的にスキップされます。
# 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"# 开发运行
.venv/Scripts/python desktop/main.py
# 打包为独立 exe（产物在 desktop/dist/）
.venv/Scripts/python desktop/build_exe.py機能：
グラフ可視化：レイヤーごとに色分け（要件/モジュール/データ）、ノードをクリックして詳細表示（要約、ポインタ、ステータス、近傍）
アクティビティパネル：pending の意図リクエスト、タスクキュー、最近の changelog フロー、stale ノード一覧
5秒ごとに自動更新
setup.py が ~/.workbuddy/mcp.json に自動的に書き込みます。WorkBuddy を再起動すると、ツール一覧に以下が表示されます：
submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks
Hermes が MCP をサポートする場合：同様に本サーバーを登録します（python -m graph_arch.mcp_server、作業ディレクトリはリポジトリルート）。
OpenAI function calling のみをサポートする場合：tools 定義は src/graph_arch/mcp_server.py の docstring にあり、そのまま OpenAI tools 形式に変換できます。
开发工作流（必须遵守）:
1. 接到任何修改类任务，先调 query_context 加载目标节点邻域（摘要+指针+状态）
2. 若涉及已有数据结构/模块，必须调 query_impact 确认影响范围
3. 按指针从源头（git/文档/schema）加载细节后开工
4. 完成后必须 submit_graph_intent 声明图变更，再创建 git 提交
5. review 失败则按返回原因修正，重新提交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/キー | デフォルト | 説明 |
|
| Neo4j 接続 |
|
| setup 初期化後に書き込み |
|
| OpenAI 互換エンドポイント（review/メンテナンス用、空欄でスキップ可） |
|
| モデル名 |
|
| 同一ノードの同一 Hook チェーン内でのトリガー回数上限（ループ防止） |
|
| タスククレームタイムアウト（タイムアウトで再割り当て/デッドレター） |
|
| 変更ログディレクトリ |
bash git-hooks/install.sh /path/to/your/code-repo以降、そのリポジトリの push / merge で review 検証とグラフマージがトリガーされます。
症状 | 対応 |
Neo4j ダウンロード失敗（403/タイムアウト） | neo4j.com から手動で |
|
|
bolt 接続拒否 |
|
review 手順で LLM 接続失敗 | LLM は空欄で可： |
MCP ツールが表示されない | harness を再起動； |
MIT（必要に応じて変更可）
认领一个 Hook 分发的任务（多 Agent 防撞车的排他锁定）。
何时必须调用:
收到任务通知、评估后确认需要响应时，开发之前先认领
认领成功才开工；返回 rejected 说明他人已认领，直接放弃
何时不需要:
评估后确认无需变更时（不认领，让任务自然超时或被他人处理）
参数:
task_id: 任务 id（来自 get_pending_tasks）
agent_id: 你的 Agent 角色 id（稳定命名，与订阅关系关联）
返回: {status: claimed|rejected, task_id, ...}
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| agent_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does so well: it discloses the exclusive-lock side effect, the claimed/rejected status outcomes, and the rule that work must start only after a successful claim. It does not cover edge cases like invalid task_id or lock expiry, so it is not a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then usage conditions, parameters, and return shape. Each section is short, scannable, and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the full call path: when to call, when not to call, parameter provenance, and return statuses. Given only two string parameters and a simple claimed/rejected result, nothing essential is missing and the output schema further covers the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only gives string types, but the description compensates fully: task_id is sourced from get_pending_tasks and agent_id is the stable agent role id tied to the subscription relationship. Both parameters receive meaning and constraints that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: '认领一个 Hook 分发的任务' with the clarifying parenthetical '多 Agent 防撞车的排他锁定'. This clearly sets it apart from sibling tools like get_pending_tasks (listing) and submit_graph_intent/graph_revision (other mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated '何时必须调用' and '何时不需要' sections give concrete conditions: claim after evaluation and before starting work, and do not claim when no change is needed. It also tells the agent what to do on rejection ('直接放弃'), which is actionable routing behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看待核验的意图请求（review agent 专用）。
何时调用:
你是 Review Agent，git hook 触发你执行核验时
排查「为什么图没更新」时检查是否有滞留的 pending
何时不需要:
普通开发任务（你不应该消费别人的意图请求）
返回: 意图请求列表（完整 JSON）
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. '查看' signals a read-only list operation, and '返回: 意图请求列表（完整 JSON）' states the expected outcome. It also discloses the role restriction. It could be more explicit about side effects, but the wording strongly implies this is a non-mutating lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with distinct '何时调用', '何时不需要', and '返回' sections. All information is meaningful and front-loaded, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the necessary context: what it returns, who may use it, when to use it, and when not to. Nothing critical is missing for an agent to decide whether to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to document. Per the calibration baseline, this scores 4; the description does not need to add parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('查看待核验的意图请求') and immediately scopes it to the review agent. This distinguishes it from sibling tools like get_pending_tasks and clearly identifies what resource the tool operates on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to call it: when acting as the Review Agent during git hook verification, and when debugging why the graph did not update. It also gives a clear negative case: normal development tasks where the agent should not consume others' intent requests. This is excellent routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
拉取任务队列（被动触达的 pull 端）。harness 执行循环中每轮调用。
何时必须调用:
Agent 执行循环的每轮迭代开始时（检查是否有 Hook 分发给你的任务）
何时不需要:
正在处理一个任务的中间（先完成当前任务）
参数:
status: pending（待认领）/ claimed（已认领）/ completed
返回: 任务列表 [{task_id, source_node, message, subscribers, status, ...}] 对订阅了你的任务: 先 query_impact 评估 → 需响应则 claim_task 后开工
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | pending |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the polling cadence, the passive pull nature, the status semantics, the return shape, and the intended workflow after retrieval. '拉取' clearly implies a read operation with no mutation side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, when to call, when not to call, parameters, return shape, and follow-up workflow. Every section earns its place and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description is complete: it explains the trigger condition, the parameter values, and the downstream interaction with sibling tools. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It enumerates the three possible status values ('pending（待认领）/ claimed（已认领）/ completed') and their meanings, which the schema does not provide. This fully documents the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: '拉取任务队列（被动触达的 pull 端）', making the tool's role clear. The reference to the harness execution loop and Hook-distributed tasks distinguishes this passive pull mechanism from sibling tools like claim_task and get_pending_intents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to call ('每轮迭代开始时') and when not to call ('正在处理一个任务的中间'), and provides a clear downstream workflow: query_impact first, then claim_task if a response is needed. This is model guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询当前图版本号（写意图请求时填入 base_revision，用于过期检测）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It clearly indicates a read-only query and states how the value is consumed (base_revision for expiry detection). This is sufficient for a zero-parameter query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence conveys both the operation and the reason it is needed. No filler or redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter query tool with an output schema, the description provides the necessary context: what the tool returns, how to use the result, and why it matters. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema confirms this, so there is no parameter documentation burden. The description mentions base_revision, but that is a field in a downstream request, not a parameter of this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (查询) and resource (当前图版本号), and explains the purpose: filling base_revision in write-intent requests for staleness detection. This clearly distinguishes it from sibling tools like query_impact or query_context, which target different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: call this to obtain base_revision before submitting an intent request. It doesn't explicitly state when not to use it or name alternatives, but the intended workflow is evident from the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
图导航：查询节点的邻域导航信息，用于 Agent 诞生后构建工作上下文。
何时必须调用:
接到任何涉及已有节点（数据结构/模块/需求）的任务时，第一步调用
收到 Hook 任务通知、需要了解变更节点的宏观环境时
何时不需要:
已经持有该节点邻域信息的连续会话中（避免重复调用）
参数:
node_id: 图节点 id
返回: {id, type, layer, name, summary, path, status, skill_hint, neighborhood} 返回的是导航信息而非内容本身——按 path 指针从源头（git/文档/schema）加载细节。 skill_hint 是处理建议，实际路由由 harness 的 skill_routes.yaml 决定。
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It meaningfully discloses that the return is navigation info rather than content itself, that details must be loaded via path pointers, and that skill_hint is only a suggestion overridden by skill_routes.yaml. This goes well beyond a simple query statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized into clear sections: purpose, when to call, when not to call, parameter, and return semantics. Each section earns its place, and the core navigation purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter query tool with an output schema, the description is remarkably complete: it covers invocation triggers, non-triggers, parameter meaning, return shape, and the crucial navigation-vs-content caveat. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It defines node_id as a graph node id, which adds real meaning beyond the bare string type, and also describes the return fields that help an agent understand what the parameter is used for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb '查询' with the resource '节点的邻域导航信息' and clearly ties it to building an Agent's work context. It clearly defines what the tool does, but does not explicitly distinguish it from the sibling query_impact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool must be called (first step for tasks involving existing nodes, and on Hook notifications) and when it is not needed (when neighborhood info is already held in a continuous session). It provides strong when/when-not guidance, though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询一个图节点的变更影响范围（谁会被这个节点的变更波及）。
何时必须调用:
修改任何已有数据结构、模块或需求之前
收到图变更通知、评估自己负责区域是否需要更新时
规划跨模块任务、需要完整依赖上下文时
何时不需要:
纯新增且明确无下游依赖的独立模块
参数:
node_id: 图节点 id（命名规范: data:user_table / module:auth_svc / req:login）
direction: "downstream"=谁被我影响 / "upstream"=我依赖谁
返回: [{id, layer, type, status, summary, path, hops}] 按传播距离排序。 返回的 path 是指针——细节由 skill 按指针从源头加载，不要向本工具索要内容全文。
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | ||
| direction | No | downstream |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it describes the read-only query nature, the exact output shape, sort order by propagation distance, and the important pointer behavior that the result path is a pointer and full content must be loaded from source. This goes well beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for when to use, when not, parameters, and return value. It is dense but every sentence adds value, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema, the description still adds crucial context: the ordering of results, the pointer semantics of the path field, the exact parameter vocabulary, and concrete usage scenarios. Nothing an agent needs to invoke correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the input schema has 0% description coverage, the description fully compensates by explaining node_id naming conventions (data:user_table / module:auth_svc / req:login) and the exact meaning of direction values ('downstream'=谁被我影响 / 'upstream'=我依赖谁). This gives an agent everything needed to fill parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: '查询一个图节点的变更影响范围（谁会被这个节点的变更波及）'. It clearly defines the tool's purpose and distinguishes it from a generic context query like query_context by focusing on change propagation and upstream/downstream impact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'must call' scenarios and a clear 'not needed' case, which strongly guides when to use the tool. However, it does not explicitly name alternative siblings or say 'use X instead', so the comparison against other tools is left partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
提交图变更意图请求（开发完成后的必经步骤）。缓存为 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 不会进图。
| Name | Required | Description | Default |
|---|---|---|---|
| intent_json | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden. It discloses that the request is only cached as pending, that review happens after git commit, and that a failed review means the pending intent does not enter the graph. This is unusually clear about side effects and non-write semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with headers for usage, parameters, return, and caveats. Every section adds operational value, and the key warning about cache-only behavior is front-loaded as well as repeated at the end for emphasis without being wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single complex parameter and no annotations, the description covers when to use it, the JSON structure, required work_notes, return shape, and failure semantics. It does not define valid values for edge 'type' or how to obtain task_id/base_revision, but sibling tools and the output schema already imply that context, so it is only slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by defining intent_json as a JSON string with a complete nested structure: task_id, base_revision, node/edge collections, work_notes, summary, and actor. It also highlights that work_notes is required and explains its purpose, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'submit graph change intent request' and identifies it as the mandatory step after development and before git commit. It enumerates what counts as a graph change and explicitly covers when not needed, which distinguishes it from read/query sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated 'when must call' and 'when not needed' sections give explicit selection criteria: any graph-change task before creating the git commit, versus pure read/query tasks. This lets an agent route to query_impact/query_context instead without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0claim_taskget_pending_intentsget_pending_tasksgraph_revisionquery_contextquery_impactsubmit_graph_intentScored 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.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.