experience_graph_mcp

bastion 의 Experience Graph(EG, 장기 메모리)와 보안 Skill 을 MCP 로 노출하는 얇은 래퍼.

bastion 을 gpt-oss:120b 대신 Claude Code 를 하네스로 테스트할 때, bastion 의 핵심 차별점인 장기 컨텍스트(Experience Graph) 를 그대로 유지하기 위한 브리지다. bastion 의 느린 ReAct 루프(gpt-oss 호출부)만 Claude Code 가 대체하고, EG 와 33개 Skill 은 bastion 소스를 무수정 재사용한다.

Claude Code (하네스/루프)
   │  ├─ UserPromptSubmit 훅 → inject_eg.py → EG 사전참조 자동주입 (bastion 규칙 재현)
   │  └─ MCP 도구 호출
   ▼
experience-graph MCP  ──import(무수정)──▶  bastion.kg_context / kg_recorder / graph / skills
   │                                              │
   ├── eg_search / eg_record_* / eg_stats         └── 공유 Experience Graph DB (bastion_graph.db)
   └── skill_list / skill_preview / skill_run

• bastion 소스는 한 줄도 수정하지 않는다. PYTHONPATH 로 import 하고, bastion/__init__.py 가 강제하는 LLM_* 환경변수는 더미로 채운다(LLM 은 Claude 가 담당 → 실제 호출 없음).
• EG DB 는 BASTION_GRAPH_DB(또는 bastion 자동탐색)로 bastion 과 공유한다.
• MCP SDK 1.x(FastMCP) / 2.x(MCPServer) 모두 호환.

---

빠른 설치 (fresh Linux, 바닥부터)

git clone https://github.com/mrgrit/experience_graph_mcp.git
cd experience_graph_mcp
PROJECT_DIR=/home/ccc/el34/bastion ./install.sh

install.sh 가 자동으로: prereq(python3/venv/git) 확인·설치 → bastion 소스 탐색(없으면 clone) → venv+의존성 → .mcp.json/훅/CLAUDE.md 등록 → doctor 진단까지 수행한다.

python3-venv 가 없는 환경(강의실 최소 설치 등)도 --without-pip + 호스트 pip fallback 으로 자동 처리한다. 자세한 옵션·수동 절차는 docs/USAGE.md.

설치 후:

cd /home/ccc/el34/bastion   # PROJECT_DIR — 여기서 실행해야 .mcp.json 로드됨
claude
/mcp                        # experience-graph 서버 승인

---

도구

도구	종류	설명
eg_search(query, eg_mode, char_budget)	read	EG 조회 → 과거 경험/정책/플레이북/자산/앵커 markdown. 작업 착수 전 호출
eg_record_task(...)	write	완료된 작업 결과를 EG 에 장기 보존
eg_record_finding(...)	write	탐지/취약점 finding 기록
eg_record_observation(...)	write	자산 관찰 기록
eg_stats()	read	EG 노드/엣지 통계 + DB 경로
skill_list()	read	bastion Skill 목록
skill_preview(name, params)	read	실행 없이 명령·대상·위험도(LOW/MED/HIGH) 미리보기
skill_run(name, params)	destructive	Skill 실제 실행(SubAgent A2A/SSH)

read/destructive 는 MCP ToolAnnotations 로 노출되어 Claude Code 승인 UX 가 위험 도구를 구분한다.

LLM 이 필요한 Skill(analyze_logs, ollama_query 등)은 이 래퍼에서 쓰지 않는다 — 분석·추론은 Claude 가 직접 하고, 여기선 인프라 Skill(probe_*/scan_ports/check_*/ configure_nftables/shell 등)만 사용한다.

---

EG ablation (평가)

bastion 과 동일하게 EG_MODE 로 EG 기여도를 A/B 측정한다: off | playbook | experience | full. off 면 자동주입/사전참조가 비활성화되어 No-EG 조건을 재현한다. Claude Code 하네스를 고정한 채 EG 만 켜고 끄므로 평가가 유효하다. → .mcp.json 의 env.EG_MODE 변경 후 재시작.

---

편의 기능

• install.sh — 바닥부터 원커맨드 설치(idempotent).
• python -m eg_mcp.doctor — 셋업 진단(SDK/소스/DB/검색/Skill).
• python -m eg_mcp.register — 다른 프로젝트에도 재등록(기존 설정 보존).
• uninstall.sh — 등록 해제.
• templates/CLAUDE.eg.md — 하네스가 EG/Skill 을 실제로 활용하도록 지시하는 프로젝트 가이드.
• 버전 호환 shim — mcp 1.x/2.x 자동 대응.

---

검증됨

• bastion 소스 무수정 import (33개 Skill 로드)
• EG 기록→검색 왕복: eg_record_finding → eg_search 에서 hits=1 로 복원
• MCP stdio 종단 핸드셰이크: initialize → tools/list → tools/call(eg_stats)
• 공유 DB: bastion_graph.db (anchor 는 history_anchors 테이블)

문서: docs/USAGE.md — 아키텍처·수동 설치·트러블슈팅·평가 절차 상세.