Mandu Mcp Index

---
name: mandu-mcp-index
description: |
  MCP 도구 오케스트레이션 라우터 (always-on). 108개 MCP 도구 중
  상황에 맞는 워크플로우 skill 선택, 집계>세분 우선순위, anti-pattern 카탈로그.
  MCP 도구 호출 직전 자동 참조.
---

# Mandu MCP Index

`@mandujs/mcp` 는 약 108 개의 MCP 도구를 노출합니다. 이 문서는
**flat palette 가 아니라 tiered hierarchy** 로 도구를 선택하도록 안내합니다.

핵심 원칙:

1. **Workflow skill 먼저**. 개별 도구가 아닌 `mandu-mcp-*` workflow skill 을 먼저 본다.
2. **집계 > 세분**. 같은 일을 하는 집계 도구가 있으면 그걸 먼저. 실패했을 때만 세분 도구로 drill-down.
3. **안전망 먼저**. `refactor_*` / 마이그레이션은 `mandu.history.snapshot` + `mandu.tx.begin` 안에서만.
4. **순서는 강제**. `mandu_create_contract` → `mandu_generate`, `mandu.history.snapshot` → `refactor_*`.

## 1. Situation -> Workflow Skill

| 상황 | 먼저 열 workflow skill | 보조 task-shaped skill |
|------|----------------------|----------------------|
| 세션 시작 / "현 상태?" / "무슨 일 있었어?" | `mandu-mcp-orient` | — |
| "만들어줘" / 피처·리소스·라우트 추가 | `mandu-mcp-create-flow` | `mandu-create-feature`, `mandu-create-api` |
| 편집 직후 / stop-hook / "check 해줘" | `mandu-mcp-verify` | `mandu-debug` |
| 마이그레이션 / 리팩터 / `refactor_*` | `mandu-mcp-safe-change` | — |
| 배포 / release / "deploy" | `mandu-mcp-deploy` | `mandu-deploy` |
| 에러 / 증상 기반 진단 | `mandu-mcp-verify` -> drill-down | `mandu-debug` |
| Guard 위반 | `mandu-mcp-verify` -> `mandu_guard_explain` | `mandu-guard-guide` |
| Island / Hydration | `mandu-mcp-verify` | `mandu-hydration`, `mandu-slot` |

## 2. Aggregate > Granular — 우선순위 표

한 번에 처리하는 집계 도구가 있으면 그걸 먼저. 실패/불충분할 때만 세분.

| 목적 | 집계 (먼저 호출) | 세분 (drill-down 용도만) |
|------|----------------|----------------------|
| 테스트 파이프라인 | `mandu.ate.auto_pipeline` | `mandu.ate.extract`, `mandu.ate.generate`, `mandu.ate.run`, `mandu.ate.heal`, `mandu.ate.apply_heal` |
| 세션 오리엔테이션 | `mandu.ai.brief` | `mandu_get_architecture`, `mandu_get_decisions`, `mandu_list_routes` |
| 배포 준비 | `mandu.deploy.check` | `mandu_guard_check`, `mandu_validate_contracts`, `mandu_validate_manifest` |
| 배포 미리보기 | `mandu.deploy.preview` | `mandu_preview_seo`, `mandu_write_seo_file` |
| 구조/진단 | `mandu_doctor` | `mandu_check_import`, `mandu_check_location` |
| 스캐폴드 | `mandu_generate_scaffold` (negotiate → scaffold 묶음) | `mandu_add_route`, `mandu_create_contract`, `mandu_generate` |
| 피처 생성 | `mandu.feature.create` | `mandu_add_route` × n + contract + generate |
| 리소스 생성 | `mandu.resource.create` | `mandu.resource.addField`, `mandu_create_contract`, `mandu_generate` |

규칙:

- **집계 도구 실패 시에만** 개별 도구로 분해한다. "4번 부르면 뭐 하는지 알 수 있을 것 같아서" 라는 이유로 `extract → generate → run → heal` 을 수동으로 호출하지 않는다.
- 집계 도구는 내부에서 올바른 **순서 / 병렬화 / 실패 복구** 를 이미 구현하고 있다. 손으로 재조립하면 그 보장을 잃는다.

