blueprint-mcp

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

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

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

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

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

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

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

# 폴더 단위 의존성 모식도(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

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

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;

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 -m unittest discover -s tests