@mandujs/mcp 0.3.3

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mandujs/mcp",
+  "version": "0.3.3",
+  "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "mandu-mcp": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "keywords": [
+    "mandu",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/mcp"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mandujs/core": "^0.3.3",
+    "@modelcontextprotocol/sdk": "^1.25.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+import { startServer } from "./server.js";
+
+// Start the MCP server
+startServer().catch((error) => {
+  console.error("Failed to start Mandu MCP server:", error);
+  process.exit(1);
+});

package/src/resources/handlers.ts

@@ -0,0 +1,176 @@
+import type { Resource } from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadManifest,
+  getTransactionStatus,
+  type GeneratedMap,
+  type SpecLock,
+} from "@mandujs/core";
+import { getProjectPaths, readJsonFile } from "../utils/project.js";
+import path from "path";
+
+export const resourceDefinitions: Resource[] = [
+  {
+    uri: "mandu://spec/manifest",
+    name: "Routes Manifest",
+    description: "Current routes.manifest.json content",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://spec/lock",
+    name: "Spec Lock",
+    description: "Current spec.lock.json with hash verification",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://generated/map",
+    name: "Generated Map",
+    description: "Map of generated files to their source routes",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://transaction/active",
+    name: "Active Transaction",
+    description: "Current active transaction information",
+    mimeType: "application/json",
+  },
+  {
+    uri: "mandu://slots/{routeId}",
+    name: "Route Slot",
+    description: "Slot file content for a specific route",
+    mimeType: "text/typescript",
+  },
+];
+
+type ResourceHandler = (params: Record<string, string>) => Promise<unknown>;
+
+export function resourceHandlers(
+  projectRoot: string
+): Record<string, ResourceHandler> {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    "mandu://spec/manifest": async () => {
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return {
+          error: "Failed to load manifest",
+          details: result.errors,
+        };
+      }
+
+      return {
+        version: result.data.version,
+        routeCount: result.data.routes.length,
+        routes: result.data.routes,
+      };
+    },
+
+    "mandu://spec/lock": async () => {
+      const lock = await readJsonFile<SpecLock>(paths.lockPath);
+      if (!lock) {
+        return {
+          exists: false,
+          message: "spec.lock.json not found",
+        };
+      }
+
+      return {
+        exists: true,
+        routesHash: lock.routesHash,
+        updatedAt: lock.updatedAt,
+      };
+    },
+
+    "mandu://generated/map": async () => {
+      const generatedMap = await readJsonFile<GeneratedMap>(paths.generatedMapPath);
+      if (!generatedMap) {
+        return {
+          exists: false,
+          message: "generated.map.json not found. Run mandu generate first.",
+        };
+      }
+
+      return {
+        exists: true,
+        version: generatedMap.version,
+        generatedAt: generatedMap.generatedAt,
+        specSource: generatedMap.specSource,
+        fileCount: Object.keys(generatedMap.files).length,
+        files: generatedMap.files,
+        frameworkPaths: generatedMap.frameworkPaths,
+      };
+    },
+
+    "mandu://transaction/active": async () => {
+      const { state, change } = await getTransactionStatus(projectRoot);
+
+      if (!state.active) {
+        return {
+          hasActive: false,
+          message: "No active transaction",
+        };
+      }
+
+      return {
+        hasActive: true,
+        changeId: state.changeId,
+        snapshotId: state.snapshotId,
+        change: change
+          ? {
+              id: change.id,
+              message: change.message,
+              status: change.status,
+              createdAt: change.createdAt,
+              autoGenerated: change.autoGenerated,
+            }
+          : null,
+      };
+    },
+
+    "mandu://slots/{routeId}": async (params: Record<string, string>) => {
+      const { routeId } = params;
+
+      if (!routeId) {
+        return { error: "routeId parameter is required" };
+      }
+
+      // Load manifest to find the route
+      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}` };
+      }
+
+      if (!route.slotModule) {
+        return {
+          error: `Route '${routeId}' does not have a slotModule`,
+        };
+      }
+
+      const slotPath = path.join(projectRoot, route.slotModule);
+      const file = Bun.file(slotPath);
+
+      if (!(await file.exists())) {
+        return {
+          exists: false,
+          slotModule: route.slotModule,
+          message: "Slot file does not exist",
+        };
+      }
+
+      const content = await file.text();
+      return {
+        exists: true,
+        slotModule: route.slotModule,
+        routeId,
+        kind: route.kind,
+        pattern: route.pattern,
+        content,
+      };
+    },
+  };
+}

package/src/resources/index.ts

@@ -0,0 +1 @@
+export { resourceHandlers, resourceDefinitions } from "./handlers.js";

package/src/server.ts

@@ -0,0 +1,232 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  type Tool,
+  type Resource,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { specTools, specToolDefinitions } from "./tools/spec.js";
+import { generateTools, generateToolDefinitions } from "./tools/generate.js";
+import { transactionTools, transactionToolDefinitions } from "./tools/transaction.js";
+import { historyTools, historyToolDefinitions } from "./tools/history.js";
+import { guardTools, guardToolDefinitions } from "./tools/guard.js";
+import { slotTools, slotToolDefinitions } from "./tools/slot.js";
+import { resourceHandlers, resourceDefinitions } from "./resources/handlers.js";
+import { findProjectRoot } from "./utils/project.js";
+
+export class ManduMcpServer {
+  private server: Server;
+  private projectRoot: string;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+    this.server = new Server(
+      {
+        name: "mandu-mcp",
+        version: "0.1.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+        },
+      }
+    );
+
+    this.registerToolHandlers();
+    this.registerResourceHandlers();
+  }
+
+  private getAllToolDefinitions(): Tool[] {
+    return [
+      ...specToolDefinitions,
+      ...generateToolDefinitions,
+      ...transactionToolDefinitions,
+      ...historyToolDefinitions,
+      ...guardToolDefinitions,
+      ...slotToolDefinitions,
+    ];
+  }
+
+  private getAllToolHandlers(): Record<string, (args: Record<string, unknown>) => Promise<unknown>> {
+    return {
+      ...specTools(this.projectRoot),
+      ...generateTools(this.projectRoot),
+      ...transactionTools(this.projectRoot),
+      ...historyTools(this.projectRoot),
+      ...guardTools(this.projectRoot),
+      ...slotTools(this.projectRoot),
+    };
+  }
+
+  private registerToolHandlers(): void {
+    const toolHandlers = this.getAllToolHandlers();
+
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: this.getAllToolDefinitions(),
+      };
+    });
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      const handler = toolHandlers[name];
+      if (!handler) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Unknown tool: ${name}` }),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        const result = await handler(args || {});
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+              }),
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  private registerResourceHandlers(): void {
+    const handlers = resourceHandlers(this.projectRoot);
+
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: resourceDefinitions,
+      };
+    });
+
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+
+      const handler = handlers[uri];
+      if (!handler) {
+        // Try pattern matching for dynamic resources
+        for (const [pattern, h] of Object.entries(handlers)) {
+          if (pattern.includes("{") && matchResourcePattern(pattern, uri)) {
+            const params = extractResourceParams(pattern, uri);
+            const result = await h(params);
+            return {
+              contents: [
+                {
+                  uri,
+                  mimeType: "application/json",
+                  text: JSON.stringify(result, null, 2),
+                },
+              ],
+            };
+          }
+        }
+
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify({ error: `Unknown resource: ${uri}` }),
+            },
+          ],
+        };
+      }
+
+      try {
+        const result = await handler({});
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+              }),
+            },
+          ],
+        };
+      }
+    });
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error(`Mandu MCP Server running for project: ${this.projectRoot}`);
+  }
+}
+
+/**
+ * Match a resource pattern like "mandu://slots/{routeId}" against a URI
+ */
+function matchResourcePattern(pattern: string, uri: string): boolean {
+  const regexPattern = pattern.replace(/\{[^}]+\}/g, "([^/]+)");
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(uri);
+}
+
+/**
+ * Extract parameters from a URI based on a pattern
+ */
+function extractResourceParams(pattern: string, uri: string): Record<string, string> {
+  const paramNames: string[] = [];
+  const regexPattern = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+
+  const regex = new RegExp(`^${regexPattern}$`);
+  const match = uri.match(regex);
+
+  if (!match) return {};
+
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, index) => {
+    params[name] = match[index + 1];
+  });
+
+  return params;
+}
+
+/**
+ * Create and start the MCP server
+ */
+export async function startServer(projectRoot?: string): Promise<void> {
+  const root = projectRoot || (await findProjectRoot()) || process.cwd();
+  const server = new ManduMcpServer(root);
+  await server.run();
+}