## 3. Tiered Tool Hierarchy (108 tools)

> 전체 나열이 아니라 *계층* 이다. 각 티어 안에서 "먼저 볼 곳" 이 정해져 있다.

### Tier 0 — Aggregate Orchestrators (먼저 본다)

- `mandu.ai.brief` — 세션 진입용 종합 브리핑
- `mandu.ate.auto_pipeline` — ATE 전체 파이프라인 (extract/generate/run/heal)
- `mandu.deploy.check` — guard + contract + manifest 병렬 검사
- `mandu.deploy.preview` — 프로덕션 빌드 사전 리허설
- `mandu_doctor` (alias of `mandu.brain.doctor`) — 구조/임포트/위치 진단
- `mandu.feature.create`, `mandu.resource.create` — 복합 스캐폴드
- `mandu_generate_scaffold` (alias of `mandu.negotiate.scaffold`) — negotiate→scaffold 묶음

### Tier 1 — Domain Entry Points

| Domain | Entry tool | 역할 |
|--------|-----------|------|
| Architecture | `mandu_get_architecture` (alias `mandu.brain.architecture`) | 프리셋/레이어 규칙 |
| Decisions | `mandu_get_decisions` | ADR / 결정 이력 |
| Contract | `mandu_list_contracts`, `mandu_create_contract` | Zod 계약 |
| Routes | `mandu_list_routes`, `mandu_add_route` | FS 라우트 |
| Island | `mandu_list_islands`, `mandu_set_hydration` | 하이드레이션 |
| Slot | `mandu_read_slot`, `mandu_validate_slot` | 서버 로더 |
| SEO | `mandu_preview_seo`, `mandu_write_seo_file` | 메타/sitemap/robots |
| Runtime | `mandu_get_runtime_config` | 실행 구성 |
| Guard | `mandu_guard_check`, `mandu_guard_heal`, `mandu_guard_explain` | 아키텍처 강제 |
| History | `mandu.history.snapshot`, `mandu_list_history`, `mandu_prune_history` | 스냅샷 |
| Transaction | `mandu_begin`, `mandu_commit`, `mandu_rollback`, `mandu_tx_status` | 트랜잭션 |
| Kitchen | `mandu_kitchen_errors` | 런타임 에러 스트림 |

### Tier 2 — Granular Operations (drill-down 시에만)

- ATE 개별: `mandu.ate.extract`, `mandu.ate.generate`, `mandu.ate.run`, `mandu.ate.report`, `mandu.ate.heal`, `mandu.ate.apply_heal`, `mandu.ate.impact`, `mandu.ate.feedback`
- Brain 세분: `mandu_check_import`, `mandu_check_location`, `mandu_watch_start`, `mandu_watch_stop`, `mandu_watch_status`
- Contract 세분: `mandu_get_contract`, `mandu_update_route_contract`, `mandu_validate_contracts`, `mandu_sync_contract_slot`, `mandu_generate_openapi`
- Resource 세분: `mandu.resource.list`, `mandu.resource.get`, `mandu.resource.addField`, `mandu.resource.removeField`
- SEO 세분: `mandu_generate_sitemap_preview`, `mandu_generate_robots_preview`, `mandu_create_jsonld`, `mandu_seo_analyze`

### Tier 3 — Destructive / AI Refactor (항상 Safe-Change wrapper)

> 이 레이어의 도구는 **반드시** `mandu-mcp-safe-change` 레시피 안에서만 호출한다.
> `mandu.history.snapshot` 선행 + `mandu.tx.begin` 래핑 필수.

- `mandu.refactor.rewriteGeneratedBarrel`
- `mandu.refactor.migrateRouteConventions`
- `mandu.refactor.extractContract`

## 4. Anti-Pattern Catalog

다음 패턴이 감지되면 **즉시 멈추고** 대응 워크플로우로 전환한다.

### AP-1 — ATE 수동 조합
- 증상: `mandu.ate.extract` → `mandu.ate.generate` → `mandu.ate.run` → `mandu.ate.heal` 를 개별 호출.
- 왜 안 되나: `mandu.ate.auto_pipeline` 이 이 시퀀스를 내부에서 올바른 순서와 실패 복구로 실행한다. 수동 조합은 왕복 4배 + 오더링 버그 + 실패 지점에서 멈추지 못함.
- 대응: `mandu-mcp-verify` 의 fast path (`mandu.ate.auto_pipeline`) 사용. 실패 응답이 개별 도구를 지시할 때만 분해.

