mandu-mcp-index
MCP 도구 오케스트레이션 라우터 (always-on). 108개 MCP 도구 중 상황에 맞는 워크플로우 skill 선택, 집계>세분 우선순위, anti-pattern 카탈로그. MCP 도구 호출 직전 자동 참조.
SKILL.mddocs/archive/skills/package-v0/mandu-mcp-index/SKILL.md
GitHubMandu MCP Index
@mandujs/mcp 는 약 108 개의 MCP 도구를 노출합니다. 이 문서는
flat palette 가 아니라 tiered hierarchy 로 도구를 선택하도록 안내합니다.
핵심 원칙:
- Workflow skill 먼저. 개별 도구가 아닌
mandu-mcp-*workflow skill 을 먼저 본다. - 집계 > 세분. 같은 일을 하는 집계 도구가 있으면 그걸 먼저. 실패했을 때만 세분 도구로 drill-down.
- 안전망 먼저.
refactor_*/ 마이그레이션은mandu.history.snapshot+mandu.tx.begin안에서만. - 순서는 강제.
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 ofmandu.brain.doctor) — 구조/임포트/위치 진단mandu.feature.create,mandu.resource.create— 복합 스캐폴드mandu_generate_scaffold(alias ofmandu.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.rewriteGeneratedBarrelmandu.refactor.migrateRouteConventionsmandu.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-verifyfast 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