@mandujs/mcp 0.37.3 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.37.3",
+  "version": "0.38.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.54.3",
+    "@mandujs/core": "^0.54.6",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/index.ts

@@ -86,10 +86,11 @@ export {
 // Profile exports
 export {
   type McpProfile,
-  PROFILE_CATEGORIES,
-  getProfileCategories,
-  isValidProfile,
-} from "./profiles.js";
+  PROFILE_CATEGORIES,
+  getProfileCategories,
+  isValidProfile,
+  resolveMcpProfile,
+} from "./profiles.js";
 
 // CLI entry point
 import { startServer } from "./server.js";

package/src/profiles.ts

@@ -1,34 +1,57 @@
-/**
- * MCP Tool Profiles
- *
- * Controls how many tool categories are exposed to AI agents.
- * - minimal: Core scaffolding tools only (~15 tools)
- * - standard: Common development workflow (~40 tools)
- * - full: All categories, no filtering (default)
- */
-
-export type McpProfile = "minimal" | "standard" | "full";
-
-export const PROFILE_CATEGORIES: Record<McpProfile, string[] | null> = {
-  minimal: ["spec", "project", "guard", "generate"],
-  standard: [
-    "spec", "project", "guard", "generate",
-    "contract", "slot", "hydration", "seo",
-    "component", "kitchen", "composite",
-  ],
-  full: null,
-};
+/**
+ * MCP Tool Profiles
+ *
+ * Controls how many tool categories are exposed to AI agents.
+ * - agent-core: Canonical agent workflow plus docs grounding (default)
+ * - agent-full: Agent workflow plus Mandu domain tools
+ * - internal: All categories, no filtering
+ */
+
+export type McpProfile = "agent-core" | "agent-full" | "internal";
+
+export const PROFILE_CATEGORIES: Record<McpProfile, string[] | null> = {
+  "agent-core": ["agent", "docs"],
+  "agent-full": [
+    "agent",
+    "docs",
+    "spec",
+    "generate",
+    "slot",
+    "slot-validation",
+    "hydration",
+    "contract",
+    "guard",
+    "run-tests",
+    "lint",
+  ],
+  internal: null,
+};
 
 /**
  * Returns allowed category names for a profile, or null if all categories are allowed.
  */
-export function getProfileCategories(profile: McpProfile): string[] | null {
-  return PROFILE_CATEGORIES[profile] ?? null;
-}
-
+export function getProfileCategories(profile: McpProfile): string[] | null {
+  return PROFILE_CATEGORIES[profile] ?? null;
+}
+
 /**
  * Type guard for valid profile strings.
  */
-export function isValidProfile(value: string): value is McpProfile {
-  return value === "minimal" || value === "standard" || value === "full";
-}
+export function isValidProfile(value: string): value is McpProfile {
+  return value === "agent-core" || value === "agent-full" || value === "internal";
+}
+
+/**
+ * Resolve current and legacy profile names to the new official profile set.
+ */
+export function resolveMcpProfile(
+  value: string | undefined,
+  fallback: McpProfile = "agent-core",
+): McpProfile {
+  if (!value) return fallback;
+  if (isValidProfile(value)) return value;
+  if (value === "minimal") return "agent-core";
+  if (value === "standard") return "agent-full";
+  if (value === "full") return "internal";
+  return fallback;
+}

package/src/resources/skills/loader.ts

@@ -27,10 +27,11 @@ export interface RuleMeta {
 }
 
 // Available skills