### AP-2 — Generate before Contract
- 증상: `mandu_generate` 를 `mandu_create_contract` 없이 호출.
- 왜 안 되나: 생성물 (`.mandu/generated/**`) 의 타입이 unstable. Re-generate 시 매번 변경되고, API-호출 쪽 타입이 부유.
- 대응: `mandu-mcp-create-flow` 순서 (`negotiate → route/resource → contract → generate`) 고정.

### AP-3 — Refactor without Snapshot
- 증상: `mandu.refactor.*` 또는 마이그레이션을 `mandu.history.snapshot` 없이 호출.
- 왜 안 되나: 롤백 포인트가 없어 실패 시 수동 복구 불가. Git 이 있어도 `.mandu/generated/**` 같은 생성물은 추적 밖.
- 대응: `mandu-mcp-safe-change` 레시피 (`snapshot → tx_begin → edit+verify → commit/rollback`).

### AP-4 — Name-Match Tool Pick
- 증상: "이름이 맞아 보여서" 108개 중 하나를 직접 호출. 예: "build 니까 `mandu_build`" "deploy 니까 `mandu.deploy.*`".
- 왜 안 되나: 같은 도메인에 3-4개 도구가 있고 집계 도구가 우선한다. 잘못 고르면 효과가 없거나 순서가 깨진다.
- 대응: 먼저 이 index 의 **Situation → Workflow Skill** 표에서 workflow skill 을 고르고, workflow skill 이 지시하는 도구만 호출.

### AP-5 — Guard After Commit
- 증상: `mandu_guard_check` 를 `git commit` 후 실행.
- 왜 안 되나: 위반을 커밋 안에 박음. CI 에서 reject 되거나 revert 부담.
- 대응: `mandu-mcp-verify` fast path 를 편집 직후 / pre-commit hook 으로.

### AP-6 — Parallel Mutation Without Transaction
- 증상: `mandu_add_route`, `mandu_create_contract`, `mandu_generate` 를 `mandu.tx.begin` 없이 독립적으로.
- 왜 안 되나: 중간에 실패하면 반쯤 만들어진 상태가 남는다. (예: route 만 있고 contract 없음 → guard violation.)
- 대응: 복합 스캐폴드는 `mandu.resource.create` / `mandu.feature.create` / `mandu_generate_scaffold` 집계로, 또는 `mandu-mcp-safe-change` 로.

### AP-7 — Manual Build Pipeline
- 증상: 배포 전에 `mandu_build`, `mandu_guard_check`, `mandu_validate_contracts`, `mandu_validate_manifest`, `mandu_preview_seo` 를 손으로 나열.
- 왜 안 되나: `mandu.deploy.check` + `mandu.deploy.preview` 가 이 시퀀스를 올바른 순서와 병렬로 이미 처리한다.
- 대응: `mandu-mcp-deploy` 레시피.

## 5. Escalation Flow

```
요청 도착
  → mandu-mcp-index (이 문서) 로 상황 매핑
  → 해당 workflow skill 오픈
    → 집계 도구 먼저 호출
      → 통과: 종료
      → 실패: workflow skill 의 drill-down 섹션으로만 진입
    → 필요시 task-shaped skill (mandu-debug, mandu-guard-guide, ...) 참조
```

이 순서를 뒤집지 않는다. 특히 **108개 도구 목록을 직접 훑지 않는다** — workflow skill 이 고른 도구만 호출한다.

## See Also

- `mandu-mcp-orient` — 세션 시작 시 상태 파악
- `mandu-mcp-create-flow` — 스펙 우선 생성
- `mandu-mcp-verify` — 편집 후 검증
- `mandu-mcp-safe-change` — 위험 변경 트랜잭션
- `mandu-mcp-deploy` — 빌드/배포
- `mandu-create-feature`, `mandu-create-api`, `mandu-debug`, `mandu-guard-guide` — 도메인 지식 skill