@mandujs/mcp 0.38.9 → 0.38.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.38.9",
+  "version": "0.38.11",
   "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.17",
+    "@mandujs/core": "^0.54.19",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/tools/hydration.ts

@@ -232,31 +232,39 @@ 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;
-
+    "mandu.pageClientMount.list": async () => {
+      // Load manifest
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+      const bundleManifest = await readJsonFile<BundleManifest>(
+        path.join(projectRoot, ".mandu", "manifest.json"),
+      );
+      const partialBoundaryCount = Object.keys(bundleManifest?.partials ?? {}).length;
+
+      const pageClientMounts = manifestResult.data.routes
+        .filter((route) => route.kind === "page")
+        .map((route) => {
+          const hydration = getRouteHydration(route);
+          const needsClientMount = needsHydration(route);
+          const clientBoundaryCount = route.boundaries?.length ?? 0;
+          const hasRouteLevelClientMount = needsClientMount && !!route.clientModule;
+          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",
+            pattern: route.pattern,
+            hasClientModule: !!route.clientModule,
+            clientModule: route.clientModule || null,
+            needsClientMount,
+            hasRouteLevelClientMount,
+            clientBoundaryCount,
+            // Backward compatibility for older agents that read `isIsland`.
+            isIsland: needsClientMount,
+            status: needsClientMount ? (route.clientModule ? "ready" : "broken") : "static",
             warning,
             hydration: {
               strategy: hydration.strategy,
@@ -266,23 +274,38 @@ export function hydrationTools(projectRoot: string) {
           };
         });
 
-      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,
+      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);
+      const clientBoundaryCount = pageClientMounts.reduce(
+        (count, route) => count + route.clientBoundaryCount,
+        0,
+      );
+
+      return {
+        terminology: {
+          pageClientMount:
+            "A page route whose whole page is hydrated from a route-level clientModule and route bundle.",
+          clientBoundary:
+            "A compiler-discovered nested client component marker recorded on RouteSpec.boundaries.",
+          partialBoundary:
+            "A legacy/runtime partial bundle listed in .mandu/manifest.json partials.",
+          island:
+            "Legacy umbrella term. Prefer pageClientMount, clientBoundary, or partialBoundary for precise reports.",
+        },
+        boundarySummary: {
+          clientBoundaryCount,
+          partialBoundaryCount,
+          pageClientMountCount,
+        },
+        totalPages: pageClientMounts.length,
+        pageClientMountCount,
+        clientBoundaryCount,
+        partialBoundaryCount,
+        staticCount,
+        pageClientMounts: activeMounts,
+        staticPages,
         // Backward compatibility for older clients.
         islandCount: pageClientMountCount,
         islands: activeMounts,

package/src/tools/spec.ts

@@ -3,7 +3,7 @@ import {
   loadManifest,
   generateManifest,
 } from "@mandujs/core";
-import { getProjectPaths, isInsideProject } from "../utils/project.js";
+import { getProjectPaths, isInsideProject, readJsonFile } from "../utils/project.js";
 import path from "path";
 import fs from "fs/promises";
 
@@ -21,8 +21,8 @@ export const specToolDefinitions: Tool[] = [
       required: [],
     },
   },
-  {
-    name: "mandu.route.get",
+  {
+    name: "mandu.route.get",
     description:
       "Get full details of a specific route by its ID. Use before modifying a route.",
     annotations: {
@@ -37,10 +37,32 @@ export const specToolDefinitions: Tool[] = [
         },
       },
       required: ["routeId"],
-    },
-  },
-  {
-    name: "mandu.route.add",
+    },
+  },
+  {
+    name: "mandu.route.boundaries",
+    description:
+      "Inspect compiler-discovered client boundary metadata for one route or all routes, including route manifest records and optional bundle manifest entries.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "Optional route ID to inspect. Omit to list boundaries for all routes.",
+        },
+        includeBundle: {
+          type: "boolean",
+          description: "When true, also correlate route boundaries with .mandu/manifest.json boundary bundle entries.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu.route.add",
     description:
       "Scaffold a new route in app/ with optional slot and contract files, then regenerate the manifest.",
     annotations: {
@@ -129,7 +151,7 @@ export function specTools(projectRoot: string) {
       };
     },
 
-    "mandu.route.get": async (args: Record<string, unknown>) => {
+    "mandu.route.get": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       const result = await loadManifest(paths.manifestPath);
@@ -142,10 +164,117 @@ export function specTools(projectRoot: string) {
         return { error: `Route not found: ${routeId}` };
       }
 
-      return { route };
-    },
-
-    "mandu.route.add": async (args: Record<string, unknown>) => {
+      return { route };
+    },
+
+    "mandu.route.boundaries": async (args: Record<string, unknown>) => {
+      const { routeId, includeBundle = false } = args as { routeId?: string; includeBundle?: boolean };
+
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      const bundleManifestPath = path.join(projectRoot, ".mandu", "manifest.json");
+      const bundleManifest = includeBundle
+        ? await readJsonFile<{
+            boundaries?: Record<string, {
+              route?: string;
+              js?: string;
+              module?: string;
+              exportName?: string;
+              priority?: string;
+              hydrate?: string;
+            }>;
+          }>(bundleManifestPath)
+        : null;
+
+      const routes = routeId
+        ? result.data.routes.filter((route) => route.id === routeId)
+        : result.data.routes;
+
+      if (routeId && routes.length === 0) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      const inspected = routes.map((route) => {
+        const boundaries = route.boundaries ?? [];
+        const diagnostics: Array<{
+          code: string;
+          severity: "warning";
+          message: string;
+          routeId: string;
+          boundaryId?: string;
+        }> = [];
+
+        if (includeBundle && boundaries.length > 0 && !bundleManifest) {
+          diagnostics.push({
+            code: "MANDU_BOUNDARY_BUNDLE_MANIFEST_MISSING",
+            severity: "warning",
+            message: "Route has compiler-discovered client boundaries, but .mandu/manifest.json was not found. Run mandu build to inspect generated boundary chunks.",
+            routeId: route.id,
+          });
+        }
+
+        const boundaryRecords = boundaries.map((boundary) => {
+          const bundle = bundleManifest?.boundaries?.[boundary.id];
+          if (includeBundle && bundleManifest && !bundle) {
+            diagnostics.push({
+              code: "MANDU_BOUNDARY_BUNDLE_ENTRY_MISSING",
+              severity: "warning",
+              message: `Boundary '${boundary.id}' is present in routes manifest but missing from .mandu/manifest.json boundaries.`,
+              routeId: route.id,
+              boundaryId: boundary.id,
+            });
+          }
+
+          return {
+            id: boundary.id,
+            routeId: boundary.routeId,
+            module: boundary.module,
+            importSpecifier: boundary.importSpecifier,
+            exportName: boundary.exportName,
+            localName: boundary.localName,
+            hydrate: boundary.hydrate,
+            ordinal: boundary.ordinal,
+            propsSource: boundary.propsSource,
+            propsKeys: boundary.propsKeys ?? [],
+            hasSpreadProps: !!boundary.hasSpreadProps,
+            source: boundary.source,
+            bundle: bundle
+              ? {
+                  js: bundle.js ?? null,
+                  priority: bundle.priority ?? null,
+                  hydrate: bundle.hydrate ?? null,
+                }
+              : null,
+          };
+        });
+
+        return {
+          routeId: route.id,
+          pattern: route.pattern,
+          module: route.module,
+          boundaryCount: boundaryRecords.length,
+          boundaries: boundaryRecords,
+          diagnostics,
+        };
+      });
+
+      return {
+        source: {
+          routesManifest: ".mandu/routes.manifest.json",
+          bundleManifest: includeBundle && bundleManifest ? ".mandu/manifest.json" : null,
+        },
+        includeBundle,
+        routeId: routeId ?? null,
+        routeCount: inspected.length,
+        boundaryCount: inspected.reduce((count, route) => count + route.boundaryCount, 0),
+        routes: inspected,
+      };
+    },
+
+    "mandu.route.add": async (args: Record<string, unknown>) => {
       const { path: routePath, kind, withSlot = true, withContract = false } = args as {
         path: string;
         kind: "api" | "page";
@@ -276,8 +405,8 @@ export function specTools(projectRoot: string) {
   };
 
   // Backward-compatible aliases (deprecated)
-  handlers["mandu_list_routes"] = handlers["mandu.route.list"];
-  handlers["mandu_get_route"] = handlers["mandu.route.get"];
+  handlers["mandu_list_routes"] = handlers["mandu.route.list"];
+  handlers["mandu_get_route"] = handlers["mandu.route.get"];
   handlers["mandu_add_route"] = handlers["mandu.route.add"];
   handlers["mandu_delete_route"] = handlers["mandu.route.delete"];
   handlers["mandu_validate_manifest"] = handlers["mandu.manifest.validate"];