@mandujs/mcp 0.3.3

package/src/tools/spec.ts

@@ -0,0 +1,322 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadManifest,
+  validateManifest,
+  writeLock,
+  type RouteSpec,
+  type RoutesManifest,
+} from "@mandujs/core";
+import { getProjectPaths, readJsonFile, writeJsonFile } from "../utils/project.js";
+import path from "path";
+
+export const specToolDefinitions: Tool[] = [
+  {
+    name: "mandu_list_routes",
+    description: "List all routes in the current Mandu project",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "mandu_get_route",
+    description: "Get details of a specific route by ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to retrieve",
+        },
+      },
+      required: ["routeId"],
+    },
+  },
+  {
+    name: "mandu_add_route",
+    description: "Add a new route to the manifest",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique route identifier",
+        },
+        pattern: {
+          type: "string",
+          description: "URL pattern (e.g., /api/users/:id)",
+        },
+        kind: {
+          type: "string",
+          enum: ["api", "page"],
+          description: "Route type: api or page",
+        },
+        slotModule: {
+          type: "string",
+          description: "Path to slot file (optional)",
+        },
+        componentModule: {
+          type: "string",
+          description: "Path to component module (required for page kind)",
+        },
+      },
+      required: ["id", "pattern", "kind"],
+    },
+  },
+  {
+    name: "mandu_update_route",
+    description: "Update an existing route",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to update",
+        },
+        updates: {
+          type: "object",
+          description: "Partial route updates",
+          properties: {
+            pattern: { type: "string" },
+            kind: { type: "string", enum: ["api", "page"] },
+            slotModule: { type: "string" },
+            componentModule: { type: "string" },
+          },
+        },
+      },
+      required: ["routeId", "updates"],
+    },
+  },
+  {
+    name: "mandu_delete_route",
+    description: "Delete a route from the manifest",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID to delete",
+        },
+      },
+      required: ["routeId"],
+    },
+  },
+  {
+    name: "mandu_validate_spec",
+    description: "Validate the current spec manifest",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+export function specTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    mandu_list_routes: async () => {
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      return {
+        version: result.data.version,
+        routes: result.data.routes.map((r) => ({
+          id: r.id,
+          pattern: r.pattern,
+          kind: r.kind,
+          slotModule: r.slotModule,
+          componentModule: r.componentModule,
+        })),
+        count: result.data.routes.length,
+      };
+    },
+
+    mandu_get_route: async (args: Record<string, unknown>) => {
+      const { routeId } = args as { routeId: string };
+
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      const route = result.data.routes.find((r) => r.id === routeId);
+      if (!route) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      return { route };
+    },
+
+    mandu_add_route: async (args: Record<string, unknown>) => {
+      const { id, pattern, kind, slotModule, componentModule } = args as {
+        id: string;
+        pattern: string;
+        kind: "api" | "page";
+        slotModule?: string;
+        componentModule?: string;
+      };
+
+      // Load current manifest
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      // Check for duplicate
+      if (result.data.routes.some((r) => r.id === id)) {
+        return { error: `Route with id '${id}' already exists` };
+      }
+
+      if (result.data.routes.some((r) => r.pattern === pattern)) {
+        return { error: `Route with pattern '${pattern}' already exists` };
+      }
+
+      // Build new route
+      const newRoute: RouteSpec = {
+        id,
+        pattern,
+        kind,
+        module: `apps/server/generated/routes/${id}.route.ts`,
+        slotModule: slotModule || `spec/slots/${id}.slot.ts`,
+      };
+
+      if (kind === "page") {
+        newRoute.componentModule = componentModule || `apps/web/generated/routes/${id}.route.tsx`;
+      }
+
+      // Validate new route
+      const newManifest: RoutesManifest = {
+        version: result.data.version,
+        routes: [...result.data.routes, newRoute],
+      };
+
+      const validation = validateManifest(newManifest);
+      if (!validation.success) {
+        return { error: validation.errors };
+      }
+
+      // Write updated manifest
+      await writeJsonFile(paths.manifestPath, newManifest);
+
+      // Update lock file
+      await writeLock(paths.lockPath, newManifest);
+
+      return {
+        success: true,
+        route: newRoute,
+        message: `Route '${id}' added successfully`,
+      };
+    },
+
+    mandu_update_route: async (args: Record<string, unknown>) => {
+      const { routeId, updates } = args as {
+        routeId: string;
+        updates: Partial<RouteSpec>;
+      };
+
+      // Load current manifest
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      // Find route
+      const routeIndex = result.data.routes.findIndex((r) => r.id === routeId);
+      if (routeIndex === -1) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      // Apply updates
+      const updatedRoute = {
+        ...result.data.routes[routeIndex],
+        ...updates,
+        id: routeId, // ID cannot be changed
+      };
+
+      const newRoutes = [...result.data.routes];
+      newRoutes[routeIndex] = updatedRoute as RouteSpec;
+
+      // Validate
+      const newManifest: RoutesManifest = {
+        version: result.data.version,
+        routes: newRoutes,
+      };
+
+      const validation = validateManifest(newManifest);
+      if (!validation.success) {
+        return { error: validation.errors };
+      }
+
+      // Write updated manifest
+      await writeJsonFile(paths.manifestPath, newManifest);
+
+      // Update lock file
+      await writeLock(paths.lockPath, newManifest);
+
+      return {
+        success: true,
+        route: updatedRoute,
+        message: `Route '${routeId}' updated successfully`,
+      };
+    },
+
+    mandu_delete_route: async (args: Record<string, unknown>) => {
+      const { routeId } = args as { routeId: string };
+
+      // Load current manifest
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return { error: result.errors };
+      }
+
+      // Find route
+      const routeIndex = result.data.routes.findIndex((r) => r.id === routeId);
+      if (routeIndex === -1) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      const deletedRoute = result.data.routes[routeIndex];
+
+      // Remove route
+      const newRoutes = result.data.routes.filter((r) => r.id !== routeId);
+
+      const newManifest: RoutesManifest = {
+        version: result.data.version,
+        routes: newRoutes,
+      };
+
+      // Write updated manifest
+      await writeJsonFile(paths.manifestPath, newManifest);
+
+      // Update lock file
+      await writeLock(paths.lockPath, newManifest);
+
+      return {
+        success: true,
+        deletedRoute,
+        message: `Route '${routeId}' deleted successfully`,
+      };
+    },
+
+    mandu_validate_spec: async () => {
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success) {
+        return {
+          valid: false,
+          errors: result.errors,
+        };
+      }
+
+      return {
+        valid: true,
+        routeCount: result.data?.routes.length || 0,
+        version: result.data?.version,
+      };
+    },
+  };
+}

