# blueprint-mcp

> 개발 지식이 없어도, LLM으로 만든 프로그램의 **구조를 검토**하고 **연결관계를 한 장의 그림(Mermaid)** 으로 볼 수 있게 해 주는 **호스트 중립 MCP 서버**.

`blueprint-mcp` 는 Claude · OpenAI Codex · Google Antigravity 등 MCP를 지원하는 어떤 호스트에서든 동작한다. 대상 코드를 **읽기 전용**으로 분석해서

1. **구조·코드 적정성 검토** — 순환 의존성, 기능이 몰린 허브(god module), 고립 파일, 폴더 경계 침범 같은 "아키텍처 냄새"를 신호등(🔴🟡🟢)으로 알려 주고,
2. **의존성 모식도** — 파일/폴더가 서로 어떻게 물려 있는지 한 장의 **Mermaid flowchart** 로 그려 준다.

핵심 설계 원칙은 **"결정론 먼저, LLM은 설명만"** 이다. 그래프·지표·냄새는 표준 라이브러리 기반 정적 분석이 계산하고, LLM(호스트)은 그 결과를 비개발자용으로 풀어 설명·등급화만 한다. LLM에 직접 판정을 맡길 때 생기는 환각·과잉교정을 구조적으로 차단한다.

---

## 왜 이렇게 만들었나

| 결정 | 이유 |
|---|---|
| **결정론 2계층** (정적분석 → LLM 설명) | LLM 단독 코드 판정은 과잉교정·환각·자기편향(모델이 같은 계열 산출물을 후하게 평가)이 보고돼 있음. 점수는 코드가 계산하고 LLM은 해설만. |
| **다이어그램은 flowchart** (mindmap ❌) | 의존성 그래프는 교차엣지·순환이 있는 방향그래프. Mermaid mindmap은 트리 전용이라 표현 불가. |
| **파서 출력 → 코드로 Mermaid 조립** | LLM 자유 생성은 구문 오류가 잦음. 그래프에서 코드로 조립하고 크기 한계(50k자/500엣지/200노드)를 강제. |
| **stdio 1순위** | 세 호스트 모두 로컬 stdio 지원. 네트워크·인증 없이 가장 단순. |
| **표준 라이브러리 기반** | Python은 `ast`, JS/TS는 경량 정규식으로 **무설치 즉시 동작**. tree-sitter/dependency-cruiser는 정밀도 승격(로드맵 M3)용 선택 사항. |
| **realpath + 읽기 전용** | 로컬 파일 접근 MCP는 실제 CVE 이력(EscapeRoute)이 있는 고위험 영역. 심볼릭 링크를 완전 해석하고 허용 루트만 검사. |

설계 근거의 상세 조사 내용은 [`PLAN/`](PLAN/) 폴더와 리서치 리포트를 참고.

---

## 동작 방식

```mermaid
flowchart TD
    U["사용자 (비개발자)"] -->|자연어 요청| H["MCP 호스트<br/>Claude · Codex · Antigravity"]
    H -->|tools/call| S["blueprint-mcp 서버 (stdio)"]
    S --> SEC{"경로 검증<br/>realpath + 허용 루트"}
    SEC -->|통과| WALK["파일 탐색 · 언어 감지"]
    WALK --> PY["Python: 표준 ast 로 import 추출 (정밀)"]
    WALK --> JS["JS/TS: 정규식 import 추출 (구문 추정)"]
    PY --> G["의존성 그래프"]
    JS --> G
    G --> REV["검토: 순환 · 허브 · 고립 · 경계"]
    G --> DIA["폴더 집약 → Mermaid flowchart 조립"]
    REV --> OUT["structuredContent (JSON)"]
    DIA --> OUT
    OUT -->|결과 반환| H
    H -->|쉬운 말로 설명·등급화| U
```

---

## 제공 도구 (MCP tools)

