그래프 데이터베이스 기반 코드 아키텍처 관리 시스템 —— Neo4j로 「요구사항 / 코드 모듈 / 데이터」 3계층 의존성 그래프를 유지하고, Agent 개발 시 자동으로 채워지며, 변경 영향은 원클릭 조회, Hook 반응형 연동으로 다중 Agent 협업을 지원합니다.
AI를 위한 한 줄 설정 지시: 「이 README를 읽고, 『빠른 시작』 섹션에 따라 이 프로젝트의 설치와 구성을 완료하세요.」
기존 도구는 「데이터 구조 하나를 바꾸면, 업데이트가 필요한 모든 곳이 어디인지」에 답할 수 없습니다. IDE는 코드 import만 인식하고, 빌드 시스템은 컴파일 의존성만 인식하며, 데이터 혈통(Data Lineage)은 데이터 파이프라인만 인식합니다. 이 프로젝트는 코드, 데이터, 도구, 요구사항을 하나의 그래프에 담습니다:
AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
└──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端영향 분석: 임의 노드 변경 시, 한 줄의 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 | 그래프 schema 적용 (제약 조건 + 인덱스 + 예시 파이프라인 시드 데이터) | Neo4j 내 3계층 그래프 |
7 | MCP server를 | WorkBuddy에서 6개 tool 직접 호출 가능 |
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기능:
그래프 시각화: 계층별 색상 구분(요구사항/모듈/데이터), 노드 클릭 시 상세 정보(요약, 포인터, 상태, 이웃) 확인
활동 패널: 대기 중인 의도 요청, 작업 큐, 최근 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를 지원하는 경우: 동일하게 이 server를 등록하세요 (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