-const SKILL_IDS = [
-  "mandu-slot",
-  "mandu-fs-routes",
-  "mandu-hydration",
+const SKILL_IDS = [
+  "mandu-agent-workflow",
+  "mandu-slot",
+  "mandu-fs-routes",
+  "mandu-hydration",
   "mandu-guard",
   "mandu-performance",
   "mandu-composition",
@@ -94,8 +95,9 @@ export function listSkills(): SkillMeta[] {
 }
 
 function getSkillDescription(id: string): string {
-  const descriptions: Record<string, string> = {
-    "mandu-slot": "Business logic with Mandu.filling() API",
+  const descriptions: Record<string, string> = {
+    "mandu-agent-workflow": "Canonical context -> plan -> apply -> verify -> repair workflow for Mandu agents",
+    "mandu-slot": "Business logic with Mandu.filling() API",
     "mandu-fs-routes": "File-system based routing patterns",
     "mandu-hydration": "Island hydration and client components",
     "mandu-guard": "Architecture enforcement and layer dependencies",

package/src/resources/skills/mandu-agent-workflow/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: mandu-agent-workflow
+description: |
+  Canonical Mandu agent workflow. Use first in Mandu projects before direct
+  source edits so Codex, Claude Code, Gemini CLI, and other agents follow the
+  same context -> plan -> apply -> verify -> repair loop.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Agent Workflow
+
+Mandu is an agent-native fullstack framework. Agents should not begin by
+guessing file structure or calling low-level tools directly. Start with the
+official agent surface, then use domain tools only when the plan identifies a
+specific domain.
+
+## When to Use
+
+Use this skill for every Mandu project task that may inspect, create, modify, or
+verify application code, framework configuration, contracts, slots, islands, or
+deployment artifacts.
+
+## Canonical Workflow
+
+Always follow this loop:
+
+```text
+context -> plan -> apply -> verify -> repair
+```
+
+1. `context`: read the project map.
+2. `plan`: convert the user request into domains, files, risks, and checks.
+3. `apply`: prefer intent-level MCP/domain tools; direct edits must be grounded
+   in the plan.
+4. `verify`: run the single agent-facing verification report.
+5. `repair`: convert failures into next actions, then verify again.
+
+## Preferred MCP Tools
+
+Use these first when MCP is available:
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| context | `mandu.agent.context` | Project map, routes, APIs, slots, contracts, guard, diagnostics. |
+| plan | `mandu.agent.plan` | Deterministic task plan with domains, files, tools, risks. |
+| apply | `mandu.agent.apply` | Ordered action preview from `.mandu/agent-plan.json`. |
+| verify | `mandu.agent.verify` | Unified post-change guard/diagnose/contract report. |
+| repair | `mandu.agent.repair` | Structured next actions from `.mandu/agent-verify.json`. |
+
+If MCP is unavailable, use the CLI equivalents:
+
+```bash
+mandu agent context --json
+mandu agent plan "<task>" --json --write
+mandu agent apply --from .mandu/agent-plan.json --json
+mandu agent verify --changed --json --write
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## Allowed File Edits
+
+Direct file edits are allowed only after `plan` identifies the relevant domain
+and the agent has inspected the local pattern. Prefer MCP/domain generation for:
+
+- pages, layouts, and API routes
+- contracts and OpenAPI-related files
+- slots and fillings
+- islands, partials, and hydration boundaries
+- deploy intent and provider artifacts
+
+Do not use destructive cleanup, cache removal, deploy execution, or broad
+refactors without an explicit plan and verification path.
+
+## Domain Skill Escalation
+
+Read the matching domain skill when `mandu.agent.plan` includes that domain:
+
+| Domain | Skill |
+|--------|-------|
+| route/api | `mandu-fs-routes` |
+| hydration/island/partial | `mandu-hydration` |
+| slot/filling | `mandu-slot` |
+| guard/import boundary | `mandu-guard` |
+| test/e2e/ATE | `mandu-testing` |
+| deploy | `mandu-deployment` |
+| security/auth/session | `mandu-security` |
+| styling/ui/design | `mandu-styling`, `mandu-ui`, `mandu-composition` |
+| performance | `mandu-performance` |
+
+Domain skills are addenda. They must not replace the canonical workflow.
+
+## Verification Command
+
+Every code-changing task should end with:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Run additional commands listed in the plan or verify report, usually
+`bun run typecheck` and targeted `bun test` commands.
+
+## Repair Path
+
+When verify fails:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+Apply only actions that are explicitly safe and scoped. After any repair, run
+`mandu agent verify --changed --json --write` again.
+
+## Common Failures
+
+- Skipping context and editing the wrong route or contract path.
+- Calling low-level Guard, Doctor, Fix, ATE, or deploy tools before a plan.
+- Treating a domain skill as the full workflow.
+- Ending a task after tests without writing or reading the agent verify report.
+- Applying broad file changes when `agent.apply` only produced a dry-run action
+  report.

package/src/resources/skills/mandu-agent-workflow/metadata.json

@@ -0,0 +1,7 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "May 2026",
+  "abstract": "Canonical Mandu agent workflow for Codex, Claude Code, Gemini CLI, and other coding agents. Establishes context -> plan -> apply -> verify -> repair as the default loop and routes domain work through focused Mandu skills and MCP tools.",
+  "tags": ["agent", "workflow", "mcp", "skills", "mandu"]
+}

package/src/resources/skills/mandu-composition/SKILL.md

@@ -11,13 +11,53 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Composition
-
-Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, 상태 관리 인터페이스, Provider 패턴, slot-client 분리를 다룹니다. Vercel의 Composition Patterns를 Mandu 컨텍스트로 변환하여 적용합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Composition
+
+Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, 상태 관리 인터페이스, Provider 패턴, slot-client 분리를 다룹니다. Vercel의 Composition Patterns를 Mandu 컨텍스트로 변환하여 적용합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects composition, UI, hydration, slot, or component domains.
+
+Canonical workflow step: `plan -> apply -> verify`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.design.get`, `mandu.island.list` |
+| apply | `mandu.agent.apply` |
+| verify | `mandu.agent.verify`, `mandu.design.check`, `mandu.slot.validate` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- Island/client component files named in the plan
+- Provider/state modules scoped to the target feature
+- Slot-client boundaries only when the plan includes slot or hydration domains
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Refactoring component APIs without checking island/client boundaries
+- Adding shared state providers broader than the planned feature
+- Mixing slot server logic into client composition files
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Designing Island component architecture
 - Managing shared state between Islands
 - Building reusable component APIs

package/src/resources/skills/mandu-deployment/SKILL.md

@@ -12,20 +12,63 @@ globs:
   - "bunfig.toml"
 ---
 
-# Mandu Deployment Skill
-
-Mandu 앱을 프로덕션 환경에 안전하고 효율적으로 배포하기 위한 가이드입니다.
-
-## 핵심 원칙
-
-1. **Bun 네이티브**: Bun 런타임과 번들러를 최대한 활용
+# Mandu Deployment Skill
+
+Mandu 앱을 프로덕션 환경에 안전하고 효율적으로 배포하기 위한 가이드입니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects the deploy domain.
+
+Canonical workflow step: `plan -> apply -> verify`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.deploy.plan` |
+| apply | `mandu.agent.apply`, `mandu.deploy.compile` |
+| verify | `mandu.agent.verify`, `mandu.deploy.preview` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- `.mandu/deploy.intent.json`
+- Provider artifacts named in the plan, such as `render.yaml`, `Dockerfile`, `docker-compose.yml`, `fly.toml`, `vercel.json`, or `netlify.toml`
+- CI workflow files only when deploy automation is explicitly requested
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Executing a provider deploy before a dry-run or preview step
+- Writing secrets into tracked config
+- Changing provider artifacts without route/deploy intent verification
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## 핵심 원칙
+
+1. **Bun 네이티브**: Bun 런타임과 번들러를 최대한 활용
 2. **환경 분리**: 개발/스테이징/프로덕션 환경 명확히 구분
 3. **자동화**: CI/CD를 통한 일관된 배포 프로세스
 4. **보안 우선**: 민감 정보는 환경 변수로 관리
 
-## 빠른 시작
-
-### Render 배포 (권장)
+## Provider Artifact Examples
+
+Use these examples only after `mandu.agent.plan` selects the deploy domain and
+`mandu.agent.apply` has produced the intended action order.
+
+### Render 배포 (권장)
 
 ```yaml
 # render.yaml

package/src/resources/skills/mandu-fs-routes/SKILL.md

@@ -10,13 +10,53 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu FS Routes
-
-FS Routes는 파일 시스템 기반 라우팅입니다. `app/` 폴더의 파일 구조가 URL이 됩니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu FS Routes
+
+FS Routes는 파일 시스템 기반 라우팅입니다. `app/` 폴더의 파일 구조가 URL이 됩니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects the route or API domain.
+
+Canonical workflow step: `plan -> apply -> verify`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.route.list` |
+| apply | `mandu.agent.apply`, `mandu.generate`, `mandu.route.add` |
+| verify | `mandu.agent.verify`, `mandu.manifest.validate` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- `app/**/page.tsx`, `app/**/layout.tsx`, `app/**/route.ts`
+- Route-local metadata files and co-located helpers
+- Related contract/slot files only when the plan includes those domains
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Creating a page or API route before reading the local `app/` pattern
+- Editing generated route manifests by hand
+- Adding API files without contract verification when the plan includes API work
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Creating new pages or API endpoints
 - Setting up dynamic routes with parameters
 - Implementing shared layouts

package/src/resources/skills/mandu-guard/SKILL.md

@@ -10,14 +10,53 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Guard
-
-Mandu Guard는 아키텍처 규칙을 강제하는 시스템입니다.
-레이어 간 의존성을 검사하고 위반을 실시간으로 감지합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Guard
+
+Mandu Guard는 아키텍처 규칙을 강제하는 시스템입니다.
+레이어 간 의존성을 검사하고 위반을 실시간으로 감지합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.verify` reports guard diagnostics or `mandu.agent.plan` selects the guard domain.
+
+Canonical workflow step: `verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan` |
+| verify | `mandu.agent.verify`, `mandu.guard.check`, `mandu.guard.explain` |
+| repair | `mandu.agent.repair`, `mandu.guard.heal` |
+
+Allowed file edits:
+
+- Source files that violate import/layer rules
+- `mandu.config.*` guard settings only when the plan explicitly changes policy
+- Generated files are not direct-edit targets
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Running low-level guard commands before reading the agent verify report
+- Weakening guard config instead of fixing the import boundary
+- Directly editing generated files to silence diagnostics
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Setting up architecture rules
 - Checking layer dependencies
 - Validating import paths
@@ -103,23 +142,17 @@ shared       # Shared
 | `SLOT_NAMING` | Slot file naming rule violation |
 | `FORBIDDEN_IMPORT` | Forbidden import (fs, child_process, etc.) |
 
-## CLI Commands
-
-```bash
-# Architecture check
-bunx mandu guard arch
-
-# Watch mode
-bunx mandu guard arch --watch
-
-# CI mode (exit 1 on violation)
-bunx mandu guard arch --ci
-
-# Use specific preset
-bunx mandu guard arch --preset fsd
-```
-
-## How to Use
+## Low-Level CLI Commands
+
+Use these only when `agent verify` or `agent repair` asks for guard-specific detail:
+
+```bash
+mandu agent verify --changed --json --write
+mandu guard arch --ci
+mandu guard arch --preset fsd
+```
+
+## How to Use
 
 Read individual rule files for detailed explanations:
 

package/src/resources/skills/mandu-hydration/SKILL.md

@@ -10,14 +10,54 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Island Hydration
-
-Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
-대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Island Hydration
+
+Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
+대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects the hydration, island, partial, or route domain.
+
+Canonical workflow step: `plan -> apply -> verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.island.list` |
+| apply | `mandu.agent.apply`, `mandu.hydration.set`, `mandu.hydration.addClientSlot` |
+| verify | `mandu.agent.verify`, `mandu.build`, `mandu.build.status` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- `app/**/*.partial.tsx`, `app/**/*.island.tsx`, route-local client components
+- Page hydration metadata only when the plan names the route
+- Shared client utilities only after inspecting existing client boundaries
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Rendering page-level islands inline instead of using `partial().Render`
+- Forgetting route hydration metadata when a server page renders partials
+- Moving server-only imports into client bundles
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Creating interactive client components
 - Adding client-side state to pages
 - Implementing partial hydration