| 도구 | 하는 일 | 주요 인자 |
|---|---|---|
| `analyze_structure` | 파일/언어/폴더 분포와 그래프 규모 요약 | `path` |
| `review_code_quality` | 구조 냄새를 신호등으로 검토 | `path`, `hub_threshold` |
| `generate_dependency_diagram` | 연결관계를 한 장의 Mermaid flowchart로 | `path`, `granularity`, `focus`, `direction` |
| `extract_dependency_graph` | 노드·엣지 JSON 그래프 추출(재사용용) | `path`, `granularity` |

모든 도구는 대상 경로를 **읽기 전용**으로만 접근한다.

---

## 사용 방법 (3가지)

### 1) 자연어로 요청 — 설치하면 바로 가능

명령어를 외울 필요 없다. 대화창에서 평범하게 부탁하면 모델이 알맞은 도구를 호출한다.

- "blueprint로 `C:/myapp` 구조 검토해줘" → `review_code_quality`
- "이 프로젝트 의존성 모식도 한 장으로 그려줘" → `generate_dependency_diagram`
- "`src/api` 폴더만 확대해서 보여줘" → `focus`

### 2) BP 작업 템플릿 — 한 단어 명령

네 가지 작업을 짧은 명령 하나로 실행한다. 경로를 생략하면 현재 폴더가 대상이다.

| 작업 | Claude Code | OpenAI Codex | 도구 |
|---|---|---|---|
| **BP_A** 구조 적정성 검토(신호등) | `/bp_a` | `$bp-a` | `review_code_quality` |
| **BP_B** 의존성 모식도(Mermaid) | `/bp_b` | `$bp-b` | `generate_dependency_diagram` |
| **BP_C** 종합 요약서(개요+신호등+모식도) | `/bp_c` | `$bp-c` | `analyze_structure` + `review_code_quality` + `generate_dependency_diagram` |
| **BP_D** 의도·기능 점검(README/기획 대비 — 무엇이 빠졌고 무엇이 연결돼야 하나) | `/bp_d` | `$bp-d` | `analyze_structure` + 소스·문서 대조 |

```
/bp_c C:/myapp     # Claude Code — 슬래시
$bp-c C:/myapp     # Codex — 달러 기호(스킬 호출)
```

> **BP_A~C 는 "구조가 깔끔한가", BP_D 는 "만들려던 의도대로 기능이 채워지고 연결됐는가"** 를 본다.
> 비개발자에게 보통 가장 중요한 질문은 후자다. 결과 문서는 모두 프로젝트의 `blueprint/` 폴더에 저장된다.

명령 파일은 자동 설치기가 복사한다(수동 설치는 각 폴더의 README 참고).

- **Claude Code**: [`install/claude-commands`](install/claude-commands/) → `~/.claude/commands/`.
  서버가 제공하는 MCP Prompts 를 직접 쓰면 `/mcp__blueprint__bp_a` 처럼 접두어가 붙어 길어진다.
- **OpenAI Codex**: [`install/codex-skills`](install/codex-skills/) → `~/.agents/skills/`.
  Codex 는 커스텀 슬래시 명령(`~/.codex/prompts`)을 폐지했고 MCP Prompts 도 읽지 않으므로,
  같은 역할을 **스킬**로 제공한다. 호출 기호가 `/` 가 아니라 `$` 인 점만 다르다.
- **Antigravity**: MCP Prompt 노출 여부는 버전에 따라 다르며, 보이지 않으면 자연어로 요청한다.

### 3) 자동 검토 (선택)

편집·커밋·push 시점에 자동으로 순환 의존성을 검사하게 할 수 있다 →
[`install/automation`](install/automation/) (Claude Code 훅 · git pre-commit · Gitea CI).
"코드 바꾸면 먼저 검토하고 모식도를 보여줘"라는 습관을 붙이려면
[`install/agent-instructions`](install/agent-instructions/) 의 `AGENTS.md`/`CLAUDE.md`
템플릿을 대상 프로젝트에 두면 된다.

