@mandujs/mcp 0.3.3

package/src/tools/guard.ts

@@ -0,0 +1,211 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadManifest,
+  runGuardCheck,
+  runAutoCorrect,
+  ErrorClassifier,
+  type ManduError,
+  type GeneratedMap,
+} from "@mandujs/core";
+import { getProjectPaths, readJsonFile } from "../utils/project.js";
+
+export const guardToolDefinitions: Tool[] = [
+  {
+    name: "mandu_guard_check",
+    description:
+      "Run guard checks to validate spec integrity, generated files, and slot files",
+    inputSchema: {
+      type: "object",
+      properties: {
+        autoCorrect: {
+          type: "boolean",
+          description: "If true, attempt to automatically fix violations",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu_analyze_error",
+    description:
+      "Analyze a ManduError JSON to provide actionable fix guidance",
+    inputSchema: {
+      type: "object",
+      properties: {
+        errorJson: {
+          type: "string",
+          description: "The ManduError JSON string to analyze",
+        },
+      },
+      required: ["errorJson"],
+    },
+  },
+];
+
+export function guardTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    mandu_guard_check: async (args: Record<string, unknown>) => {
+      const { autoCorrect = false } = args as { autoCorrect?: boolean };
+
+      // Load manifest
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return {
+          error: "Failed to load manifest",
+          details: manifestResult.errors,
+        };
+      }
+
+      // Run guard check
+      const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
+
+      if (checkResult.passed) {
+        return {
+          passed: true,
+          violations: [],
+          message: "All guard checks passed",
+        };
+      }
+
+      // If auto-correct requested and there are violations
+      if (autoCorrect && checkResult.violations.length > 0) {
+        const autoCorrectResult = await runAutoCorrect(
+          checkResult.violations,
+          manifestResult.data,
+          projectRoot
+        );
+
+        return {
+          passed: autoCorrectResult.fixed,
+          violations: autoCorrectResult.remainingViolations,
+          autoCorrect: {
+            attempted: true,
+            fixed: autoCorrectResult.fixed,
+            steps: autoCorrectResult.steps,
+            retriedCount: autoCorrectResult.retriedCount,
+            rolledBack: autoCorrectResult.rolledBack,
+            changeId: autoCorrectResult.changeId,
+          },
+        };
+      }
+
+      return {
+        passed: false,
+        violations: checkResult.violations.map((v) => ({
+          ruleId: v.ruleId,
+          file: v.file,
+          message: v.message,
+          suggestion: v.suggestion,
+        })),
+        message: `Found ${checkResult.violations.length} violation(s)`,
+        tip: "Use autoCorrect: true to attempt automatic fixes",
+      };
+    },
+
+    mandu_analyze_error: async (args: Record<string, unknown>) => {
+      const { errorJson } = args as { errorJson: string };
+
+      let error: ManduError;
+      try {
+        error = JSON.parse(errorJson) as ManduError;
+      } catch {
+        return {
+          error: "Invalid JSON format",
+          tip: "Provide a valid ManduError JSON string",
+        };
+      }
+
+      // Load generated map for better analysis
+      const generatedMap = await readJsonFile<GeneratedMap>(paths.generatedMapPath);
+
+      // Provide analysis based on error type
+      const analysis: Record<string, unknown> = {
+        errorType: error.errorType,
+        code: error.code,
+        summary: error.summary,
+      };
+
+      switch (error.errorType) {
+        case "SPEC_ERROR":
+          analysis.category = "Specification Error";
+          analysis.fixLocation = error.fix?.file || "spec/routes.manifest.json";
+          analysis.actions = [
+            "Check the spec file for JSON syntax errors",
+            "Validate route IDs are unique",
+            "Ensure patterns start with /",
+            "For page routes, verify componentModule is specified",
+          ];
+          break;
+
+        case "LOGIC_ERROR":
+          analysis.category = "Business Logic Error";
+          analysis.fixLocation = error.fix?.file || "spec/slots/";
+          analysis.actions = [
+            "Review the slot file at the specified location",
+            error.fix?.suggestion || "Check the handler logic",
+            "Verify ctx.body() and ctx.params are used correctly",
+            "Add proper error handling in the slot",
+          ];
+          if (error.fix?.line) {
+            analysis.lineNumber = error.fix.line;
+          }
+          break;
+
+        case "FRAMEWORK_BUG":
+          analysis.category = "Framework Internal Error";
+          analysis.fixLocation = error.fix?.file || "packages/core/";
+          analysis.actions = [
+            "This appears to be a framework bug",
+            "Check GitHub issues for similar problems",
+            "Consider filing a bug report with the error details",
+          ];
+          analysis.reportUrl = "https://github.com/konamgil/mandu/issues";
+          break;
+
+        default:
+          analysis.category = "Unknown Error";
+          analysis.actions = [
+            "Review the error message for details",
+            error.fix?.suggestion || "Check related files",
+          ];
+      }
+
+      // Add route context if available
+      if (error.route) {
+        analysis.routeContext = {
+          routeId: error.route.id,
+          pattern: error.route.pattern,
+          kind: error.route.kind,
+        };
+
+        // Try to find slot mapping
+        if (generatedMap && error.route.id) {
+          for (const [, entry] of Object.entries(generatedMap.files)) {
+            if (entry.routeId === error.route.id && entry.slotMapping) {
+              analysis.slotFile = entry.slotMapping.slotPath;
+              break;
+            }
+          }
+        }
+      }
+
+      // Add debug info if available
+      if (error.debug) {
+        analysis.debug = {
+          hasStack: !!error.debug.stack,
+          generatedFile: error.debug.generatedFile,
+        };
+      }
+
+      return {
+        analysis,
+        originalError: {
+          message: error.message,
+          timestamp: error.timestamp,
+        },
+      };
+    },
+  };
+}

