グラフデータベース駆動のコードアーキテクチャ管理システム —— 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（必要に応じて変更可）
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/3486038424/neo4j_mcp_controller'
If you have feedback or need assistance with the MCP directory API, please join our Discord server