> CI/pre-commit 용 검사: `blueprint-mcp-cli check <경로>` — 순환이 있으면 종료코드 1.

---

## 설치

### 비개발자라면 — 더블클릭 한 번 (권장)

내려받은 폴더에서 **`설치_Windows.bat`(또는 `install.bat`) 를 더블클릭**(mac/Linux 은 `sh 설치_macOS_Linux.sh`).
설치기가 프로그램을 깔고, 설치된 Claude·Codex·Antigravity 를 찾아 **설정을 자동으로
넣어 줍니다**(기존 설정은 `.bak` 백업). → 자세한 그림 설명: [초간단 설치 가이드](install/비개발자_설치가이드.md)

```bat
설치_Windows.bat                       :: 자동 감지 설치
설치_Windows.bat --allow C:/내프로젝트   :: 분석 허용 폴더 지정(권장)
```

설치 후 앱을 껐다 켜면 끝. 되돌리기: `python installer/uninstall.py`.

### 개발자라면 — 수동 설치

```bash
git clone https://gitea.hmac.kr/saman/blueprint-mcp.git
cd blueprint-mcp
pip install -e .          # mcp SDK 포함 설치
```

> 무설치로 서버만 띄우려면 `pip install mcp` 후 [`run_server.py`](run_server.py) 를 직접 실행해도 된다.

### 호스트별 등록

세 호스트 모두 로컬 stdio 서버 등록을 지원하며, 설정 포맷만 다르다. 예시는 [`install/`](install/) 참고.

**Claude (Claude Code / Desktop)** — `.mcp.json` 또는 `~/.claude.json`:

```json
{
  "mcpServers": {
    "blueprint": { "type": "stdio", "command": "python", "args": ["-m", "blueprint_mcp"] }
  }
}
```

**OpenAI Codex** — `~/.codex/config.toml` (테이블 키가 **snake_case** 임에 주의):

```toml
[mcp_servers.blueprint]
command = "python"
args = ["-m", "blueprint_mcp"]
```

**Google Antigravity** — `~/.gemini/config/mcp_config.json` (또는 IDE 내장 MCP Store에서 GUI 설치):

```json
{
  "mcpServers": {
    "blueprint": { "command": "python", "args": ["-m", "blueprint_mcp"] }
  }
}
```

> 안전을 위해 환경변수 `BLUEPRINT_MCP_ALLOWED_ROOTS`(경로 구분자로 구분)를 지정하면 그 폴더 밖은 분석하지 않는다.

---

## 호스트 없이 바로 써 보기 (CLI)

```bash
# 폴더 단위 의존성 모식도(Mermaid)
python -m blueprint_mcp.cli diagram <프로젝트경로> --granularity folder --direction LR

# 구조 냄새 검토(JSON)
python -m blueprint_mcp.cli review <프로젝트경로>

# 구조 요약 / 그래프 추출
python -m blueprint_mcp.cli structure <프로젝트경로>
python -m blueprint_mcp.cli graph <프로젝트경로> --granularity file
```

### 예시 ― blueprint-mcp 가 자기 자신을 분석한 결과

`generate_dependency_diagram` 이 만든 폴더 단위 조감도(실제 출력):

```mermaid
flowchart LR
    tools["tools"]
    graph["graph"]
    analyze["analyze"]
    parse["parse"]
    security["security"]
    root["(진입점)"]
    root --> tools
    root --> security
    tools --> analyze
    tools --> graph
    tools --> parse
    tools --> security
    analyze --> graph
    graph --> parse
```

진입점(server/cli)이 `tools`를 부르고, `tools`가 검토·그래프·파싱·보안 계층을 조율하며, `analyze → graph → parse` 로 단방향으로 흐른다. 순환이 없다 → 🟢.

