acad-mcp

v0.8.4

Published

6 days ago

ACAD methodology MCP server — diagram validation, doc bridge, test/lint runner

0High
0Medium
0Low

cskeum

mcp acad architecture diagram plantuml mermaid

ACAD-MCP Server

ACAD(Architecture-Centric AI-native Development) 방법론을 MCP 서버로 구현한 프로젝트입니다.

GitHub: https://github.com/cskeum88/acad-mcp

MCP 호환 AI 에이전트(Claude, Codex CLI, Gemini CLI 등)가 이 서버에 연결하면 다음 작업을 도구 호출 한 번으로 처리할 수 있습니다:

다이어그램 검증: Mermaid·PlantUML 코드의 문법 오류를 감지하고 수정 힌트 반환
문서 브리지: ACAD 설계 산출물 5개를 읽어 코딩 에이전트에 자동 전달
코딩 도구: 런타임별 test/lint/typecheck 검사 실행 및 결과 반환
에이전트 인계 파일 생성: Stage 5 이후 CLAUDE.md, AGENTS.md, GEMINI.md 생성

ACAD Stage 1~5 산출물 생성은 ACAD 워크플로우를 수행하는 에이전트/호스트 환경이 담당합니다. acad-mcp는 생성된 산출물을 docs/에서 읽고, 다이어그램 검증·품질 검사·코딩 에이전트 인계 파일 생성을 지원합니다.

또한 이 저장소에는 ACAD 절차 강제를 위한 별도 CLI 하네스인 acad-harness가 포함되어 있습니다. acad-mcp가 capability server라면, acad-harness는 상태 전이·게이트·완료 판정을 담당하는 orchestration layer입니다. resources/SKILL.md는 하네스가 있는 환경에서 Stage 전이와 검증 시점마다 acad-harness를 호출하도록 지시해 절차 게이트를 연결합니다.

빠른 시작

요구사항: Node.js 18 이상.

현재 배포 버전 확인:

npx -y acad-mcp@latest --version

1분 설치 — Claude Code

프로젝트 루트에서:

npx -y acad-mcp@latest init

생성/갱신되는 항목:

.mcp.json — 프로젝트 로컬 MCP 서버 설정
.claude/skills/acad/SKILL.md — ACAD 워크플로우 스킬

같은 프로젝트 루트에서 Claude Code를 재시작한 뒤:

/acad 새 결제 시스템을 ACAD 방식으로 설계해줘

또는 자연어로:

ACAD 방식으로 새 결제 시스템 아키텍처를 설계해줘

전역 Claude Code 스킬로 설치하려면:

npx -y acad-mcp@latest init --global

/acad 버전을 확인해가 예전 버전을 보고하고 스킬 경로가 ~/.claude/skills/acad/로 표시되면 전역 스킬을 읽는 상태입니다. 이 경우 init --global을 실행한 뒤 Claude Code를 재시작하세요.

1분 설치 — Codex CLI

npx -y acad-mcp@latest init --client codex

생성/갱신되는 항목:

~/.codex/skills/acad/SKILL.md — Codex용 ACAD 스킬
~/.codex/config.toml — [mcp_servers.acad-mcp] 항목 자동 추가 (이미 있으면 스킵)

Codex CLI를 재시작한 뒤:

$acad 새 결제 시스템을 ACAD 방식으로 설계해줘

패키지를 업데이트한 뒤에도 설치된 스킬 파일은 자동으로 바뀌지 않습니다. 새 버전의 $acad 스킬을 쓰려면 init --client codex를 다시 실행하고 Codex CLI를 재시작하세요. MCP 등록은 이미 되어 있으므로 재등록 불필요합니다.

기존 ACAD 설계 문서가 있는 프로젝트에서 변경 설계를 하려면:

$acad 기존 설계에 구독 결제 기능을 추가하고 싶어. Evolution Protocol로 영향 범위부터 판단해줘.

