# 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, 바닥부터)

```bash
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`](docs/USAGE.md).

설치 후:

```bash
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`](docs/USAGE.md) — 아키텍처·수동 설치·트러블슈팅·평가 절차 상세.