### 예시 ― 순환 의존성이 있는 프로젝트 (🔴)

순환에 걸린 노드는 빨간색으로 강조된다:

```mermaid
flowchart TD
    a["pkg/a.py"] --> b["pkg/b.py"]
    b --> a
    a --> hub["pkg/hub.py"]
    b --> hub
    c["pkg/c.py"] --> hub
    main["main.py"] --> a
    main --> hub
    classDef cycle fill:#f8d7da,stroke:#dc3545,color:#842029;
    class a,b cycle;
```

`a ↔ b` 가 서로를 물고 있어 한쪽만 고치기 어렵고, `hub.py` 는 여러 파일이 참조하는 허브다.

---

## 패키지 구조

```mermaid
flowchart LR
    subgraph entry["진입점"]
      SRV["server.py<br/>(FastMCP · stdio)"]
      CLI["cli.py"]
    end
    subgraph corelayer["분석 코어"]
      TOOLS["tools/api"]
      SEC["security/paths<br/>realpath 검증"]
      PARSE["parse<br/>base · python_ast · js_ts"]
      GRAPH["graph<br/>model · build · collapse · mermaid"]
      ANALYZE["analyze<br/>smells · report"]
    end
    SRV --> TOOLS
    CLI --> TOOLS
    TOOLS --> SEC
    TOOLS --> PARSE
    TOOLS --> GRAPH
    TOOLS --> ANALYZE
    ANALYZE --> GRAPH
    GRAPH --> PARSE
```

```
blueprint-mcp/
├─ src/blueprint_mcp/
│  ├─ server.py            # MCP 서버(FastMCP, stdio) — 4개 tool 노출
│  ├─ cli.py               # 호스트 없이 쓰는 CLI
│  ├─ security/paths.py    # realpath + 허용 루트 검증 (읽기 전용)
│  ├─ parse/               # 파일 탐색 + import 추출 (ast / 정규식)
│  ├─ graph/               # 그래프 모델 · 폴더 집약 · Mermaid 조립
│  ├─ analyze/             # 냄새 탐지 · 신호등 리포트
│  └─ tools/api.py         # 고수준 오케스트레이션
├─ PLAN/                   # 단계별 개발 계획(M1~M5)
├─ install/                # 호스트별 등록 스니펫
├─ tests/                  # 표준 unittest (mcp 미설치에서도 실행)
└─ run_server.py           # 무설치 실행 부트스트랩
```

---

## 지원 언어

| 언어군 | 추출 방식 | 신뢰도 |
|---|---|---|
| **Python** | 표준 `ast` 로 절대/상대 import 정밀 해석 | resolved(정밀) |
| **JavaScript / TypeScript** | 경량 정규식으로 상대 import 해석 | heuristic(구문 추정) |
| (확장) 다중 언어 | tree-sitter / dependency-cruiser 로 승격 | 로드맵 M3 |

---

## 테스트

```bash
python -m unittest discover -s tests
```

의도적으로 순환·허브·고립을 심은 샘플 프로젝트([`tests/fixtures/sample_project`](tests/fixtures/sample_project))로 파싱·냄새 탐지·Mermaid 생성·보안 검증을 회귀 검사한다. mcp SDK 없이도 실행된다.

---

## 로드맵

- **M1 (현재)** — stdio 서버, 경로 보안, Python/JS·TS 파싱, 폴더 조감도, 4개 tool.
- **M2** — 규칙 기반 검토 강화, LLM 2계층 설명 프롬프트.
- **M3** — tree-sitter/SCIP 정밀층 승격, 대규모 그래프 드릴다운.
- **M4** — 호스트별 배포 UX, 스모크 테스트.
- **M5** — Streamable HTTP 전송, 다국어 확대, 슬래시 커맨드 프롬프트.

자세한 내용은 [`PLAN/`](PLAN/) 참고.

---

## 라이선스

[MIT](LICENSE)