하네스 CLI를 직접 실행하려면:

npx -y --package acad-mcp@latest acad-harness status --project-dir .

acad-harness는 같은 npm 패키지의 bin으로 함께 배포됩니다. MCP가 연결된 에이전트는 스킬 지침에 따라 필요한 시점에 acad-harness를 호출합니다.

에이전트별 연결 방법

자세한 설정 가이드: docs/agent-setup-guide.md Windows 환경 가이드: docs/windows-wsl2-setup.md Unity/Unreal + acad-mcp 통합 가이드: docs/unity-unreal-integration.md Figma MCP + acad-mcp 통합 가이드: docs/figma-integration.md AI 피처 포함 시스템 설계 가이드: docs/ai-feature-design.md

Claude Code

가장 쉬운 방법:

npx -y acad-mcp@latest init

기본 init은 프로젝트 로컬 .claude/skills/acad/SKILL.md를 갱신합니다. Claude Code를 같은 프로젝트 루트에서 실행하세요. 모든 프로젝트에서 쓰는 전역 /acad 스킬을 갱신하려면 npx -y acad-mcp@latest init --global을 사용합니다.

수동으로 MCP만 등록하려면:

claude mcp add acad-mcp -- npx -y acad-mcp@latest

또는 프로젝트 루트에 .mcp.json 생성:

{
  "mcpServers": {
    "acad-mcp": {
      "command": "npx",
      "args": ["-y", "acad-mcp@latest"]
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "acad-mcp": {
      "command": "npx",
      "args": ["-y", "acad-mcp@latest"]
    }
  }
}

Codex CLI

가장 쉬운 방법:

npx -y acad-mcp@latest init --client codex

init --client codex는 다음을 한 번에 처리합니다:

~/.codex/skills/acad/SKILL.md 설치
~/.codex/config.toml에 [mcp_servers.acad-mcp] 자동 등록 (이미 있으면 스킵)

업데이트 시에는 스킬 갱신 후 Codex CLI만 재시작하면 됩니다. MCP 재등록 불필요합니다.

수동 설정이 필요하면 ~/.codex/config.toml에 추가:

[mcp_servers.acad-mcp]
command = "npx"
args = ["-y", "acad-mcp@latest"]

Gemini CLI

~/.gemini/settings.json에 추가:

{
  "mcpServers": {
    "acad-mcp": {
      "command": "npx",
      "args": ["-y", "acad-mcp@latest"]
    }
  }
}

VS Code (GitHub Copilot Agent Mode)

프로젝트 루트에 .vscode/mcp.json 생성:

{
  "servers": {
    "acad-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "acad-mcp@latest"]
    }
  }
}

ACAD 설계 시작 방법

쉬운 호출 예시

| 환경 | 설치 후 호출 | |------|-------------| | Claude Code | /acad 새 시스템을 ACAD 방식으로 설계해줘 | | Codex CLI | $acad 새 시스템을 ACAD 방식으로 설계해줘 | | MCP만 연결된 에이전트 | start_acad_workflow tool로 새 시스템 설계 시작해줘 |

기존 설계를 변경할 때는 “추가/변경/수정/리팩토링” 의도를 명시하세요. ACAD 스킬은 기존 docs/ 산출물이 있으면 Evolution Protocol로 영향 Stage를 먼저 판단합니다.

$acad 기존 시스템에 관리자 감사 로그 기능을 추가하고 싶어. 영향 범위부터 판단해줘.

처음 시작하는 프로젝트 (CLAUDE.md 없음)

에이전트에게 tool을 직접 지명합니다:

start_acad_workflow tool로 [앱/시스템 이름] 설계 시작해줘

start_acad_workflow 응답은 맨 앞에 실행 계약을 포함합니다. 에이전트는 이 계약에 따라 바로 파일을 만들지 않고, 설명이 부족하면 먼저 맥락 질문을 한 뒤 사용자 입력을 기다려야 합니다.