package/src/tools/transaction.ts

@@ -0,0 +1,154 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  beginChange,
+  commitChange,
+  rollbackChange,
+  getTransactionStatus,
+  hasActiveTransaction,
+} from "@mandujs/core";
+
+export const transactionToolDefinitions: Tool[] = [
+  {
+    name: "mandu_begin",
+    description:
+      "Begin a new transaction. Creates a snapshot of the current spec state for safe rollback.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: {
+          type: "string",
+          description: "Description of the changes being made",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu_commit",
+    description: "Commit the current transaction, finalizing all changes",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "mandu_rollback",
+    description: "Rollback the current transaction, restoring the previous state",
+    inputSchema: {
+      type: "object",
+      properties: {
+        changeId: {
+          type: "string",
+          description: "Specific change ID to rollback (optional, defaults to active transaction)",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu_tx_status",
+    description: "Get the current transaction status",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+export function transactionTools(projectRoot: string) {
+  return {
+    mandu_begin: async (args: Record<string, unknown>) => {
+      const { message } = args as { message?: string };
+
+      // Check if there's already an active transaction
+      const isActive = await hasActiveTransaction(projectRoot);
+      if (isActive) {
+        const status = await getTransactionStatus(projectRoot);
+        return {
+          error: "Active transaction already exists",
+          activeTransaction: status.change,
+        };
+      }
+
+      const change = await beginChange(projectRoot, {
+        message: message || "MCP transaction",
+      });
+
+      return {
+        success: true,
+        changeId: change.id,
+        snapshotId: change.snapshotId,
+        message: change.message,
+        createdAt: change.createdAt,
+        tip: "Use mandu_commit to finalize or mandu_rollback to revert changes",
+      };
+    },
+
+    mandu_commit: async () => {
+      const isActive = await hasActiveTransaction(projectRoot);
+      if (!isActive) {
+        return {
+          error: "No active transaction to commit",
+        };
+      }
+
+      const result = await commitChange(projectRoot);
+
+      return {
+        success: result.success,
+        changeId: result.changeId,
+        message: result.message,
+      };
+    },
+
+    mandu_rollback: async (args: Record<string, unknown>) => {
+      const { changeId } = args as { changeId?: string };
+
+      const isActive = await hasActiveTransaction(projectRoot);
+      if (!isActive && !changeId) {
+        return {
+          error: "No active transaction to rollback. Provide a changeId to rollback a specific change.",
+        };
+      }
+
+      const result = await rollbackChange(projectRoot, changeId);
+
+      return {
+        success: result.success,
+        changeId: result.changeId,
+        restored: {
+          filesRestored: result.restoreResult.restoredFiles.length,
+          filesFailed: result.restoreResult.failedFiles.length,
+          errors: result.restoreResult.errors,
+        },
+      };
+    },
+
+    mandu_tx_status: async () => {
+      const { state, change } = await getTransactionStatus(projectRoot);
+
+      if (!state.active) {
+        return {
+          hasActiveTransaction: false,
+          message: "No active transaction",
+        };
+      }
+
+      return {
+        hasActiveTransaction: true,
+        changeId: state.changeId,
+        snapshotId: state.snapshotId,
+        change: change
+          ? {
+              id: change.id,
+              message: change.message,
+              status: change.status,
+              createdAt: change.createdAt,
+            }
+          : null,
+      };
+    },
+  };
+}

package/src/utils/project.ts

@@ -0,0 +1,71 @@
+import path from "path";
+import fs from "fs/promises";
+
+/**
+ * Find the Mandu project root by looking for routes.manifest.json
+ */
+export async function findProjectRoot(startDir: string = process.cwd()): Promise<string | null> {
+  let currentDir = path.resolve(startDir);
+
+  while (currentDir !== path.dirname(currentDir)) {
+    const manifestPath = path.join(currentDir, "spec", "routes.manifest.json");
+    try {
+      await fs.access(manifestPath);
+      return currentDir;
+    } catch {
+      currentDir = path.dirname(currentDir);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get standard paths for a Mandu project
+ */
+export function getProjectPaths(rootDir: string) {
+  return {
+    root: rootDir,
+    specDir: path.join(rootDir, "spec"),
+    manifestPath: path.join(rootDir, "spec", "routes.manifest.json"),
+    lockPath: path.join(rootDir, "spec", "spec.lock.json"),
+    slotsDir: path.join(rootDir, "spec", "slots"),
+    historyDir: path.join(rootDir, "spec", "history"),
+    generatedMapPath: path.join(rootDir, "packages", "core", "map", "generated.map.json"),
+    serverRoutesDir: path.join(rootDir, "apps", "server", "generated", "routes"),
+    webRoutesDir: path.join(rootDir, "apps", "web", "generated", "routes"),
+  };
+}
+
+/**
+ * Check if a path is inside the project
+ */
+export function isInsideProject(filePath: string, rootDir: string): boolean {
+  const resolved = path.resolve(filePath);
+  const root = path.resolve(rootDir);
+  return resolved.startsWith(root);
+}
+
+/**
+ * Read JSON file safely
+ */
+export async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return null;
+    }
+    return await file.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON file safely
+ */
+export async function writeJsonFile(filePath: string, data: unknown): Promise<void> {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  await Bun.write(filePath, JSON.stringify(data, null, 2));
+}