package/src/tools/history.ts

@@ -0,0 +1,138 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  listChanges,
+  pruneHistory,
+  getChangeStats,
+  readSnapshotById,
+} from "@mandujs/core";
+
+export const historyToolDefinitions: Tool[] = [
+  {
+    name: "mandu_list_history",
+    description: "List the change history with snapshots",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Maximum number of entries to return (default: 10)",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu_get_snapshot",
+    description: "Get details of a specific snapshot",
+    inputSchema: {
+      type: "object",
+      properties: {
+        snapshotId: {
+          type: "string",
+          description: "The snapshot ID to retrieve",
+        },
+      },
+      required: ["snapshotId"],
+    },
+  },
+  {
+    name: "mandu_prune_history",
+    description: "Remove old snapshots to free up space",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keepCount: {
+          type: "number",
+          description: "Number of snapshots to keep (default: 5)",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function historyTools(projectRoot: string) {
+  return {
+    mandu_list_history: async (args: Record<string, unknown>) => {
+      const { limit = 10 } = args as { limit?: number };
+
+      const changes = await listChanges(projectRoot);
+      const stats = await getChangeStats(projectRoot);
+
+      // Sort by createdAt descending and limit
+      const sortedChanges = changes
+        .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
+        .slice(0, limit);
+
+      return {
+        changes: sortedChanges.map((c) => ({
+          id: c.id,
+          message: c.message,
+          status: c.status,
+          createdAt: c.createdAt,
+          snapshotId: c.snapshotId,
+          autoGenerated: c.autoGenerated,
+        })),
+        stats: {
+          total: stats.total,
+          active: stats.active,
+          committed: stats.committed,
+          rolledBack: stats.rolledBack,
+          snapshotCount: stats.snapshotCount,
+        },
+      };
+    },
+
+    mandu_get_snapshot: async (args: Record<string, unknown>) => {
+      const { snapshotId } = args as { snapshotId: string };
+
+      const snapshot = await readSnapshotById(projectRoot, snapshotId);
+      if (!snapshot) {
+        return { error: `Snapshot not found: ${snapshotId}` };
+      }
+
+      const slotFiles = Object.keys(snapshot.slotContents);
+
+      return {
+        id: snapshot.id,
+        timestamp: snapshot.timestamp,
+        manifest: {
+          version: snapshot.manifest.version,
+          routeCount: snapshot.manifest.routes.length,
+          routes: snapshot.manifest.routes.map((r) => ({
+            id: r.id,
+            pattern: r.pattern,
+            kind: r.kind,
+          })),
+        },
+        hasLock: !!snapshot.lock,
+        lock: snapshot.lock
+          ? {
+              routesHash: snapshot.lock.routesHash,
+              updatedAt: snapshot.lock.updatedAt,
+            }
+          : null,
+        slotFiles,
+        slotCount: slotFiles.length,
+      };
+    },
+
+    mandu_prune_history: async (args: Record<string, unknown>) => {
+      const { keepCount = 5 } = args as { keepCount?: number };
+
+      const deletedIds = await pruneHistory(projectRoot, keepCount);
+
+      const stats = await getChangeStats(projectRoot);
+
+      return {
+        success: true,
+        deletedCount: deletedIds.length,
+        deletedIds,
+        remaining: {
+          snapshotCount: stats.snapshotCount,
+          changeCount: stats.total,
+        },
+      };
+    },
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,6 @@
+export { specTools, specToolDefinitions } from "./spec.js";
+export { generateTools, generateToolDefinitions } from "./generate.js";
+export { transactionTools, transactionToolDefinitions } from "./transaction.js";
+export { historyTools, historyToolDefinitions } from "./history.js";
+export { guardTools, guardToolDefinitions } from "./guard.js";
+export { slotTools, slotToolDefinitions } from "./slot.js";

package/src/tools/slot.ts

@@ -0,0 +1,166 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { loadManifest } from "@mandujs/core";
+import { getProjectPaths, isInsideProject } from "../utils/project.js";
+import path from "path";
+import fs from "fs/promises";
+
+export const slotToolDefinitions: Tool[] = [
+  {
+    name: "mandu_read_slot",
+    description: "Read the contents of a slot file for a specific route",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID whose slot file to read",
+        },
+      },
+      required: ["routeId"],
+    },
+  },
+  {
+    name: "mandu_write_slot",
+    description: "Write or update the contents of a slot file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routeId: {
+          type: "string",
+          description: "The route ID whose slot file to write",
+        },
+        content: {
+          type: "string",
+          description: "The TypeScript content to write to the slot file",
+        },
+      },
+      required: ["routeId", "content"],
+    },
+  },
+];
+
+export function slotTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    mandu_read_slot: async (args: Record<string, unknown>) => {
+      const { routeId } = args as { routeId: string };
+
+      // Load manifest to find the route
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+
+      const route = manifestResult.data.routes.find((r) => r.id === routeId);
+      if (!route) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      if (!route.slotModule) {
+        return {
+          error: `Route '${routeId}' does not have a slotModule defined`,
+          tip: "Add slotModule to the route spec or use mandu_update_route",
+        };
+      }
+
+      const slotPath = path.join(projectRoot, route.slotModule);
+
+      // Security check
+      if (!isInsideProject(slotPath, projectRoot)) {
+        return { error: "Slot path is outside project directory" };
+      }
+
+      try {
+        const file = Bun.file(slotPath);
+        if (!(await file.exists())) {
+          return {
+            exists: false,
+            slotPath: route.slotModule,
+            message: "Slot file does not exist. Run mandu_generate to create it.",
+          };
+        }
+
+        const content = await file.text();
+        return {
+          exists: true,
+          slotPath: route.slotModule,
+          content,
+          lineCount: content.split("\n").length,
+        };
+      } catch (error) {
+        return {
+          error: `Failed to read slot file: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    },
+
+    mandu_write_slot: async (args: Record<string, unknown>) => {
+      const { routeId, content } = args as { routeId: string; content: string };
+
+      // Load manifest to find the route
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+
+      const route = manifestResult.data.routes.find((r) => r.id === routeId);
+      if (!route) {
+        return { error: `Route not found: ${routeId}` };
+      }
+
+      if (!route.slotModule) {
+        return {
+          error: `Route '${routeId}' does not have a slotModule defined`,
+          tip: "Add slotModule to the route spec first",
+        };
+      }
+
+      const slotPath = path.join(projectRoot, route.slotModule);
+
+      // Security check
+      if (!isInsideProject(slotPath, projectRoot)) {
+        return { error: "Slot path is outside project directory" };
+      }
+
+      // Basic validation - check for Mandu.filling() pattern
+      if (!content.includes("Mandu") && !content.includes("filling")) {
+        return {
+          warning: "Slot content doesn't appear to use Mandu.filling() pattern",
+          tip: "Slot files should export a default using Mandu.filling()",
+          proceeding: true,
+        };
+      }
+
+      try {
+        // Ensure directory exists
+        const slotDir = path.dirname(slotPath);
+        await fs.mkdir(slotDir, { recursive: true });
+
+        // Check if file exists (for backup/warning)
+        const file = Bun.file(slotPath);
+        const existed = await file.exists();
+        let previousContent: string | null = null;
+
+        if (existed) {
+          previousContent = await file.text();
+        }
+
+        // Write the new content
+        await Bun.write(slotPath, content);
+
+        return {
+          success: true,
+          slotPath: route.slotModule,
+          action: existed ? "updated" : "created",
+          lineCount: content.split("\n").length,
+          previousLineCount: previousContent ? previousContent.split("\n").length : null,
+        };
+      } catch (error) {
+        return {
+          error: `Failed to write slot file: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    },
+  };
+}