Stage 1~5가 완료되면 create_agent_instructions tool이 프로젝트 루트에 CLAUDE.md, AGENTS.md, GEMINI.md를 생성합니다.

기존 프로젝트 (CLAUDE.md 있음)

create_agent_instructions가 생성한 CLAUDE.md에는 자동 트리거 규칙이 포함되어 있습니다. 이후부터는 자연어로 바로 시작할 수 있습니다:

ACAD 스타일로 [기능명] 추가 설계해줘

기존 설계를 변경하면 SKILL의 Evolution Protocol이 영향 Stage를 계산하고 해당 Stage부터 Stage 5까지 cascade 재검토합니다. 하네스 연동 환경에서는 evolve start로 세션을 시작하고, handoff_ready 도달 후 evolve complete로 종료한 뒤 구현 단계로 넘어갑니다.

기존 산출물만 있는 프로젝트를 하네스에 최초 편입할 때는 acad-harness resume --import-existing을 사용합니다. 일반 resume은 저장된 승인 경계를 건너뛰지 않습니다.

제공 도구 (MCP Tools)

| Tool | 설명 | |------|------| | start_acad_workflow | ACAD 설계 시작 — 실행 계약 + Stage 1 반환. 설계 시작 시 반드시 먼저 호출 | | advance_stage | Stage 전환 게이트 — 이전 산출물 파일 확인 후 다음 Stage 내용 반환 | | validate_diagram | Mermaid·PlantUML 문법 검증 | | read_acad_docs | ACAD 산출물 파일 읽기 (docs/ 기본) | | create_agent_instructions | Stage 5 이후 CLAUDE.md, AGENTS.md, GEMINI.md 생성 | | run_checks | 런타임별 품질 검사 실행 (test 기본, lint/typecheck는 지원 시 실행) | | get_acad_status | 실행 중인 서버 버전과 번들 ACAD 스킬 버전 조회 |

입력 파라미터와 응답 형식은 docs/tool-reference.md를 참조하세요.

현재 로드된 스킬과 연결된 MCP 서버의 버전을 함께 확인하려면 코딩 에이전트에서 다음처럼 질문하세요.

/acad 현재 로드된 스킬 버전과 연결된 MCP 서버 버전을 알려줘.
$acad 현재 로드된 스킬 버전과 연결된 MCP 서버 버전을 알려줘.

에이전트는 현재 로드된 SKILL.md 헤더 버전을 확인하고 get_acad_status를 호출합니다. 버전이 다르면 최신 스킬을 설치한 뒤 에이전트를 재시작하세요.

# Claude Code 프로젝트 로컬
npx -y acad-mcp@latest init

# Claude Code 전역 스킬
npx -y acad-mcp@latest init --global

# Codex CLI
npx -y acad-mcp@latest init --client codex

Harness 설계와 수동 검증 절차는 아래 문서를 참조하세요.

제공 프롬프트 (MCP Prompts)

| Prompt | 설명 | |--------|------| | acad-workflow | preamble + Stage 1 시작 지침 (이후 advance_stage tool로 진행) |

프로젝트 구조

