@stackwright-pro/mcp 0.2.0-alpha.12 → 0.2.0-alpha.14

package/dist/server.mjs

@@ -3,15 +3,44 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/tools/data-explorer.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 import { listEntities, generateFilter } from "@stackwright-pro/cli-data-explorer";
+
+// src/coerce.ts
+import { z } from "zod";
+function jsonCoerce(schema) {
+  return z.preprocess((v) => {
+    if (typeof v === "string") {
+      try {
+        return JSON.parse(v);
+      } catch {
+        return v;
+      }
+    }
+    return v;
+  }, schema);
+}
+function boolCoerce(schema) {
+  return z.preprocess((v) => v === "true" ? true : v === "false" ? false : v, schema);
+}
+function numCoerce(schema) {
+  return z.preprocess((v) => {
+    if (typeof v === "string" && v.trim() !== "") {
+      const n = Number(v);
+      if (!Number.isNaN(n)) return n;
+    }
+    return v;
+  }, schema);
+}
+
+// src/tools/data-explorer.ts
 function registerDataExplorerTools(server2) {
   server2.tool(
     "stackwright_pro_list_entities",
     "List all available API entities from OpenAPI specs or generated Zod schemas. Use this to discover what entities are available before generating endpoint filters. Returns entity names, endpoints, and field counts. Part of the Pro Otter Raft for building API-integrated Stackwright applications.",
     {
-      specPath: z.string().optional().describe("Path to OpenAPI spec file (YAML or JSON)"),
-      projectRoot: z.string().optional().describe("Project root directory (auto-detected if omitted)")
+      specPath: z2.string().optional().describe("Path to OpenAPI spec file (YAML or JSON)"),
+      projectRoot: z2.string().optional().describe("Project root directory (auto-detected if omitted)")
     },
     async ({ specPath, projectRoot }) => {
       const result = listEntities({
@@ -59,9 +88,13 @@ function registerDataExplorerTools(server2) {
     "stackwright_pro_generate_filter",
     "Generate endpoint filter configuration from selected entities. Creates include/exclude patterns for stackwright.yml OpenAPI integration. Use this after stackwright_pro_list_entities to select which API endpoints the application needs. Only selected endpoints will generate client code, reducing bundle size and improving security.",
     {
-      selectedEntities: z.array(z.string()).describe('Entity slugs to include (e.g., ["equipment", "supplies"])'),
-      excludePatterns: z.array(z.string()).optional().describe('Glob patterns to exclude (e.g., ["/admin/**", "/reports/**"])'),
-      projectRoot: z.string().optional().describe("Project root directory")
+      selectedEntities: jsonCoerce(z2.array(z2.string())).describe(
+        'Entity slugs to include (e.g., ["equipment", "supplies"])'
+      ),
+      excludePatterns: jsonCoerce(z2.array(z2.string()).optional()).describe(
+        'Glob patterns to exclude (e.g., ["/admin/**", "/reports/**"])'
+      ),
+      projectRoot: z2.string().optional().describe("Project root directory")
     },
     async ({ selectedEntities, excludePatterns, projectRoot }) => {
       const result = generateFilter({
@@ -117,7 +150,7 @@ function registerDataExplorerTools(server2) {
 }
 
 // src/tools/security.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 import { createHash } from "crypto";
 import fs from "fs";
 import path from "path";
@@ -126,8 +159,8 @@ function registerSecurityTools(server2) {
     "stackwright_pro_validate_spec",
     "Validate an OpenAPI spec against the enterprise approved-specs configuration. Checks if the spec URL is on the allowlist and verifies SHA-256 hash integrity. Use this in enterprise environments where only pre-approved API specs are allowed. Fails build if spec is not approved or has been modified.",
     {
-      specPath: z2.string().describe("URL or file path to the OpenAPI spec to validate"),
-      configPath: z2.string().optional().describe("Path to stackwright.yml with prebuild.security config")
+      specPath: z3.string().describe("URL or file path to the OpenAPI spec to validate"),
+      configPath: z3.string().optional().describe("Path to stackwright.yml with prebuild.security config")
     },
     async ({ specPath, configPath }) => {
       let securityEnabled = false;
@@ -235,9 +268,9 @@ Status: Valid (${allowlist.length} specs on allowlist)`
     "stackwright_pro_add_approved_spec",
     "Add an OpenAPI spec to the approved-specs allowlist in stackwright.yml. Computes the SHA-256 hash of the spec and adds it to the security configuration. Use this when onboarding a new API in enterprise environments.",
     {
-      name: z2.string().describe("Human-readable name for the spec"),
-      url: z2.string().describe("URL or file path to the OpenAPI spec"),
-      configPath: z2.string().optional().describe("Path to stackwright.yml")
+      name: z3.string().describe("Human-readable name for the spec"),
+      url: z3.string().describe("URL or file path to the OpenAPI spec"),
+      configPath: z3.string().optional().describe("Path to stackwright.yml")
     },
     async ({ name, url, configPath }) => {
       const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
@@ -291,7 +324,7 @@ SHA-256 computed: ${sha256}`
     "stackwright_pro_list_approved_specs",
     "List all specs currently on the approved-specs allowlist. Shows spec names, URLs, and hash prefixes. Use this to audit what APIs are approved in the project.",
     {
-      configPath: z2.string().optional().describe("Path to stackwright.yml")
+      configPath: z3.string().optional().describe("Path to stackwright.yml")
     },
     async ({ configPath }) => {
       const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
@@ -360,16 +393,18 @@ SHA-256 computed: ${sha256}`
 }
 
 // src/tools/isr.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 function registerIsrTools(server2) {
   server2.tool(
     "stackwright_pro_configure_isr",
     "Configure Incremental Static Regeneration (ISR) for an API-backed collection. ISR allows API data to be cached and refreshed on a schedule, providing real-time data with the performance of static generation. Use this after stackwright_pro_generate_filter to set revalidation intervals.",
     {
-      collection: z3.string().describe('Collection name (e.g., "equipment", "supplies")'),
-      revalidateSeconds: z3.number().optional().describe("Revalidation interval in seconds (default: 60)"),
-      fallback: z3.enum(["blocking", "true", "false"]).optional().describe("Fallback behavior for new pages"),
-      configPath: z3.string().optional().describe("Path to stackwright.yml")
+      collection: z4.string().describe('Collection name (e.g., "equipment", "supplies")'),
+      revalidateSeconds: numCoerce(z4.number().optional()).describe(
+        "Revalidation interval in seconds (default: 60)"
+      ),
+      fallback: z4.enum(["blocking", "true", "false"]).optional().describe("Fallback behavior for new pages"),
+      configPath: z4.string().optional().describe("Path to stackwright.yml")
     },
     async ({ collection, revalidateSeconds = 60, fallback = "blocking", configPath }) => {
       const revalidate = revalidateSeconds;
@@ -412,14 +447,16 @@ ${yamlSnippet}
     "stackwright_pro_configure_isr_batch",
     "Configure ISR for multiple collections at once. More efficient than calling stackwright_pro_configure_isr multiple times. Provide different revalidation intervals based on data freshness requirements.",
     {
-      collections: z3.array(
-        z3.object({
-          name: z3.string().describe("Collection name"),
-          revalidateSeconds: z3.number().optional().describe("Revalidation interval")
-        })
+      collections: jsonCoerce(
+        z4.array(
+          z4.object({
+            name: z4.string().describe("Collection name"),
+            revalidateSeconds: numCoerce(z4.number().optional()).describe("Revalidation interval")
+          })
+        )
       ).describe("Array of collection configurations"),
-      defaultFallback: z3.enum(["blocking", "true", "false"]).optional().describe("Default fallback behavior"),
-      configPath: z3.string().optional().describe("Path to stackwright.yml")
+      defaultFallback: z4.enum(["blocking", "true", "false"]).optional().describe("Default fallback behavior"),
+      configPath: z4.string().optional().describe("Path to stackwright.yml")
     },
     async ({ collections, defaultFallback = "blocking", configPath }) => {
       const lines = [`\u2699\uFE0F Batch ISR Configuration:
@@ -447,17 +484,17 @@ Fallback: ${defaultFallback}`);
 }
 
 // src/tools/dashboard.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 import { listEntities as listEntities2 } from "@stackwright-pro/cli-data-explorer";
 function registerDashboardTools(server2) {
   server2.tool(
     "stackwright_pro_generate_dashboard",
     "Generate a dashboard page configuration for displaying API data. Creates YAML content for a Stackwright page with grid, metric_card, data_table, and collection_list content types. Use this after stackwright_pro_generate_filter to create pages for your API collections.",
     {
-      entities: z4.array(z4.string()).describe("Entity slugs to include in dashboard"),
-      layout: z4.enum(["grid", "table", "mixed"]).optional().describe("Dashboard layout style"),
-      pageTitle: z4.string().optional().describe("Page title"),
-      specPath: z4.string().optional().describe("Path to OpenAPI spec for entity details")
+      entities: jsonCoerce(z5.array(z5.string())).describe("Entity slugs to include in dashboard"),
+      layout: z5.enum(["grid", "table", "mixed"]).optional().describe("Dashboard layout style"),
+      pageTitle: z5.string().optional().describe("Page title"),
+      specPath: z5.string().optional().describe("Path to OpenAPI spec for entity details")
     },
     async ({ entities, layout = "mixed", pageTitle, specPath }) => {
       let entityDetails = [];
@@ -543,9 +580,9 @@ ${yaml}
     "stackwright_pro_generate_detail_page",
     "Generate a detail view page for a single API entity. Creates YAML content for displaying all fields of an individual record. Use this to create detail pages that complement collection listing pages.",
     {
-      entity: z4.string().describe('Entity slug (e.g., "equipment")'),
-      slugField: z4.string().optional().describe('Field to use as URL slug (default: "id")'),
-      specPath: z4.string().optional().describe("Path to OpenAPI spec for field details")
+      entity: z5.string().describe('Entity slug (e.g., "equipment")'),
+      slugField: z5.string().optional().describe('Field to use as URL slug (default: "id")'),
+      specPath: z5.string().optional().describe("Path to OpenAPI spec for field details")
     },
     async ({ entity, slugField = "id", specPath }) => {
       let fields = [];
@@ -621,7 +658,7 @@ ${yaml}
 }
 
 // src/tools/clarification.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var CONTRADICTION_PATTERNS = [
   {
     keywords: ["minimal", "clean", "simple"],
@@ -709,12 +746,14 @@ function registerClarificationTools(server2) {
     "stackwright_pro_clarify",
     "Ask the user for clarification when a specialist otter encounters ambiguity. This is for MID-EXECUTION questions, NOT upfront question collection (use the Question Manifest Protocol for that). Returns a structured response for the foreman to present to the user via ask_user_question (closed_choice) or directly (open_text).",
     {
-      context: z5.string().optional().describe("Context about what the otter is trying to do"),
-      question_type: z5.enum(["closed_choice", "open_text"]).describe("Type of question being asked"),
-      question: z5.string().describe("The clarification question to ask the user"),
-      choices: z5.array(z5.string()).optional().describe("Options for closed_choice questions"),
-      priority: z5.enum(["blocking", "preferred", "optional"]).optional().default("preferred").describe("How critical is this clarification? Default: preferred"),
-      target_field: z5.string().optional().describe("What field/config does this clarify?")
+      context: z6.string().optional().describe("Context about what the otter is trying to do"),
+      question_type: z6.enum(["closed_choice", "open_text"]).describe("Type of question being asked"),
+      question: z6.string().describe("The clarification question to ask the user"),
+      choices: jsonCoerce(z6.array(z6.string()).optional()).describe(
+        "Options for closed_choice questions"
+      ),
+      priority: z6.enum(["blocking", "preferred", "optional"]).optional().default("preferred").describe("How critical is this clarification? Default: preferred"),
+      target_field: z6.string().optional().describe("What field/config does this clarify?")
     },
     async ({ context, question_type, question, choices, priority, target_field }) => {
       const result = handleClarify({
@@ -743,8 +782,10 @@ function registerClarificationTools(server2) {
     "stackwright_pro_detect_conflict",
     "Detect when a user's stated preference conflicts with their selected choices. Uses keyword heuristics against known contradiction patterns (minimal vs vibrant, dark vs light, etc). Returns conflict details and resolution options.",
     {
-      stated_preference: z5.string().describe("What the user said they wanted"),
-      selected_values: z5.record(z5.string(), z5.string()).describe("What the user actually selected (field \u2192 value)")
+      stated_preference: z6.string().describe("What the user said they wanted"),
+      selected_values: jsonCoerce(z6.record(z6.string(), z6.string())).describe(
+        "What the user actually selected (field \u2192 value)"
+      )
     },
     async ({ stated_preference, selected_values }) => {
       const result = handleDetectConflict({ stated_preference, selected_values });
@@ -789,7 +830,7 @@ ${result.resolution_options?.map((o) => `  \u2022 ${o}`).join("\n")}
 }
 
 // src/tools/packages.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 import { readFileSync, writeFileSync, existsSync, realpathSync, lstatSync } from "fs";
 import { execSync } from "child_process";
 import path2 from "path";
@@ -810,17 +851,23 @@ function registerPackageTools(server2) {
     "Ensures pro packages are present in a project's package.json. Safe to call multiple times \u2014 never overwrites existing version pins. Use this to bootstrap dependencies before specialist otters run. Pass includeBaseline: true to automatically include all required @stackwright-pro/* baseline dependencies. Safe to call on existing projects \u2014 never overwrites pinned versions.",
     {
       // FIX 3 (B-new-1): Zod v4 requires two-arg z.record(keySchema, valueSchema)
-      packages: z6.record(z6.string(), z6.string()).describe(
-        'Dependencies to add. Record<packageName, version>. e.g. { "@stackwright-pro/auth": "latest" }'
+      packages: z7.record(z7.string(), z7.string()).optional().default({}).describe(
+        'Dependencies to add. Record<packageName, version>. e.g. { "@stackwright-pro/auth": "latest" }. Omit or pass {} when using includeBaseline: true.'
+      ),
+      devPackages: jsonCoerce(z7.record(z7.string(), z7.string()).optional()).describe(
+        "devDependencies to add. Same format as packages."
       ),
-      devPackages: z6.record(z6.string(), z6.string()).optional().describe("devDependencies to add. Same format as packages."),
-      scripts: z6.record(z6.string(), z6.string()).optional().describe("npm scripts to add. Only adds if key does not already exist."),
-      targetDir: z6.string().optional().describe(
+      scripts: jsonCoerce(z7.record(z7.string(), z7.string()).optional()).describe(
+        "npm scripts to add. Only adds if key does not already exist."
+      ),
+      targetDir: z7.string().optional().describe(
         "Project directory containing package.json. Defaults to process.cwd(). Must be an absolute path within the current working directory."
       ),
-      runInstall: z6.boolean().optional().default(true).describe("Run pnpm install after writing package.json. Defaults to true."),
-      includeBaseline: z6.boolean().optional().default(false).describe(
-        "When true, automatically merges BASELINE_DEPS and BASELINE_DEV_DEPS before applying packages/devPackages args. Safe to call on existing projects \u2014 never overwrites pinned versions."
+      runInstall: boolCoerce(z7.boolean().optional().default(true)).describe(
+        "Run pnpm install after writing package.json. Defaults to true. Pass boolean true/false."
+      ),
+      includeBaseline: boolCoerce(z7.boolean().optional().default(false)).describe(
+        "When true, automatically merges BASELINE_DEPS and BASELINE_DEV_DEPS before applying packages/devPackages args. Safe to call on existing projects \u2014 never overwrites pinned versions. Pass boolean true/false."
       )
     },
     async ({ packages, devPackages, scripts, targetDir, runInstall, includeBaseline }) => {
@@ -978,11 +1025,11 @@ function setupPackages(opts) {
       }
     }
     const raw = readFileSync(realPackageJsonPath, "utf8");
-    const PackageJsonSchema = z6.object({
+    const PackageJsonSchema = z7.object({
       // Zod v4: z.record(keySchema, valueSchema) — two-arg form required
-      dependencies: z6.record(z6.string(), z6.string()).optional(),
-      devDependencies: z6.record(z6.string(), z6.string()).optional(),
-      scripts: z6.record(z6.string(), z6.string()).optional()
+      dependencies: z7.record(z7.string(), z7.string()).optional(),
+      devDependencies: z7.record(z7.string(), z7.string()).optional(),
+      scripts: z7.record(z7.string(), z7.string()).optional()
     }).passthrough();
     const schemaResult = PackageJsonSchema.safeParse(JSON.parse(raw));
     if (!schemaResult.success) {
@@ -1065,7 +1112,7 @@ function setupPackages(opts) {
 // src/tools/questions.ts
 import { readFile } from "fs/promises";
 import { join } from "path";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/question-adapter.ts
 function truncate(str, maxLength) {
@@ -1251,22 +1298,22 @@ function answersToManifestFormat(answers, questions) {
 }
 
 // src/tools/questions.ts
-var ManifestQuestionSchema = z7.object({
-  id: z7.string(),
-  question: z7.string(),
-  type: z7.enum(["text", "select", "multi-select", "confirm"]),
-  required: z7.boolean().optional(),
-  options: z7.array(
-    z7.object({
-      label: z7.string(),
-      value: z7.string()
+var ManifestQuestionSchema = z8.object({
+  id: z8.string(),
+  question: z8.string(),
+  type: z8.enum(["text", "select", "multi-select", "confirm"]),
+  required: z8.boolean().optional(),
+  options: z8.array(
+    z8.object({
+      label: z8.string(),
+      value: z8.string()
     })
   ).optional(),
-  default: z7.union([z7.string(), z7.boolean(), z7.array(z7.string())]).optional(),
-  help: z7.string().optional(),
-  dependsOn: z7.object({
-    questionId: z7.string(),
-    value: z7.union([z7.string(), z7.array(z7.string())])
+  default: z8.union([z8.string(), z8.boolean(), z8.array(z8.string())]).optional(),
+  help: z8.string().optional(),
+  dependsOn: z8.object({
+    questionId: z8.string(),
+    value: z8.union([z8.string(), z8.array(z8.string())])
   }).optional()
 });
 function registerQuestionTools(server2) {
@@ -1274,11 +1321,13 @@ function registerQuestionTools(server2) {
     "stackwright_pro_present_phase_questions",
     "Adapt manifest-format questions from a specialist otter and present them to the user via ask_user_question. Pass only the phase name \u2014 this tool reads questions from .stackwright/question-manifest.json automatically. The questions parameter is optional and only needed if the manifest has not been written yet. Use this instead of calling ask_user_question directly \u2014 it handles label truncation (50-char limit), header generation, confirm/text defaults, and correct array formatting automatically. IMPORTANT: This is the ONLY approved way to prepare questions before calling ask_user_question. Never call ask_user_question with raw manifest questions. Never retry ask_user_question validation errors by calling it directly \u2014 always re-call this tool.",
     {
-      phase: z7.string().describe('Phase name for display context, e.g. "designer", "api", "auth"'),
-      questions: z7.array(ManifestQuestionSchema).optional().describe(
+      phase: z8.string().describe('Phase name for display context, e.g. "designer", "api", "auth"'),
+      questions: jsonCoerce(z8.array(ManifestQuestionSchema).optional()).describe(
         "Questions in Question Manifest format. If omitted, questions are read from .stackwright/question-manifest.json using the phase name."
       ),
-      answers: z7.record(z7.string(), z7.union([z7.string(), z7.array(z7.string()), z7.boolean()])).optional().describe("Previously collected answers used to resolve dependsOn conditions")
+      answers: jsonCoerce(
+        z8.record(z8.string(), z8.union([z8.string(), z8.array(z8.string()), z8.boolean()])).optional()
+      ).describe("Previously collected answers used to resolve dependsOn conditions")
     },
     async ({ phase, questions, answers }) => {
       let resolvedQuestions;
@@ -1363,7 +1412,7 @@ function registerQuestionTools(server2) {
 }
 
 // src/tools/orchestration.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync, lstatSync as lstatSync2 } from "fs";
 import { join as join2 } from "path";
 var OTTER_NAME_TO_PHASE = [
@@ -1536,8 +1585,8 @@ function registerOrchestrationTools(server2) {
     "stackwright_pro_parse_otter_response",
     "Parse and validate a specialist otter's QUESTION_COLLECTION_MODE JSON response. Handles JSON extraction from LLM responses (strips markdown, fixes single quotes, trailing commas). Detects the phase from the otter name. Use this immediately after invoke_agent() to get a validated manifest phase object.",
     {
-      otterName: z8.string().describe('The agent name, e.g. "stackwright-pro-api-otter"'),
-      responseText: z8.string().describe("Raw text response from the otter's QUESTION_COLLECTION_MODE invocation")
+      otterName: z9.string().describe('The agent name, e.g. "stackwright-pro-api-otter"'),
+      responseText: z9.string().describe("Raw text response from the otter's QUESTION_COLLECTION_MODE invocation")
     },
     async ({ otterName, responseText }) => {
       const { result, isError } = handleParseOtterResponse({ otterName, responseText });
@@ -1551,16 +1600,18 @@ function registerOrchestrationTools(server2) {
     "stackwright_pro_save_manifest",
     "Write the question manifest to .stackwright/question-manifest.json. Call this after collecting and parsing questions from all otters via stackwright_pro_parse_otter_response.",
     {
-      phases: z8.array(
-        z8.object({
-          phase: z8.string(),
-          otter: z8.string(),
-          questions: z8.array(z8.any()),
-          requiredPackages: z8.object({
-            dependencies: z8.record(z8.string(), z8.string()).optional(),
-            devPackages: z8.record(z8.string(), z8.string()).optional()
-          }).optional()
-        })
+      phases: jsonCoerce(
+        z9.array(
+          z9.object({
+            phase: z9.string(),
+            otter: z9.string(),
+            questions: z9.array(z9.any()),
+            requiredPackages: z9.object({
+              dependencies: z9.record(z9.string(), z9.string()).optional(),
+              devPackages: z9.record(z9.string(), z9.string()).optional()
+            }).optional()
+          })
+        )
       ).describe("Array of parsed phase objects from stackwright_pro_parse_otter_response")
     },
     async ({ phases }) => {
@@ -1575,15 +1626,21 @@ function registerOrchestrationTools(server2) {
     "stackwright_pro_save_phase_answers",
     "Save user answers for a phase to .stackwright/answers/{phase}.json. Pass rawAnswers directly from ask_user_question and the original manifest questions for label-to-value reverse mapping.",
     {
-      phase: z8.string().describe('Phase name, e.g. "designer"'),
-      rawAnswers: z8.array(
-        z8.object({
-          question_header: z8.string(),
-          selected_options: z8.array(z8.string()),
-          other_text: z8.string().nullable().optional()
-        })
-      ).describe("Answers as returned by ask_user_question"),
-      questions: z8.array(z8.any()).optional().describe("Original manifest questions for label\u2192value reverse-mapping")
+      phase: z9.string().describe('Phase name, e.g. "designer"'),
+      rawAnswers: jsonCoerce(
+        z9.array(
+          z9.object({
+            question_header: z9.string(),
+            selected_options: z9.array(z9.string()),
+            other_text: z9.string().nullable().optional()
+          })
+        )
+      ).describe(
+        "Answers as returned by ask_user_question \u2014 pass the native array, not a JSON string"
+      ),
+      questions: jsonCoerce(z9.array(z9.any()).optional()).describe(
+        "Original manifest questions for label\u2192value reverse-mapping \u2014 pass the native array, not a JSON string"
+      )
     },
     async ({ phase, rawAnswers, questions }) => {
       const { text, isError } = handleSavePhaseAnswers({
@@ -1601,7 +1658,7 @@ function registerOrchestrationTools(server2) {
     "stackwright_pro_read_phase_answers",
     "Read saved answers for a phase from .stackwright/answers/{phase}.json. Returns { missing: true } when no answers exist yet \u2014 use this to skip phases safely in the execution loop.",
     {
-      phase: z8.string().describe('Phase name, e.g. "designer"')
+      phase: z9.string().describe('Phase name, e.g. "designer"')
     },
     async ({ phase }) => {
       const { text, isError } = handleReadPhaseAnswers({ phase });
@@ -1615,7 +1672,7 @@ function registerOrchestrationTools(server2) {
     "stackwright_pro_get_otter_name",
     "Get the agent name for a phase (e.g. 'designer' \u2192 'stackwright-pro-designer-otter'). Use this in the execution loop to invoke the correct specialist otter without hardcoding names in the prompt.",
     {
-      phase: z8.string().describe('Phase name, e.g. "designer", "api", "pages"')
+      phase: z9.string().describe('Phase name, e.g. "designer", "api", "pages"')
     },
     async ({ phase }) => {
       const { text, isError } = handleGetOtterName({ phase });
@@ -1628,7 +1685,7 @@ function registerOrchestrationTools(server2) {
 }
 
 // src/tools/pipeline.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync3, mkdirSync as mkdirSync2, lstatSync as lstatSync3 } from "fs";
 import { join as join3 } from "path";
 var PHASE_ORDER = [
@@ -2102,11 +2159,15 @@ function registerPipelineTools(server2) {
     "stackwright_pro_set_pipeline_state",
     `Atomic read\u2192modify\u2192write pipeline state. ${DESC}`,
     {
-      phase: z9.string().optional().describe('Phase to update, e.g. "designer"'),
-      field: z9.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
-      value: z9.boolean().optional().describe("Value for the field"),
-      status: z9.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
-      incrementRetry: z9.boolean().optional().describe("Bump retryCount by 1")
+      phase: z10.string().optional().describe('Phase to update, e.g. "designer"'),
+      field: z10.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
+      value: boolCoerce(z10.boolean().optional()).describe(
+        'Value for the field \u2014 must be a JSON boolean (true/false), NOT the string "true"/"false"'
+      ),
+      status: z10.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
+      incrementRetry: boolCoerce(z10.boolean().optional()).describe(
+        "Bump retryCount by 1 \u2014 must be a JSON boolean"
+      )
     },
     async (args) => res(
       handleSetPipelineState({
@@ -2134,30 +2195,30 @@ function registerPipelineTools(server2) {
     "stackwright_pro_write_phase_questions",
     `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. ${DESC}`,
     {
-      phase: z9.string().describe('Phase name, e.g. "designer"'),
-      responseText: z9.string().describe("Raw LLM response from QUESTION_COLLECTION_MODE")
+      phase: z10.string().describe('Phase name, e.g. "designer"'),
+      responseText: z10.string().describe("Raw LLM response from QUESTION_COLLECTION_MODE")
     },
     async ({ phase, responseText }) => res(handleWritePhaseQuestions({ phase, responseText }))
   );
   server2.tool(
     "stackwright_pro_build_specialist_prompt",
     `Assemble execution prompt from answers + upstream artifacts. Foreman passes verbatim. ${DESC}`,
-    { phase: z9.string().describe('Phase to build prompt for, e.g. "pages"') },
+    { phase: z10.string().describe('Phase to build prompt for, e.g. "pages"') },
     async ({ phase }) => res(handleBuildSpecialistPrompt({ phase }))
   );
   server2.tool(
     "stackwright_pro_validate_artifact",
     `Validate specialist response + write artifact to .stackwright/artifacts/. Returns retryPrompt on failure. ${DESC}`,
     {
-      phase: z9.string().describe('Phase that produced this artifact, e.g. "designer"'),
-      responseText: z9.string().describe("Raw response text from the specialist otter")
+      phase: z10.string().describe('Phase that produced this artifact, e.g. "designer"'),
+      responseText: z10.string().describe("Raw response text from the specialist otter")
     },
     async ({ phase, responseText }) => res(handleValidateArtifact({ phase, responseText }))
   );
 }
 
 // src/tools/safe-write.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 import { writeFileSync as writeFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync3, lstatSync as lstatSync4 } from "fs";
 import { normalize, isAbsolute, dirname, join as join4 } from "path";
 var OTTER_WRITE_ALLOWLISTS = {
@@ -2389,10 +2450,10 @@ function registerSafeWriteTools(server2) {
     "stackwright_pro_safe_write",
     DESC,
     {
-      callerOtter: z10.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
-      filePath: z10.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
-      content: z10.string().describe("File content to write"),
-      createDirectories: z10.boolean().optional().describe("Create parent directories if they don't exist. Default: true")
+      callerOtter: z11.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
+      filePath: z11.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
+      content: z11.string().describe("File content to write"),
+      createDirectories: z11.boolean().optional().describe("Create parent directories if they don't exist. Default: true")
     },
     async ({ callerOtter, filePath, content, createDirectories }) => {
       const result = handleSafeWrite({
@@ -2407,7 +2468,7 @@ function registerSafeWriteTools(server2) {
 }
 
 // src/tools/auth.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync5, existsSync as existsSync5 } from "fs";
 import { join as join5 } from "path";
 function buildHierarchy(roles) {
@@ -2762,35 +2823,35 @@ function registerAuthTools(server2) {
     "stackwright_pro_configure_auth",
     "Generate authentication middleware and configuration for a Next.js Stackwright application. Writes `middleware.ts` from a secure template, appends/updates the `auth:` section in `stackwright.yml`, and generates `.env.example` with required environment variables. \u26A0\uFE0F For CAC/PKI: generated `middleware.ts` carries a SECURITY REVIEW REQUIRED comment \u2014 certificate chain validation must be verified by a DoD security officer before production deployment. This is the ONLY approved path to generating `middleware.ts`. Never write TypeScript auth files directly.",
     {
-      method: z11.enum(["cac", "oidc", "oauth2", "none"]),
-      provider: z11.enum(["azure-ad", "okta", "ping", "cognito", "custom"]).optional(),
+      method: z12.enum(["cac", "oidc", "oauth2", "none"]),
+      provider: z12.enum(["azure-ad", "okta", "ping", "cognito", "custom"]).optional(),
       // CAC
-      cacCaBundle: z11.string().optional(),
-      cacEdipiLookup: z11.string().optional(),
-      cacOcspEndpoint: z11.string().optional(),
-      cacCertHeader: z11.string().optional(),
+      cacCaBundle: z12.string().optional(),
+      cacEdipiLookup: z12.string().optional(),
+      cacOcspEndpoint: z12.string().optional(),
+      cacCertHeader: z12.string().optional(),
       // OIDC
-      oidcDiscoveryUrl: z11.string().optional(),
-      oidcClientId: z11.string().optional(),
-      oidcClientSecret: z11.string().optional(),
-      oidcScopes: z11.string().optional(),
-      oidcRoleClaim: z11.string().optional(),
+      oidcDiscoveryUrl: z12.string().optional(),
+      oidcClientId: z12.string().optional(),
+      oidcClientSecret: z12.string().optional(),
+      oidcScopes: z12.string().optional(),
+      oidcRoleClaim: z12.string().optional(),
       // OAuth2
-      oauth2AuthUrl: z11.string().optional(),
-      oauth2TokenUrl: z11.string().optional(),
-      oauth2ClientId: z11.string().optional(),
-      oauth2ClientSecret: z11.string().optional(),
-      oauth2Scopes: z11.string().optional(),
+      oauth2AuthUrl: z12.string().optional(),
+      oauth2TokenUrl: z12.string().optional(),
+      oauth2ClientId: z12.string().optional(),
+      oauth2ClientSecret: z12.string().optional(),
+      oauth2Scopes: z12.string().optional(),
       // RBAC
-      rbacRoles: z11.array(z11.string()).optional(),
-      rbacDefaultRole: z11.string().optional(),
+      rbacRoles: jsonCoerce(z12.array(z12.string()).optional()),
+      rbacDefaultRole: z12.string().optional(),
       // Audit
-      auditEnabled: z11.boolean().optional(),
-      auditRetentionDays: z11.number().int().positive().optional(),
+      auditEnabled: boolCoerce(z12.boolean().optional()),
+      auditRetentionDays: numCoerce(z12.number().int().positive().optional()),
       // Routes
-      protectedRoutes: z11.array(z11.string()).optional(),
+      protectedRoutes: jsonCoerce(z12.array(z12.string()).optional()),
       // Injection for tests
-      _cwd: z11.string().optional()
+      _cwd: z12.string().optional()
     },
     async (params) => {
       const cwd = params._cwd ?? process.cwd();
@@ -2826,7 +2887,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "27f4dfd4676246c9fea14fd1de4f148928eeaf06e58b08240761fd3e663dd540"
+    "f52264c1f6297b72f3da6d92d41b6d63356db776242caeab25571e6a8df628e4"
   ],
   [
     "stackwright-pro-page-otter.json",
@@ -3018,7 +3079,7 @@ function registerIntegrityTools(server2) {
 }
 
 // src/tools/domain.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 import { readFileSync as readFileSync6, existsSync as existsSync6 } from "fs";
 import { join as join7 } from "path";
 function handleListCollections(input) {
@@ -3404,7 +3465,7 @@ function registerDomainTools(server2) {
     "stackwright_pro_resolve_data_strategy",
     "Look up the data freshness strategy configuration from the user's answer. Returns mechanism, revalidation seconds, required packages, and the exact MCP tool call to make. Replaces the strategy table in the data-otter prompt.",
     {
-      strategy: z12.string().describe(
+      strategy: z13.string().describe(
         'The data-1 answer value: "pulse-fast", "isr-fast", "isr-standard", or "isr-slow"'
       )
     },
@@ -3414,7 +3475,7 @@ function registerDomainTools(server2) {
     "stackwright_pro_validate_workflow",
     "Validate a workflow definition against the Stackwright workflow schema. Checks step ID uniqueness, transition targets, terminal state existence, and service references. Call this after the workflow otter produces output.",
     {
-      workflow: z12.record(z12.string(), z12.unknown()).optional().describe(
+      workflow: jsonCoerce(z13.record(z13.string(), z13.unknown()).optional()).describe(
         "Parsed workflow object. If omitted, reads from .stackwright/artifacts/workflow-config.json"
       )
     },
@@ -3444,7 +3505,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.12",
+  version: "0.2.0-alpha.14",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "PROPRIETARY",
   main: "./dist/server.js",