package/src/tools/generate.ts

@@ -0,0 +1,127 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { loadManifest, generateRoutes, type GeneratedMap } from "@mandujs/core";
+import { getProjectPaths, readJsonFile } from "../utils/project.js";
+
+export const generateToolDefinitions: Tool[] = [
+  {
+    name: "mandu_generate",
+    description:
+      "Generate route handlers and components from the spec manifest. Creates server handlers, page components, and slot files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description: "If true, show what would be generated without writing files",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu_generate_status",
+    description: "Get the current generation status and generated file map",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+export function generateTools(projectRoot: string) {
+  const paths = getProjectPaths(projectRoot);
+
+  return {
+    mandu_generate: async (args: Record<string, unknown>) => {
+      const { dryRun } = args as { dryRun?: boolean };
+
+      // Load manifest
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+
+      if (dryRun) {
+        // Dry run - just show what would be generated
+        const routes = manifestResult.data.routes;
+        const wouldCreate: string[] = [];
+        const wouldSkip: string[] = [];
+
+        for (const route of routes) {
+          // Server handler
+          wouldCreate.push(`apps/server/generated/routes/${route.id}.route.ts`);
+
+          // Page component (for page kind)
+          if (route.kind === "page") {
+            wouldCreate.push(`apps/web/generated/routes/${route.id}.route.tsx`);
+          }
+
+          // Slot file (only if not exists)
+          if (route.slotModule) {
+            const slotFile = Bun.file(`${projectRoot}/${route.slotModule}`);
+            if (await slotFile.exists()) {
+              wouldSkip.push(route.slotModule);
+            } else {
+              wouldCreate.push(route.slotModule);
+            }
+          }
+        }
+
+        return {
+          dryRun: true,
+          wouldCreate,
+          wouldSkip,
+          routeCount: routes.length,
+        };
+      }
+
+      // Actually generate
+      const result = await generateRoutes(manifestResult.data, projectRoot);
+
+      return {
+        success: result.success,
+        created: result.created,
+        deleted: result.deleted,
+        skipped: result.skipped,
+        errors: result.errors,
+        summary: {
+          createdCount: result.created.length,
+          deletedCount: result.deleted.length,
+          skippedCount: result.skipped.length,
+        },
+      };
+    },
+
+    mandu_generate_status: async () => {
+      // Read generated map
+      const generatedMap = await readJsonFile<GeneratedMap>(paths.generatedMapPath);
+
+      if (!generatedMap) {
+        return {
+          hasGeneratedFiles: false,
+          message: "No generated.map.json found. Run mandu_generate first.",
+        };
+      }
+
+      const fileCount = Object.keys(generatedMap.files).length;
+      const routeIds = Object.values(generatedMap.files).map((f) => f.routeId);
+      const uniqueRoutes = [...new Set(routeIds)];
+
+      return {
+        hasGeneratedFiles: true,
+        version: generatedMap.version,
+        generatedAt: generatedMap.generatedAt,
+        specSource: generatedMap.specSource,
+        fileCount,
+        routeCount: uniqueRoutes.length,
+        files: Object.entries(generatedMap.files).map(([path, info]) => ({
+          path,
+          routeId: info.routeId,
+          kind: info.kind,
+          hasSlot: !!info.slotMapping,
+        })),
+      };
+    },
+  };
+}