@mandujs/mcp 0.38.5 → 0.38.7

package/README.md

@@ -136,9 +136,9 @@ bunx @mandujs/mcp --root /path/to/project
 
 ### Semantic Slots (RFC-001) 🆕
 
-| Tool | Description |
-|------|-------------|
-| `mandu_get_slot_constraints` | Get recommended slot constraint presets |
+| Tool | Description |
+|------|-------------|
+| `mandu_get_slot_constraints` | Get recommended slot constraint presets |
 
 ### Architecture Negotiation (RFC-001) 🆕
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.38.5",
+  "version": "0.38.7",
   "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.11",
+    "@mandujs/core": "^0.54.13",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/executor/error-handler.ts

@@ -35,6 +35,23 @@ export interface McpErrorResponse {
 export interface McpToolResponse {
   content: Array<{ type: string; text: string }>;
   isError?: boolean;
+  _meta?: McpResponseMeta;
+}
+
+export type McpNextActionKind = "none" | "inspect" | "verify" | "repair" | "retry";
+
+export interface McpNextAction {
+  kind: McpNextActionKind;
+  reason: string;
+  command?: string;
+  tool?: string;
+  input?: unknown;
+}
+
+export interface McpResponseMeta {
+  toolName: string;
+  ok: boolean;
+  nextAction: McpNextAction;
 }
 
 /**
@@ -186,6 +203,51 @@ function isSoftErrorResult(result: unknown): boolean {
   return false;
 }
 
+function inferNextAction(toolName: string, result: unknown, errorResponse?: McpErrorResponse): McpNextAction {
+  if (errorResponse) {
+    return {
+      kind: errorResponse.retryable ? "retry" : "repair",
+      reason: errorResponse.suggestion ?? errorResponse.error,
+    };
+  }
+
+  if (result && typeof result === "object") {
+    const obj = result as Record<string, unknown>;
+    if (isSoftErrorResult(result)) {
+      return { kind: "repair", reason: String(obj.error ?? "Tool returned an error result.") };
+    }
+    if (typeof obj.nextVerifyCommand === "string") {
+      return { kind: "verify", reason: "Tool returned an explicit verification command.", command: obj.nextVerifyCommand };
+    }
+    if (typeof obj.nextRepairInput === "string") {
+      return {
+        kind: "repair",
+        reason: "Tool returned a repair input artifact.",
+        command: `mandu agent repair --from ${obj.nextRepairInput}`,
+        input: obj.nextRepairInput,
+      };
+    }
+    if (obj.dryRun === true) {
+      return { kind: "inspect", reason: "Dry-run completed; review the preview before applying changes." };
+    }
+    if (Array.isArray(obj.nextSteps) && obj.nextSteps.length > 0) {
+      return { kind: "inspect", reason: "Tool returned follow-up steps.", input: obj.nextSteps };
+    }
+    if (typeof obj.tip === "string") {
+      return { kind: "inspect", reason: obj.tip };
+    }
+  }
+
+  return { kind: "none", reason: `${toolName} completed successfully.` };
+}
+
+function attachMeta(payload: unknown, meta: McpResponseMeta): unknown {
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    return { ...(payload as Record<string, unknown>), _meta: meta };
+  }
+  return { data: payload, _meta: meta };
+}
+
 export function createToolResponse(
   toolName: string,
   result: unknown,
@@ -193,28 +255,40 @@ export function createToolResponse(
 ): McpToolResponse {
   if (error) {
     const errorResponse = formatMcpError(error, toolName);
+    const meta: McpResponseMeta = {
+      toolName,
+      ok: false,
+      nextAction: inferNextAction(toolName, null, errorResponse),
+    };
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify(errorResponse, null, 2),
+          text: JSON.stringify(attachMeta(errorResponse, meta), null, 2),
         },
       ],
       isError: true,
+      _meta: meta,
     };
   }
 
   // Detect soft errors returned by handlers (e.g. { error: "Route not found" })
   const softError = isSoftErrorResult(result);
+  const meta: McpResponseMeta = {
+    toolName,
+    ok: !softError,
+    nextAction: inferNextAction(toolName, result),
+  };
 
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(result, null, 2),
+        text: JSON.stringify(attachMeta(result, meta), null, 2),
       },
     ],
     ...(softError && { isError: true }),
+    _meta: meta,
   };
 }
 

package/src/index.ts

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

package/src/prompts.ts

@@ -48,10 +48,10 @@ Follow these steps using Mandu MCP tools:
 1. Read current route manifest: Resource mandu://routes
 2. Read project config: Resource mandu://config
 3. Negotiate the feature spec: Tool mandu.negotiate
-4. Generate scaffold: Tool mandu.negotiate.scaffold
-5. If client interactivity needed, create island: Tool mandu_create_island
-   Use @mandujs/core/client with wrapComponent(Component) or island({ setup, render })
-6. If data requirements exist, create slot: Tool mandu_create_slot
+4. Generate scaffold: Tool mandu.negotiate.scaffold
+5. If client interactivity needed, create island: Tool mandu_create_island
+   Use @mandujs/core/client with wrapComponent(Component) or island({ setup, render })
+6. If data requirements exist, create slot: Tool mandu_create_slot
    Slots are server-side data loaders that run before render
 7. If API is exposed, define contract: Tool mandu_create_contract
    Contracts are Zod schemas for validation and OpenAPI generation

package/src/resources/handlers.ts

@@ -1,10 +1,8 @@
 import type { Resource } from "@modelcontextprotocol/sdk/types.js";
-import {
-  loadManifest,
-  getTransactionStatus,
-  getWatcher,
-  type GeneratedMap,
-} from "@mandujs/core";
+import { loadManifest } from "@mandujs/core";
+import { getTransactionStatus } from "@mandujs/core/change";
+import type { GeneratedMap } from "@mandujs/core/generator";
+import { getWatcher } from "@mandujs/core/watcher";
 import { getProjectPaths, readJsonFile } from "../utils/project.js";
 import {
   getGuide,

package/src/resources/skills/guides.ts

@@ -377,21 +377,21 @@ Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티
 | \`idle\` | 브라우저 유휴 시 | 비중요 기능 |
 | \`interaction\` | 사용자 상호작용 시 | 클릭해야 활성화 |
 
-## Inline client region 만들기
-
-### 1. 클라이언트 컴포넌트 작성
-
-\`\`\`tsx
-// app/counter/client.tsx
-
-"use client";
-
-import { useState } from "react";
-
-export function Counter({ initial = 0 }: { initial?: number }) {
-  const [count, setCount] = useState(initial);
-
-  return (
+## Inline client region 만들기
+
+### 1. 클라이언트 컴포넌트 작성
+
+\`\`\`tsx
+// app/counter/client.tsx
+
+"use client";
+
+import { useState } from "react";
+
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial);
+
+  return (
     <div>
       <p>Count: {count}</p>
       <button onClick={() => setCount(c => c - 1)}>-</button>
@@ -399,43 +399,43 @@ export function Counter({ initial = 0 }: { initial?: number }) {
     </div>
   );
 }
-\`\`\`
-
-### 2. 서버 페이지에서 partial로 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import { partial } from "@mandujs/core/client";
-import { Counter } from "./client";
-
-const CounterPartial = partial({
-  component: Counter,
-  priority: "visible",
-});
-
-export default function CounterPage() {
-  return (
+\`\`\`
+
+### 2. 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div>
       <h1>Counter Demo</h1>
       <p>이 텍스트는 정적 HTML입니다.</p>
-
-      {/* 이 부분만 hydration됩니다 */}
-      <CounterPartial.Render initial={10} />
-    </div>
-  );
-}
-\`\`\`
-
-## Mandu.island() API
-
-고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
-정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
-않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
-사용하세요.
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+
+      {/* 이 부분만 hydration됩니다 */}
+      <CounterPartial.Render initial={10} />
+    </div>
+  );
+}
+\`\`\`
+
+## Mandu.island() API
+
+고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
+정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
+않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
+사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState, useCallback } from "react";

package/src/resources/skills/loader.ts

@@ -27,11 +27,11 @@ export interface RuleMeta {
 }
 
 // Available skills
-const SKILL_IDS = [
-  "mandu-agent-workflow",
-  "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",
@@ -95,9 +95,9 @@ export function listSkills(): SkillMeta[] {
 }
 
 function getSkillDescription(id: string): string {
-  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",
+  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

@@ -1,124 +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.
+---
+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

@@ -1,7 +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"]
-}
+{
+  "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"]
+}