@mandujs/mcp 0.38.4 → 0.38.6

package/src/tools/hydration.ts

@@ -18,17 +18,17 @@ export const hydrationToolDefinitions: Tool[] = [
     name: "mandu.build",
     description:
       "Build client bundles for hydration. Compiles client slots (.client.ts) into browser-ready JavaScript bundles.",
-    annotations: {
-      destructiveHint: true,
-      readOnlyHint: false,
-      idempotentHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {
-        minify: {
-          type: "boolean",
-          description: "Minify the output bundles (default: true in production)",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+      idempotentHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        minify: {
+          type: "boolean",
+          description: "Minify the output bundles (default: true in production)",
         },
         sourcemap: {
           type: "boolean",
@@ -39,67 +39,67 @@ export const hydrationToolDefinitions: Tool[] = [
           items: { type: "string" },
           description:
             "Only rebuild specific islands by routeId. Skips Runtime/Router/Vendor rebuild for faster incremental updates. Omit to rebuild everything.",
-        },
-      },
-      required: [],
-      additionalProperties: false,
-    },
-  },
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
   {
     name: "mandu.build.status",
     description:
       "Get the current build status, bundle manifest, and statistics for client bundles.",
-    annotations: {
-      readOnlyHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {},
-      required: [],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "mandu.island.list",
-    description:
-      "Legacy alias for page client mount diagnostics. Prefer mandu.pageClientMount.list for terminology that separates page-level hydration from nested islands.",
-    annotations: {
-      readOnlyHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {},
-      required: [],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "mandu.pageClientMount.list",
-    description:
-      "List page-level client mounts: page routes that need a route-level clientModule and bundle. This is distinct from nested islands/partials.",
-    annotations: {
-      readOnlyHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {},
-      required: [],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "mandu.hydration.set",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "mandu.island.list",
+    description:
+      "Legacy alias for page client mount diagnostics. Prefer mandu.pageClientMount.list for terminology that separates page-level hydration from nested islands.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "mandu.pageClientMount.list",
+    description:
+      "List page-level client mounts: page routes that need a route-level clientModule and bundle. This is distinct from nested islands/partials.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "mandu.hydration.set",
     description:
       "Set hydration configuration for a specific route. Updates the route's hydration strategy and priority.",
-    annotations: {
-      readOnlyHint: false,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {
-        routeId: {
-          type: "string",
-          description: "The route ID to configure",
+    annotations: {
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to configure",
         },
         strategy: {
           type: "string",
@@ -117,25 +117,25 @@ export const hydrationToolDefinitions: Tool[] = [
           type: "boolean",
           description: "Whether to preload the bundle with modulepreload",
         },
-      },
-      required: ["routeId"],
-      additionalProperties: false,
-    },
-  },
-  {
+      },
+      required: ["routeId"],
+      additionalProperties: false,
+    },
+  },
+  {
     name: "mandu.hydration.addClientSlot",
     description:
       "Add a client slot file for a route to enable hydration. Creates the .client.ts file and updates the manifest.",
-    annotations: {
-      destructiveHint: false,
-      readOnlyHint: false,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {
-        routeId: {
-          type: "string",
-          description: "The route ID to add client slot for",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to add client slot for",
         },
         strategy: {
           type: "string",
@@ -147,14 +147,14 @@ export const hydrationToolDefinitions: Tool[] = [
           enum: ["immediate", "visible", "idle", "interaction"],
           description: "Hydration priority (default: visible)",
         },
-      },
-      required: ["routeId"],
-      additionalProperties: false,
-    },
-  },
-];
-
-export function hydrationTools(projectRoot: string) {
+      },
+      required: ["routeId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function hydrationTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
@@ -234,76 +234,76 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    "mandu.pageClientMount.list": async () => {
-      // Load manifest
-      const manifestResult = await loadManifest(paths.manifestPath);
-      if (!manifestResult.success || !manifestResult.data) {
-        return { error: manifestResult.errors };
-      }
-
-      const pageClientMounts = manifestResult.data.routes
-        .filter((route) => route.kind === "page")
-        .map((route) => {
-          const hydration = getRouteHydration(route);
-          const needsClientMount = needsHydration(route);
-          const warning = needsClientMount && !route.clientModule
-            ? `Route has hydration strategy '${hydration.strategy}' but no clientModule; build would emit no route bundle.`
-            : null;
-
-          return {
-            routeId: route.id,
-            pattern: route.pattern,
-            hasClientModule: !!route.clientModule,
-            clientModule: route.clientModule || null,
-            needsClientMount,
-            // Backward compatibility for older agents that read `isIsland`.
-            isIsland: needsClientMount,
-            status: needsClientMount ? (route.clientModule ? "ready" : "broken") : "static",
-            warning,
-            hydration: {
-              strategy: hydration.strategy,
-              priority: hydration.priority,
+    "mandu.pageClientMount.list": async () => {
+      // Load manifest
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+
+      const pageClientMounts = manifestResult.data.routes
+        .filter((route) => route.kind === "page")
+        .map((route) => {
+          const hydration = getRouteHydration(route);
+          const needsClientMount = needsHydration(route);
+          const warning = needsClientMount && !route.clientModule
+            ? `Route has hydration strategy '${hydration.strategy}' but no clientModule; build would emit no route bundle.`
+            : null;
+
+          return {
+            routeId: route.id,
+            pattern: route.pattern,
+            hasClientModule: !!route.clientModule,
+            clientModule: route.clientModule || null,
+            needsClientMount,
+            // Backward compatibility for older agents that read `isIsland`.
+            isIsland: needsClientMount,
+            status: needsClientMount ? (route.clientModule ? "ready" : "broken") : "static",
+            warning,
+            hydration: {
+              strategy: hydration.strategy,
+              priority: hydration.priority,
               preload: hydration.preload,
-            },
-          };
-        });
-
-      const pageClientMountCount = pageClientMounts.filter((i) => i.needsClientMount).length;
-      const staticCount = pageClientMounts.filter((i) => !i.needsClientMount).length;
-      const activeMounts = pageClientMounts.filter((i) => i.needsClientMount);
-      const staticPages = pageClientMounts.filter((i) => !i.needsClientMount);
-
-      return {
-        terminology: {
-          pageClientMount:
-            "A page route whose whole page is hydrated from a route-level clientModule and route bundle.",
-          island:
-            "A nested or route-local island bundle, distinct from page client mounts. Use mandu.runtime.status for both collections.",
-        },
-        totalPages: pageClientMounts.length,
-        pageClientMountCount,
-        staticCount,
-        pageClientMounts: activeMounts,
-        staticPages,
-        // Backward compatibility for older clients.
-        islandCount: pageClientMountCount,
-        islands: activeMounts,
-      };
-    },
-
-    "mandu.island.list": async () => handlers["mandu.pageClientMount.list"]({}),
-
-    "mandu.hydration.set": async (args: Record<string, unknown>) => {
-      const validationError = validateRouteIdArgs(
-        args,
-        "mandu.hydration.set",
-        ["routeId", "strategy", "priority", "preload"],
-      );
-      if (validationError) return { error: validationError };
-
-      const { routeId, strategy, priority, preload } = args as {
-        routeId: string;
-        strategy?: SpecHydrationStrategy;
+            },
+          };
+        });
+
+      const pageClientMountCount = pageClientMounts.filter((i) => i.needsClientMount).length;
+      const staticCount = pageClientMounts.filter((i) => !i.needsClientMount).length;
+      const activeMounts = pageClientMounts.filter((i) => i.needsClientMount);
+      const staticPages = pageClientMounts.filter((i) => !i.needsClientMount);
+
+      return {
+        terminology: {
+          pageClientMount:
+            "A page route whose whole page is hydrated from a route-level clientModule and route bundle.",
+          island:
+            "A nested or route-local island bundle, distinct from page client mounts. Use mandu.runtime.status for both collections.",
+        },
+        totalPages: pageClientMounts.length,
+        pageClientMountCount,
+        staticCount,
+        pageClientMounts: activeMounts,
+        staticPages,
+        // Backward compatibility for older clients.
+        islandCount: pageClientMountCount,
+        islands: activeMounts,
+      };
+    },
+
+    "mandu.island.list": async () => handlers["mandu.pageClientMount.list"]({}),
+
+    "mandu.hydration.set": async (args: Record<string, unknown>) => {
+      const validationError = validateRouteIdArgs(
+        args,
+        "mandu.hydration.set",
+        ["routeId", "strategy", "priority", "preload"],
+      );
+      if (validationError) return { error: validationError };
+
+      const { routeId, strategy, priority, preload } = args as {
+        routeId: string;
+        strategy?: SpecHydrationStrategy;
         priority?: HydrationPriority;
         preload?: boolean;
       };
@@ -357,19 +357,19 @@ export function hydrationTools(projectRoot: string) {
         newHydration,
         message: `Updated hydration config for ${routeId}`,
       };
-    },
-
-    "mandu.hydration.addClientSlot": async (args: Record<string, unknown>) => {
-      const validationError = validateRouteIdArgs(
-        args,
-        "mandu.hydration.addClientSlot",
-        ["routeId", "strategy", "priority"],
-      );
-      if (validationError) return { error: validationError };
-
-      const { routeId, strategy = "island", priority = "visible" } = args as {
-        routeId: string;
-        strategy?: SpecHydrationStrategy;
+    },
+
+    "mandu.hydration.addClientSlot": async (args: Record<string, unknown>) => {
+      const validationError = validateRouteIdArgs(
+        args,
+        "mandu.hydration.addClientSlot",
+        ["routeId", "strategy", "priority"],
+      );
+      if (validationError) return { error: validationError };
+
+      const { routeId, strategy = "island", priority = "visible" } = args as {
+        routeId: string;
+        strategy?: SpecHydrationStrategy;
         priority?: HydrationPriority;
       };
 
@@ -449,31 +449,31 @@ export function hydrationTools(projectRoot: string) {
   };
 
   // Backward-compatible aliases (deprecated)
-  handlers["mandu_build"] = handlers["mandu.build"];
-  handlers["mandu_build_status"] = handlers["mandu.build.status"];
-  handlers["mandu_list_islands"] = handlers["mandu.island.list"];
-  handlers["mandu_page_client_mount_list"] = handlers["mandu.pageClientMount.list"];
-  handlers["mandu_set_hydration"] = handlers["mandu.hydration.set"];
-  handlers["mandu_hydration_set"] = handlers["mandu.hydration.set"];
-  handlers["mandu_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
-  handlers["mandu_hydration_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
-
-  return handlers;
-}
-
-function validateRouteIdArgs(
-  args: Record<string, unknown>,
-  toolName: string,
-  allowedKeys: readonly string[],
-): string | null {
-  if (typeof args.routeId !== "string" || args.routeId.trim().length === 0) {
-    const allowed = new Set(allowedKeys);
-    const unknownKeys = Object.keys(args).filter((key) => !allowed.has(key));
-    const got = unknownKeys.length > 0 ? ` (got unknown key${unknownKeys.length === 1 ? "" : "s"} '${unknownKeys.join("', '")}')` : "";
-    return `${toolName}: missing required parameter 'routeId'${got}`;
-  }
-  return null;
-}
+  handlers["mandu_build"] = handlers["mandu.build"];
+  handlers["mandu_build_status"] = handlers["mandu.build.status"];
+  handlers["mandu_list_islands"] = handlers["mandu.island.list"];
+  handlers["mandu_page_client_mount_list"] = handlers["mandu.pageClientMount.list"];
+  handlers["mandu_set_hydration"] = handlers["mandu.hydration.set"];
+  handlers["mandu_hydration_set"] = handlers["mandu.hydration.set"];
+  handlers["mandu_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
+  handlers["mandu_hydration_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];
+
+  return handlers;
+}
+
+function validateRouteIdArgs(
+  args: Record<string, unknown>,
+  toolName: string,
+  allowedKeys: readonly string[],
+): string | null {
+  if (typeof args.routeId !== "string" || args.routeId.trim().length === 0) {
+    const allowed = new Set(allowedKeys);
+    const unknownKeys = Object.keys(args).filter((key) => !allowed.has(key));
+    const got = unknownKeys.length > 0 ? ` (got unknown key${unknownKeys.length === 1 ? "" : "s"} '${unknownKeys.join("', '")}')` : "";
+    return `${toolName}: missing required parameter 'routeId'${got}`;
+  }
+  return null;
+}
 
 /**
  * Generate a client slot template

package/src/tools/index.ts

@@ -290,10 +290,9 @@ export const TOOL_MODULES: ToolModule[] = [
 export function validateBuiltinToolModules(
   modules: readonly ToolModule[] = TOOL_MODULES
 ): string[] {
-  const issues: string[] = [];
-  const categories = new Set<string>();
-  const toolNames = new Map<string, string>();
-  const descriptions = new Map<string, string>();
+  const issues: string[] = [];
+  const categories = new Set<string>();
+  const toolNames = new Map<string, string>();
 
   for (const module of modules) {
     if (categories.has(module.category)) {
@@ -306,20 +305,7 @@ export function validateBuiltinToolModules(
     }
 
     for (const definition of module.definitions) {
-      if (!definition.description?.trim()) {
-        issues.push(`tool definition is missing description: ${definition.name} in ${module.category}`);
-      }
-      const normalizedDescription = definition.description?.trim().replace(/\s+/g, " ").toLowerCase();
-      if (normalizedDescription) {
-        const previousTool = descriptions.get(normalizedDescription);
-        if (previousTool) {
-          issues.push(
-            `duplicate tool description: ${definition.name} and ${previousTool} both describe the same action`
-          );
-        }
-        descriptions.set(normalizedDescription, definition.name);
-      }
-      const previousCategory = toolNames.get(definition.name);
+      const previousCategory = toolNames.get(definition.name);
       if (previousCategory) {
         issues.push(
           `duplicate tool definition: ${definition.name} in ${previousCategory} and ${module.category}`

package/src/tools/kitchen.ts

@@ -4,10 +4,10 @@
  * Enables any MCP-compatible agent to read client-side errors in real-time.
  */
 
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { loadManduConfig } from "@mandujs/core";
-import { getDevServerState } from "./project.js";
-import { readRuntimeControl } from "../utils/runtime-control.js";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { loadManduConfig } from "@mandujs/core";
+import { getDevServerState } from "./project.js";
+import { readRuntimeControl } from "../utils/runtime-control.js";
 
 export const kitchenToolDefinitions: Tool[] = [
   {
@@ -20,18 +20,18 @@ export const kitchenToolDefinitions: Tool[] = [
     inputSchema: {
       type: "object",
       properties: {
-        clear: {
-          type: "boolean",
-          description: "Clear errors after reading (default: false)",
-        },
-        baseURL: {
-          type: "string",
-          description: "Explicit dev server URL. Overrides runtime-control/config discovery.",
-        },
-        port: {
-          type: "number",
-          description: "Explicit dev server port. Overrides runtime-control/config discovery.",
-        },
+        clear: {
+          type: "boolean",
+          description: "Clear errors after reading (default: false)",
+        },
+        baseURL: {
+          type: "string",
+          description: "Explicit dev server URL. Overrides runtime-control/config discovery.",
+        },
+        port: {
+          type: "number",
+          description: "Explicit dev server port. Overrides runtime-control/config discovery.",
+        },
       },
       required: [],
     },
@@ -56,19 +56,19 @@ export const kitchenToolDefinitions: Tool[] = [
           description:
             "Include the extended diagnose report. Default true. Set false to lower latency when a11y_hints / package_export_gaps are noisy.",
         },
-        includeDiff: {
-          type: "boolean",
-          description:
-            "Include git diff against MANDU_DIFF_BASE (default HEAD). Default true. Set false to skip when git is unavailable.",
-        },
-        baseURL: {
-          type: "string",
-          description: "Explicit dev server URL. Overrides runtime-control/config discovery.",
-        },
-        port: {
-          type: "number",
-          description: "Explicit dev server port. Overrides runtime-control/config discovery.",
-        },
+        includeDiff: {
+          type: "boolean",
+          description:
+            "Include git diff against MANDU_DIFF_BASE (default HEAD). Default true. Set false to skip when git is unavailable.",
+        },
+        baseURL: {
+          type: "string",
+          description: "Explicit dev server URL. Overrides runtime-control/config discovery.",
+        },
+        port: {
+          type: "number",
+          description: "Explicit dev server port. Overrides runtime-control/config discovery.",
+        },
       },
       required: [],
     },
@@ -76,32 +76,32 @@ export const kitchenToolDefinitions: Tool[] = [
 ];
 
 /**
- * Resolve the dev server base URL. Prefers explicit args, then
- * `.mandu/runtime-control.json` from the running dev/start process, then
- * captured stdout, then config/default 3333. Shared by every Kitchen-backed
- * MCP tool so they all agree on where to fetch from.
+ * Resolve the dev server base URL. Prefers explicit args, then
+ * `.mandu/runtime-control.json` from the running dev/start process, then
+ * captured stdout, then config/default 3333. Shared by every Kitchen-backed
+ * MCP tool so they all agree on where to fetch from.
  */
-async function resolveDevServerBaseUrl(
-  projectRoot: string,
-  args: { baseURL?: unknown; port?: unknown } = {},
-): Promise<string> {
-  if (typeof args.baseURL === "string" && args.baseURL.trim()) {
-    return args.baseURL.trim().replace(/\/+$/, "");
-  }
-
-  const explicitPort = normalizePort(args.port);
-  if (explicitPort) {
-    return `http://localhost:${explicitPort}`;
-  }
-
-  const control = await readRuntimeControl(projectRoot);
-  if (control?.baseUrl) {
-    return control.baseUrl.replace(/\/+$/, "");
-  }
-
-  let port: number | undefined;
-
-  const serverState = getDevServerState();
+async function resolveDevServerBaseUrl(
+  projectRoot: string,
+  args: { baseURL?: unknown; port?: unknown } = {},
+): Promise<string> {
+  if (typeof args.baseURL === "string" && args.baseURL.trim()) {
+    return args.baseURL.trim().replace(/\/+$/, "");
+  }
+
+  const explicitPort = normalizePort(args.port);
+  if (explicitPort) {
+    return `http://localhost:${explicitPort}`;
+  }
+
+  const control = await readRuntimeControl(projectRoot);
+  if (control?.baseUrl) {
+    return control.baseUrl.replace(/\/+$/, "");
+  }
+
+  let port: number | undefined;
+
+  const serverState = getDevServerState();
   if (serverState) {
     for (const line of serverState.output) {
       const portMatch = line.match(/https?:\/\/localhost:(\d+)/);
@@ -115,21 +115,21 @@ async function resolveDevServerBaseUrl(
     const config = await loadManduConfig(projectRoot);
     port = config.server?.port ?? 3333;
   }
-
-  return `http://localhost:${port}`;
-}
-
-function normalizePort(value: unknown): number | undefined {
-  const raw = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
-  if (!Number.isInteger(raw) || raw < 1 || raw > 65535) return undefined;
-  return raw;
-}
+
+  return `http://localhost:${port}`;
+}
+
+function normalizePort(value: unknown): number | undefined {
+  const raw = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+  if (!Number.isInteger(raw) || raw < 1 || raw > 65535) return undefined;
+  return raw;
+}
 
 export function kitchenTools(projectRoot: string) {
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
-    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
-      const { clear = false } = args as { clear?: boolean };
-      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
+    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
+      const { clear = false } = args as { clear?: boolean };
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
 
       try {
         // Fetch errors from Kitchen API
@@ -185,12 +185,12 @@ export function kitchenTools(projectRoot: string) {
      */
     "mandu.devtools.context": async (args: Record<string, unknown>) => {
       const {
-        includeBundle = true,
-        includeDiagnose = true,
-        includeDiff = true,
-      } = args as { includeBundle?: boolean; includeDiagnose?: boolean; includeDiff?: boolean };
-
-      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
+        includeBundle = true,
+        includeDiagnose = true,
+        includeDiff = true,
+      } = args as { includeBundle?: boolean; includeDiagnose?: boolean; includeDiff?: boolean };
+
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot, args);
       const params = new URLSearchParams();
       if (!includeBundle) params.set("bundle", "0");
       if (!includeDiagnose) params.set("diagnose", "0");