acad-mcp/
├── CLAUDE.md                    # Claude Code 시작 지침
├── AGENTS.md                    # Codex CLI 시작 지침
├── GEMINI.md                    # Gemini CLI 시작 지침
├── README.md
├── package.json
├── tsconfig.json
├── esbuild.config.js
├── vitest.config.ts
├── .gitattributes
│
├── docs/                        # ACAD 설계 문서
│   ├── arch-story.md
│   ├── architecture-drivers.md
│   ├── architecture.md
│   ├── validation-report.md
│   ├── implementation-plan.md
│   ├── tool-reference.md        # MCP tool 입력/응답 명세
│   ├── harness-engineering.md   # 하네스 설계 제안
│   ├── harness-manual-test.md   # 하네스 수동 검증 절차
│   ├── windows-wsl2-setup.md    # Windows + WSL2 설치 가이드
│   └── unity-unreal-integration.md  # Unity/Unreal + acad-mcp 통합 가이드
│
├── .claude/                     # Claude Code 설정
│   └── skills/
│       └── acad/
│           └── SKILL.md         # ACAD 워크플로우 스킬
│
├── src/                         # 소스 코드
│   ├── transport/               # MCP 전송 레이어
│   ├── server/                  # MCP 서버 조율자
│   ├── tools/                   # MCP Tool 구현
│   ├── ports/                   # Port 인터페이스
│   ├── adapters/                # 외부 연동 구현체
│   ├── prompts/                 # ACAD 워크플로우 프롬프트
│   ├── harness/                 # 하네스 상태 머신, 게이트, CLI 로직
│   ├── infra/                   # Logger, GlobalErrorHandler
│   ├── index.ts                 # acad-mcp 엔트리포인트
│   └── harness-cli.ts           # acad-harness 엔트리포인트
│
├── resources/
│   └── SKILL.md                 # 번들 내장용 ACAD 스킬 (저작권 헤더 포함)
│
└── dist/                        # esbuild 번들 출력 (.gitignore)
    ├── acad-mcp.js              # MCP 서버 번들
    └── acad-harness.js          # 하네스 CLI 번들

아키텍처

Hexagonal (Ports & Adapters) 패턴 기반. 설계 문서는 docs/ 폴더 참조.

구현 상태 및 로드맵

현재 (Phase 2 완료 · v0.8.2)

| Phase | 내용 | 상태 | |-------|------|------| | Phase 1 | MCP 서버 · 다이어그램 검증 · 문서 브리지 · 품질 검사 · 에이전트 인계 | ✅ 완료 | | Phase 2 | acad-harness · Stage 게이트 · Evolution Protocol · Codex CLI 통합 | ✅ 완료 |

다음 (Phase 3 계획)

Phase 3는 세 트랙으로 병행 진행된다.

| 트랙 | 목표 | 전제 조건 | |------|------|----------| | 3-A Claude Code 플러그인 | claude plugin install acad-mcp 한 줄 설치 지원 | GitHub 리포 공개 전환 | | 3-B Gemini CLI 통합 | npx acad-mcp init --client gemini · GEMINI.md 지원 | — | | 3-C 로컬 LLM → acad-agent | 로컬 LLM 연동 후 AI Client 없이 독립 실행 가능한 에이전트로 진화 | 로컬 LLM 품질 검증 | | 3-D Unity/Unreal MCP 통합 | acad-mcp(백엔드 설계) + unity/unreal-mcp(3D 클라이언트)를 하나의 세션에서 연결 | — | | 3-E Figma MCP 통합 | Figma 디자인 파일 → ACAD 맥락 수집·ASR 수치·구현 계획 자동 투입 | Figma Personal Access Token | | 3-F AI 피처 설계 지원 | 비결정성·지연·비용·환각 등 AI 고유 드라이버를 SKILL.md Stage별로 강제 | ai-feature-design.md 현장 검증 | | 3-G bkit PDCA 통합 | ACAD 설계 산출물을 bkit 스프린트 파이프라인에 주입 — cto-lead 스펙 강화·gap-detector ADR 기준·pdca-iterator 가드레일 | Phase 0 수동 검증 완료 |

플러그인(plugin.json)은 "어떻게 설치하고 어디서 실행할지"를 정의하는 메타데이터일 뿐이다. 실제 MCP 서버 실행은 여전히 npm의 acad-mcp 패키지가 담당하므로, npm 등록은 Phase 3 이후에도 유지된다.

자세한 계획: docs/implementation-plan.md · docs/acad-plugin-distribution.md

라이선스

MIT

ACAD 방법론(resources/SKILL.md)의 저작권은 별도로 보호됩니다. 개인 학습 및 비상업적 목적에 한해 자유롭게 사용 가능합니다.