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/에서 읽고, 다이어그램 검증·품질 검사·코딩 에이전트 인계 파일 생성을 지원합니다.

빠른 시작

npx acad-mcp

Node.js 외 별도 설치 불필요.

에이전트별 연결 방법

자세한 설정 가이드: docs/agent-setup-guide.md

Claude Code

claude mcp add acad-mcp -- npx -y acad-mcp

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

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

Claude Desktop

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

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

Codex CLI

권장: CLI로 등록

codex mcp add acad-mcp -- npx -y acad-mcp

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

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

Gemini CLI

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

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

VS Code (GitHub Copilot Agent Mode)

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

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

제공 도구 (MCP Tools)

| Tool | 설명 | |------|------| | 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는 지원 시 실행) |

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

제공 프롬프트 (MCP Prompts)

| Prompt | 설명 | |--------|------| | acad-workflow | ACAD Stage 1~5 워크플로우 지침 |

프로젝트 구조

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
│
├── .claude/                     # Claude Code 설정
│   └── skills/
│       └── acad/
│           └── SKILL.md         # ACAD 워크플로우 스킬
│
├── src/                         # 소스 코드
│   ├── transport/               # MCP 전송 레이어
│   ├── server/                  # MCP 서버 조율자
│   ├── tools/                   # MCP Tool 구현
│   ├── ports/                   # Port 인터페이스
│   ├── adapters/                # 외부 연동 구현체
│   ├── prompts/                 # ACAD 워크플로우 프롬프트
│   ├── infra/                   # Logger, GlobalErrorHandler
│   └── index.ts
│
├── resources/
│   └── SKILL.md                 # 번들 내장용 ACAD 스킬 (저작권 헤더 포함)
│
├── tests/
│   ├── unit/
│   └── integration/
│
└── dist/                        # esbuild 번들 출력 (.gitignore)

아키텍처

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

라이선스

MIT

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