@mandujs/mcp 0.18.8 → 0.18.10

package/src/tools/contract.ts

@@ -1,7 +1,6 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import {
   loadManifest,
-  writeLock,
   runContractGuardCheck,
   generateContractTemplate,
   generateOpenAPIDocument,
@@ -16,16 +15,12 @@ import fs from "fs/promises";
 
 export const contractToolDefinitions: Tool[] = [
   {
-    name: "mandu_list_contracts",
+    name: "mandu.contract.list",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "List all routes that have a contract module defined. " +
-      "In Mandu, a 'contract' is a Zod-based schema file (spec/contracts/{routeId}.contract.ts) that defines " +
-      "the request/response shape for an API route. Contracts enable: " +
-      "(1) automatic input validation and sanitization (strip/strict/passthrough normalize modes), " +
-      "(2) TypeScript type inference for slot handlers, " +
-      "(3) OpenAPI 3.0 spec generation via mandu_generate_openapi, " +
-      "(4) ATE L2 (schema validation) and L3 (full behavioral) test generation. " +
-      "Also returns a list of API routes that are missing contracts.",
+      "List routes with contract modules and API routes missing contracts.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -33,12 +28,12 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_get_contract",
+    name: "mandu.contract.get",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "Get the full TypeScript source of a contract file for a specific route. " +
-      "Returns the raw content of spec/contracts/{routeId}.contract.ts, " +
-      "which contains Zod schemas for each HTTP method's request body/query params and response shape. " +
-      "If the route has no contract, returns a suggestion to create one with mandu_create_contract.",
+      "Read the TypeScript source of a route's contract file.",
     inputSchema: {
       type: "object",
       properties: {
@@ -51,13 +46,13 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_create_contract",
+    name: "mandu.contract.create",
+    annotations: {
+      destructiveHint: false,
+      readOnlyHint: false,
+    },
     description:
-      "Create a new contract file for a route and link it in the manifest. " +
-      "Generates spec/contracts/{routeId}.contract.ts with Zod schema stubs for each HTTP method. " +
-      "Template includes: request schema (body for POST/PUT/PATCH, query for GET/DELETE) and response schema. " +
-      "After creation: edit the Zod schemas to match your actual API shape, " +
-      "then run mandu_generate to regenerate typed handlers with validation.",
+      "Create a new contract file with Zod schema stubs for a route and link it in the manifest.",
     inputSchema: {
       type: "object",
       properties: {
@@ -79,12 +74,12 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_update_route_contract",
+    name: "mandu.contract.link",
+    annotations: {
+      readOnlyHint: false,
+    },
     description:
-      "Update the manifest to link an existing contract file to a route. " +
-      "Use this when the contract file already exists but the manifest's contractModule path needs updating, " +
-      "or when moving a contract file to a new location. " +
-      "Does not modify the contract file itself — only updates the manifest reference and lock file.",
+      "Update the manifest to link an existing contract file to a route. Only changes the manifest reference.",
     inputSchema: {
       type: "object",
       properties: {
@@ -101,13 +96,12 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_validate_contracts",
+    name: "mandu.contract.validate",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "Validate all contracts against their linked slot implementations for consistency. " +
-      "Checks that every HTTP method defined in a contract has a matching handler in the slot, " +
-      "response types are compatible, and no orphaned contracts exist. " +
-      "Run this after modifying contracts or slots, or before running ATE tests to catch mismatches early. " +
-      "Returns a list of violations with file locations, descriptions, and fix suggestions.",
+      "Validate all contracts against their slot implementations for method and type consistency.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -115,15 +109,12 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_sync_contract_slot",
+    name: "mandu.contract.sync",
+    annotations: {
+      readOnlyHint: true,
+    },
     description:
-      "Detect and generate code to resolve HTTP method mismatches between a contract and its slot. " +
-      "'contract-to-slot': finds HTTP methods defined in the contract but missing from the slot — " +
-      "generates handler stub code to add to the slot file. " +
-      "'slot-to-contract': finds slot handlers not documented in the contract — " +
-      "generates Zod schema stubs to add to the contract. " +
-      "Returns generated code snippets to review — does NOT auto-write files. " +
-      "Copy the output and use the Edit tool to apply the changes.",
+      "Generate code snippets to resolve HTTP method mismatches between a contract and its slot. Does not write files.",
     inputSchema: {
       type: "object",
       properties: {
@@ -143,12 +134,12 @@ export const contractToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_generate_openapi",
+    name: "mandu.contract.openapi",
+    annotations: {
+      readOnlyHint: false,
+    },
     description:
-      "Generate an OpenAPI 3.0 specification JSON file from all routes with contract modules. " +
-      "Only routes with a defined contractModule are included — add contracts with mandu_create_contract first. " +
-      "Output is written to openapi.json (or a custom path). " +
-      "The generated spec can be served with Swagger UI, Redoc, or imported into any OpenAPI-compatible tooling.",
+      "Generate an OpenAPI 3.0 JSON spec from all routes with contract modules.",
     inputSchema: {
       type: "object",
       properties: {
@@ -190,8 +181,8 @@ async function readFileContent(filePath: string): Promise<string | null> {
 export function contractTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_list_contracts: async () => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.contract.list": async () => {
       const result = await loadManifest(paths.manifestPath);
       if (!result.success || !result.data) {
         return { error: result.errors };
@@ -217,7 +208,7 @@ export function contractTools(projectRoot: string) {
       };
     },
 
-    mandu_get_contract: async (args: Record<string, unknown>) => {
+    "mandu.contract.get": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
       const result = await loadManifest(paths.manifestPath);
@@ -234,7 +225,7 @@ export function contractTools(projectRoot: string) {
         return {
           routeId,
           hasContract: false,
-          suggestion: `Create a contract with: mandu_create_contract({ routeId: "${routeId}" })`,
+          suggestion: `Create a contract with: mandu.contract.create({ routeId: "${routeId}" })`,
         };
       }
 
@@ -258,7 +249,7 @@ export function contractTools(projectRoot: string) {
       };
     },
 
-    mandu_create_contract: async (args: Record<string, unknown>) => {
+    "mandu.contract.create": async (args: Record<string, unknown>) => {
       const { routeId, description, methods } = args as {
         routeId: string;
         description?: string;
@@ -311,7 +302,6 @@ export function contractTools(projectRoot: string) {
         };
 
         await writeJsonFile(paths.manifestPath, result.data);
-        await writeLock(paths.lockPath, result.data);
       }
 
       return {
@@ -320,13 +310,13 @@ export function contractTools(projectRoot: string) {
         message: `Contract created for route '${routeId}'`,
         nextSteps: [
           `Edit ${contractPath} to define your API schema`,
-          "Run mandu_generate to regenerate handlers with validation",
-          "Run mandu_validate_contracts to check consistency",
+          "Run mandu.generate to regenerate handlers with validation",
+          "Run mandu.contract.validate to check consistency",
         ],
       };
     },
 
-    mandu_update_route_contract: async (args: Record<string, unknown>) => {
+    "mandu.contract.link": async (args: Record<string, unknown>) => {
       const { routeId, contractModule } = args as {
         routeId: string;
         contractModule: string;
@@ -352,7 +342,6 @@ export function contractTools(projectRoot: string) {
 
       // Write updated manifest
       await writeJsonFile(paths.manifestPath, result.data);
-      await writeLock(paths.lockPath, result.data);
 
       return {
         success: true,
@@ -361,7 +350,7 @@ export function contractTools(projectRoot: string) {
       };
     },
 
-    mandu_validate_contracts: async () => {
+    "mandu.contract.validate": async () => {
       const result = await loadManifest(paths.manifestPath);
       if (!result.success || !result.data) {
         return { error: result.errors };
@@ -392,7 +381,7 @@ export function contractTools(projectRoot: string) {
       };
     },
 
-    mandu_sync_contract_slot: async (args: Record<string, unknown>) => {
+    "mandu.contract.sync": async (args: Record<string, unknown>) => {
       const { routeId, direction } = args as {
         routeId: string;
         direction: "contract-to-slot" | "slot-to-contract";
@@ -526,7 +515,7 @@ export function contractTools(projectRoot: string) {
       }
     },
 
-    mandu_generate_openapi: async (args: Record<string, unknown>) => {
+    "mandu.contract.openapi": async (args: Record<string, unknown>) => {
       const { output, title, version } = args as {
         output?: string;
         title?: string;
@@ -581,4 +570,15 @@ export function contractTools(projectRoot: string) {
       }
     },
   };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_list_contracts"] = handlers["mandu.contract.list"];
+  handlers["mandu_get_contract"] = handlers["mandu.contract.get"];
+  handlers["mandu_create_contract"] = handlers["mandu.contract.create"];
+  handlers["mandu_update_route_contract"] = handlers["mandu.contract.link"];
+  handlers["mandu_validate_contracts"] = handlers["mandu.contract.validate"];
+  handlers["mandu_sync_contract_slot"] = handlers["mandu.contract.sync"];
+  handlers["mandu_generate_openapi"] = handlers["mandu.contract.openapi"];
+
+  return handlers;
 }

package/src/tools/decisions.ts

@@ -0,0 +1,270 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  searchDecisions,
+  saveDecision,
+  checkConsistency,
+  getCompactArchitecture,
+  getNextDecisionId,
+  type ArchitectureDecision,
+  type DecisionStatus,
+} from "@mandujs/core";
+
+export const decisionToolDefinitions: Tool[] = [
+  {
+    name: "mandu.decision.list",
+    description:
+      "Search architecture decisions (ADRs) by tags. Use before implementing features for consistency.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags to search for (e.g., ['auth', 'cache', 'api'])",
+        },
+      },
+      required: ["tags"],
+    },
+  },
+  {
+    name: "mandu.decision.save",
+    description:
+      "Save a new architecture decision record (ADR) for future consistency checks.",
+    annotations: {
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Decision title (e.g., 'Use JWT for API Authentication')",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags for searchability (e.g., ['auth', 'api', 'security'])",
+        },
+        context: {
+          type: "string",
+          description: "Why this decision was needed",
+        },
+        decision: {
+          type: "string",
+          description: "What was decided",
+        },
+        consequences: {
+          type: "array",
+          items: { type: "string" },
+          description: "Impact and trade-offs of this decision",
+        },
+        status: {
+          type: "string",
+          enum: ["proposed", "accepted", "deprecated", "superseded"],
+          description: "Decision status (default: proposed)",
+        },
+      },
+      required: ["title", "tags", "context", "decision", "consequences"],
+    },
+  },
+  {
+    name: "mandu.decision.check",
+    description:
+      "Check if a proposed change conflicts with existing architecture decisions.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "string",
+          description: "What you're trying to do (e.g., 'Add Redis caching layer')",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Related tags to check against (e.g., ['cache', 'redis'])",
+        },
+      },
+      required: ["intent", "tags"],
+    },
+  },
+  {
+    name: "mandu.decision.architecture",
+    description:
+      "Get a compact summary of project architecture decisions and rules.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+export function decisionTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.decision.list": async (args: Record<string, unknown>) => {
+      const { tags } = args as { tags: string[] };
+
+      if (!tags || tags.length === 0) {
+        return {
+          error: "Tags are required",
+          tip: "Provide at least one tag to search for (e.g., ['auth', 'cache'])",
+        };
+      }
+
+      const result = await searchDecisions(projectRoot, tags);
+
+      if (result.decisions.length === 0) {
+        return {
+          found: false,
+          message: `No decisions found for tags: ${tags.join(", ")}`,
+          searchedTags: tags,
+          tip: "Try broader tags or check spec/decisions/ directory",
+        };
+      }
+
+      return {
+        found: true,
+        total: result.total,
+        searchedTags: tags,
+        decisions: result.decisions.map((d) => ({
+          id: d.id,
+          title: d.title,
+          status: d.status,
+          date: d.date,
+          tags: d.tags,
+          context: d.context.slice(0, 200) + (d.context.length > 200 ? "..." : ""),
+          decision: d.decision,
+          consequences: d.consequences,
+          relatedDecisions: d.relatedDecisions,
+        })),
+        tip: "Follow these decisions for consistency. Use mandu.decision.save if you make a new architectural choice.",
+      };
+    },
+
+    "mandu.decision.save": async (args: Record<string, unknown>) => {
+      const { title, tags, context, decision, consequences, status } = args as {
+        title: string;
+        tags: string[];
+        context: string;
+        decision: string;
+        consequences: string[];
+        status?: DecisionStatus;
+      };
+
+      // Validate required fields
+      if (!title || !tags || !context || !decision || !consequences) {
+        return {
+          error: "Missing required fields",
+          required: ["title", "tags", "context", "decision", "consequences"],
+        };
+      }
+
+      // Get next ID
+      const id = await getNextDecisionId(projectRoot);
+
+      // Save decision
+      const newDecision: Omit<ArchitectureDecision, "date"> = {
+        id,
+        title,
+        status: status || "proposed",
+        tags: tags.map((t) => t.toLowerCase()),
+        context,
+        decision,
+        consequences,
+      };
+
+      const result = await saveDecision(projectRoot, newDecision);
+
+      return {
+        success: result.success,
+        decision: {
+          id,
+          title,
+          status: status || "proposed",
+          tags,
+        },
+        filePath: result.filePath,
+        message: result.message,
+        tip: "Decision saved. It will be found when searching for related tags.",
+      };
+    },
+
+    "mandu.decision.check": async (args: Record<string, unknown>) => {
+      const { intent, tags } = args as {
+        intent: string;
+        tags: string[];
+      };
+
+      if (!intent || !tags || tags.length === 0) {
+        return {
+          error: "Intent and tags are required",
+          tip: "Describe what you're trying to do and provide related tags",
+        };
+      }
+
+      const result = await checkConsistency(projectRoot, intent, tags);
+
+      return {
+        consistent: result.consistent,
+        intent,
+        checkedTags: tags,
+        relatedDecisions: result.relatedDecisions.map((d) => ({
+          id: d.id,
+          title: d.title,
+          status: d.status,
+          decision: d.decision.slice(0, 150) + "...",
+        })),
+        warnings: result.warnings,
+        suggestions: result.suggestions,
+        tip: result.consistent
+          ? "No conflicts found. Proceed with implementation following the suggestions."
+          : "⚠️ Review warnings before proceeding. Some decisions may conflict.",
+      };
+    },
+
+    "mandu.decision.architecture": async () => {
+      const compact = await getCompactArchitecture(projectRoot);
+
+      if (!compact) {
+        return {
+          found: false,
+          message: "No architecture information found",
+          tip: "Save some decisions first using mandu.decision.save",
+        };
+      }
+
+      return {
+        found: true,
+        project: compact.project,
+        lastUpdated: compact.lastUpdated,
+        summary: {
+          totalDecisions: compact.keyDecisions.length,
+          topTags: Object.entries(compact.tagCounts)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 10)
+            .map(([tag, count]) => ({ tag, count })),
+        },
+        keyDecisions: compact.keyDecisions,
+        rules: compact.rules,
+        tip: "Use mandu.decision.list with specific tags for detailed information.",
+      };
+    },
+  };
+
+  // Backward-compatible aliases (deprecated)
+  handlers["mandu_get_decisions"] = handlers["mandu.decision.list"];
+  handlers["mandu_save_decision"] = handlers["mandu.decision.save"];
+  handlers["mandu_check_consistency"] = handlers["mandu.decision.check"];
+  handlers["mandu_get_architecture"] = handlers["mandu.decision.architecture"];
+
+  return handlers;
+}

package/src/tools/generate.ts

@@ -6,19 +6,15 @@ import fs from "fs/promises";
 
 export const generateToolDefinitions: Tool[] = [
   {
-    name: "mandu_generate",
+    name: "mandu.generate",
     description:
-      "Generate all Mandu framework artifacts from the current routes manifest and resource schemas. " +
-      "Runs two generation steps: " +
-      "(1) Route generation: for every route in .mandu/routes.manifest.json, creates " +
-      "a server-side handler in .mandu/generated/server/{routeId}.route.ts and " +
-      "a web component in .mandu/generated/web/{routeId}.route.tsx. " +
-      "These generated files wire up slots and contracts automatically — do NOT edit them directly. " +
-      "Instead, edit source files in app/ (route definition) or spec/ (slots, contracts). " +
-      "(2) Resource generation (resources=true, default): scans spec/resources/{name}/schema.ts " +
-      "and generates CRUD boilerplate (repository, service, handlers) for each declared resource. " +
-      "Run this after adding routes, modifying slot/contract files, or changing resource schemas. " +
-      "Use dryRun=true to preview what would be created or overwritten without writing any files.",
+      "Generate all framework artifacts (server handlers, web components, resources) from the manifest. " +
+      "Run after adding routes or modifying slots/contracts. Use dryRun=true to preview.",
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+      idempotentHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -35,12 +31,12 @@ export const generateToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu_generate_status",
+    name: "mandu.generate.status",
     description:
-      "Show the current state of all generated artifacts from .mandu/generated.map.json. " +
-      "Returns: generation timestamp, source spec version, total file count, " +
-      "and a list of generated files per route with their kinds (server handler, web component, slot stub). " +
-      "If no generated.map.json exists, prompts to run mandu_generate first.",
+      "Show the current state of all generated artifacts from .mandu/generated.map.json.",
+    annotations: {
+      readOnlyHint: true,
+    },
     inputSchema: {
       type: "object",
       properties: {},
@@ -52,8 +48,8 @@ export const generateToolDefinitions: Tool[] = [
 export function generateTools(projectRoot: string) {
   const paths = getProjectPaths(projectRoot);
 
-  return {
-    mandu_generate: async (args: Record<string, unknown>) => {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.generate": async (args: Record<string, unknown>) => {
       const { dryRun, resources = true } = args as { dryRun?: boolean; resources?: boolean };
 
       // Regenerate manifest from FS Routes first
@@ -166,14 +162,14 @@ export function generateTools(projectRoot: string) {
       };
     },
 
-    mandu_generate_status: async () => {
+    "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.",
+          message: "No generated.map.json found. Run mandu.generate first.",
         };
       }
 
@@ -197,4 +193,10 @@ export function generateTools(projectRoot: string) {
       };
     },
   };
+
+  // Backward-compatible aliases
+  handlers["mandu_generate"] = handlers["mandu.generate"];
+  handlers["mandu_generate_status"] = handlers["mandu.generate.status"];
+
+  return handlers;
 }