@stackwright-pro/mcp 0.0.0-beta-20260417191149

package/dist/server.mjs

@@ -0,0 +1,1243 @@
+// src/server.ts
+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 { listEntities, generateFilter } from "@stackwright-pro/cli-data-explorer";
+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)")
+    },
+    async ({ specPath, projectRoot }) => {
+      const result = listEntities({
+        ...specPath !== void 0 && { specPath },
+        ...projectRoot !== void 0 && { projectRoot }
+      });
+      if (!result.success) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error discovering entities: ${(result.errors ?? []).join(", ")}`
+            }
+          ],
+          isError: true
+        };
+      }
+      const lines = [`\u{1F4E6} Found ${result.entities.length} API Entities:
+`];
+      for (const entity of result.entities) {
+        lines.push(`\u{1F4E6} ${entity.name} (${entity.slug})`);
+        lines.push(`   Endpoint: ${entity.endpoint}`);
+        lines.push(`   Fields: ${entity.fieldCount}`);
+        if (entity.fields.length > 0) {
+          const fieldTypes = entity.fields.slice(0, 3).map((f) => `${f.name}:${f.type}`).join(", ");
+          lines.push(`   Types: ${fieldTypes}${entity.fields.length > 3 ? "..." : ""}`);
+        }
+        lines.push("");
+      }
+      lines.push(
+        `
+\u{1F4A1} Use stackwright_pro_generate_filter with selected entity slugs to create endpoint filters.`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: lines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "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")
+    },
+    async ({ selectedEntities, excludePatterns, projectRoot }) => {
+      const result = generateFilter({
+        selectedEntities,
+        ...excludePatterns !== void 0 && { excludePatterns },
+        projectRoot: projectRoot ?? process.cwd()
+      });
+      if (!result.success) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error generating filter: ${result.warnings?.join(", ")}`
+            }
+          ],
+          isError: true
+        };
+      }
+      const lines = ["\u{1F510} Generated Endpoint Filter:\n"];
+      lines.push("```yaml");
+      lines.push("integrations:");
+      lines.push("  - type: openapi");
+      lines.push("    endpoints:");
+      if (result.filter.include && result.filter.include.length > 0) {
+        lines.push("      include:");
+        for (const path3 of result.filter.include) {
+          lines.push(`        - ${path3}`);
+        }
+      }
+      if (result.filter.exclude && result.filter.exclude.length > 0) {
+        lines.push("      exclude:");
+        for (const pattern of result.filter.exclude) {
+          lines.push(`        - ${pattern}`);
+        }
+      }
+      lines.push("```");
+      if (result.warnings && result.warnings.length > 0) {
+        lines.push("\n\u26A0\uFE0F Warnings:");
+        for (const warning of result.warnings) {
+          lines.push(`  ${warning}`);
+        }
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: lines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/security.ts
+import { z as z2 } from "zod";
+import { createHash } from "crypto";
+import fs from "fs";
+import path from "path";
+function registerSecurityTools(server2) {
+  server2.tool(
+    "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")
+    },
+    async ({ specPath, configPath }) => {
+      let securityEnabled = false;
+      const allowlist = [];
+      const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
+      if (fs.existsSync(configFile)) {
+        try {
+          const content = fs.readFileSync(configFile, "utf8");
+          const securityMatch = content.match(
+            /prebuild:\s*\n\s*security:\s*\n\s*enabled:\s*(true|false)/
+          );
+          if (securityMatch && securityMatch[1] === "true") {
+            securityEnabled = true;
+            const specMatches = content.matchAll(
+              /- name:\s*(.+?)\n\s+url:\s*(.+?)\n\s+sha256:\s*(.+?)(?:\n|$)/g
+            );
+            for (const match of specMatches) {
+              allowlist.push({
+                name: match[1].trim(),
+                url: match[2].trim(),
+                sha256: match[3].trim()
+              });
+            }
+          }
+        } catch {
+        }
+      }
+      if (!securityEnabled) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u2705 Spec validation skipped (security not enabled)
+
+To enable approved-specs validation, add to stackwright.yml:
+
+prebuild:
+  security:
+    enabled: true
+    allowlist:
+      - name: My API
+        url: ${specPath}
+        sha256: <sha256-of-spec>`
+            }
+          ]
+        };
+      }
+      const matchingSpec = allowlist.find((s) => s.url === specPath);
+      if (!matchingSpec) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u274C Spec rejected!
+
+Error Code: SPEC_NOT_IN_ALLOWLIST
+
+URL: ${specPath}
+
+This spec is not on the approved-specs allowlist. Add it using stackwright_pro_add_approved_spec before proceeding.`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!specPath.startsWith("http://") && !specPath.startsWith("https://")) {
+        if (fs.existsSync(specPath)) {
+          const specContent = fs.readFileSync(specPath, "utf8");
+          const sha256 = createHash("sha256").update(specContent).digest("hex");
+          if (sha256 !== matchingSpec.sha256) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `\u274C Spec hash mismatch!
+
+Error Code: SPEC_HASH_MISMATCH
+
+Expected: ${matchingSpec.sha256.substring(0, 16)}...
+Actual:   ${sha256.substring(0, 16)}...
+
+The spec has been modified since it was approved. Re-approve the spec to continue.`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u2705 Spec approved!
+
+Name: ${matchingSpec.name}
+URL: ${specPath}
+Status: Valid (${allowlist.length} specs on allowlist)`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "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")
+    },
+    async ({ name, url, configPath }) => {
+      const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
+      let sha256 = "<computed-at-build>";
+      try {
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+          sha256 = "<computed-at-build>";
+        } else if (fs.existsSync(url)) {
+          const specContent = fs.readFileSync(url, "utf8");
+          sha256 = createHash("sha256").update(specContent).digest("hex");
+        } else {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u274C Spec file not found: ${url}`
+              }
+            ],
+            isError: true
+          };
+        }
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u274C Failed to read spec: ${e}`
+            }
+          ],
+          isError: true
+        };
+      }
+      const yamlSnippet = `  - name: ${name}
+    url: ${url}
+    sha256: ${sha256}`;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u{1F4DD} Add this to stackwright.yml under prebuild.security.allowlist:
+
+${yamlSnippet}
+
+SHA-256 computed: ${sha256}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "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")
+    },
+    async ({ configPath }) => {
+      const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
+      if (!fs.existsSync(configFile)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "\u274C stackwright.yml not found in project root."
+            }
+          ],
+          isError: true
+        };
+      }
+      const content = fs.readFileSync(configFile, "utf8");
+      const securityEnabled = content.includes("prebuild:") && content.includes("security:") && content.includes("enabled: true");
+      if (!securityEnabled) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "\u2139\uFE0F Approved-specs validation is not enabled.\n\nAdd to stackwright.yml to enable:\n\nprebuild:\n  security:\n    enabled: true\n    allowlist: []"
+            }
+          ]
+        };
+      }
+      const specs = [];
+      const specMatches = content.matchAll(
+        /- name:\s*(.+?)\n\s+url:\s*(.+?)\n\s+sha256:\s*(.+?)(?:\n|$)/g
+      );
+      for (const match of specMatches) {
+        specs.push({
+          name: match[1].trim(),
+          url: match[2].trim(),
+          sha256: match[3].trim().substring(0, 16) + "..."
+        });
+      }
+      if (specs.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "\u2139\uFE0F Security enabled but no specs on allowlist.\n\nAdd specs using stackwright_pro_add_approved_spec."
+            }
+          ]
+        };
+      }
+      const lines = [`\u{1F510} Approved Specs (${specs.length}):
+`];
+      for (const spec of specs) {
+        lines.push(`\u{1F4E6} ${spec.name}`);
+        lines.push(`   URL: ${spec.url}`);
+        lines.push(`   Hash: ${spec.sha256}`);
+        lines.push("");
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: lines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/isr.ts
+import { z as z3 } 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")
+    },
+    async ({ collection, revalidateSeconds = 60, fallback = "blocking", configPath }) => {
+      const revalidate = revalidateSeconds;
+      const yamlSnippet = `# Add to stackwright.yml under integrations:
+  - type: openapi
+    name: ${collection}
+    # ... other config
+    isr:
+      revalidate: ${revalidate}
+      fallback: ${fallback}`;
+      let description = "";
+      if (revalidate < 60) {
+        description = "\u26A1 Very fresh data (revalidate every " + revalidate + "s)";
+      } else if (revalidate < 300) {
+        description = "\u{1F4CA} Fresh data (revalidate every " + (revalidate / 60).toFixed(0) + " min)";
+      } else if (revalidate < 3600) {
+        description = "\u{1F4BE} Cached data (revalidate every " + (revalidate / 60).toFixed(0) + " min)";
+      } else {
+        description = "\u{1F5C4}\uFE0F Static data (revalidate every " + (revalidate / 3600).toFixed(0) + " hour)";
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u2699\uFE0F ISR Configuration for "${collection}":
+
+${description}
+
+Fallback: ${fallback === "blocking" ? "\u23F3 Show loading until cached" : fallback === "true" ? "\u{1F4C4} Generate on demand" : "\u274C 404 for new pages"}
+
+\`\`\`yaml
+${yamlSnippet}
+\`\`\``
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "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")
+        })
+      ).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")
+    },
+    async ({ collections, defaultFallback = "blocking", configPath }) => {
+      const lines = [`\u2699\uFE0F Batch ISR Configuration:
+`];
+      for (const col of collections) {
+        const rev = col.revalidateSeconds || 60;
+        let freshness = "\u{1F4BE}";
+        if (rev < 60) freshness = "\u26A1";
+        else if (rev < 300) freshness = "\u{1F4CA}";
+        else if (rev >= 3600) freshness = "\u{1F5C4}\uFE0F";
+        lines.push(`${freshness} ${col.name}: revalidate=${rev}s`);
+      }
+      lines.push(`
+Fallback: ${defaultFallback}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: lines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/dashboard.ts
+import { z as z4 } 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")
+    },
+    async ({ entities, layout = "mixed", pageTitle, specPath }) => {
+      let entityDetails = [];
+      if (specPath) {
+        const result = listEntities2({ specPath });
+        if (result.success) {
+          entityDetails = result.entities.filter((e) => entities.includes(e.slug));
+        }
+      }
+      const title = pageTitle || entities.map((e) => e.charAt(0).toUpperCase() + e.slice(1)).join(" & ");
+      const yamlLines = [
+        "# Dashboard page configuration",
+        "# Generated by Stackwright Pro MCP",
+        "",
+        "content:",
+        "  meta:",
+        `    title: "${title} | Dashboard"`,
+        `    description: "Live data from API"`,
+        "",
+        "  content_items:"
+      ];
+      if (layout === "grid" || layout === "mixed") {
+        for (const slug of entities) {
+          yamlLines.push(`    - type: grid`);
+          yamlLines.push(`      columns: 4`);
+          yamlLines.push(`      items:`);
+          yamlLines.push(`        - type: metric_card`);
+          yamlLines.push(`          label: "Total"`);
+          yamlLines.push(`          value: {{ ${slug}.count }}`);
+          yamlLines.push(`          icon: Database`);
+          yamlLines.push(`        - type: metric_card`);
+          yamlLines.push(`          label: "Active"`);
+          yamlLines.push(`          value: 0`);
+          yamlLines.push(`          icon: CheckCircle`);
+          yamlLines.push("");
+        }
+      }
+      yamlLines.push(`    - type: collection_list`);
+      yamlLines.push(`      label: ${entities[0]}-listing`);
+      yamlLines.push(`      collection: ${entities[0]}`);
+      yamlLines.push(`      showFilters: true`);
+      yamlLines.push(`      showSearch: true`);
+      const defaultCols = ["id", "name", "status", "created_at"];
+      yamlLines.push(
+        `      columns: ${entityDetails[0]?.fields?.slice(0, 4).map((f) => f.name).join(", ") || defaultCols.join(", ")}`
+      );
+      yamlLines.push("");
+      if (layout === "table") {
+        yamlLines.push(`    - type: data_table`);
+        yamlLines.push(`      label: ${entities[0]}-table`);
+        yamlLines.push(`      collection: ${entities[0]}`);
+        yamlLines.push(`      columns:`);
+        yamlLines.push(`        - field: id`);
+        yamlLines.push(`          header: ID`);
+        yamlLines.push(`          sortable: true`);
+        yamlLines.push(`        - field: name`);
+        yamlLines.push(`          header: Name`);
+        yamlLines.push(`          sortable: true`);
+        yamlLines.push(`        - field: status`);
+        yamlLines.push(`          header: Status`);
+        yamlLines.push(`          type: badge`);
+      }
+      const yaml = yamlLines.join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u{1F4CA} Generated Dashboard for: ${entities.join(", ")}
+
+Layout: ${layout}
+
+\`\`\`yaml
+${yaml}
+\`\`\`
+
+\u{1F4A1} Add this to pages/dashboard/content.yml and validate with stackwright_validate_pages.`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "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")
+    },
+    async ({ entity, slugField = "id", specPath }) => {
+      let fields = [];
+      if (specPath) {
+        const result = listEntities2({ specPath });
+        if (result.success) {
+          const ent = result.entities.find((e) => e.slug === entity);
+          if (ent) {
+            fields = ent.fields;
+          }
+        }
+      }
+      const entityName = entity.charAt(0).toUpperCase() + entity.slice(1);
+      const yamlLines = [
+        `# Detail page for ${entityName}`,
+        "# Generated by Stackwright Pro MCP",
+        "",
+        "content:",
+        "  meta:",
+        `    title: "${entityName} Details | {{ ${entity}.${slugField} }}"`,
+        "",
+        "  content_items:",
+        "    - main:",
+        '        label: "detail-header"',
+        "        heading:",
+        `          text: "{{ ${entity}.${slugField} }}"`,
+        '          textSize: "h1"',
+        "        textBlocks:",
+        `          - text: "Details for this ${entity}"`,
+        '            textSize: "body1"',
+        '        background: "primary"',
+        '        color: "text"',
+        "",
+        "    - grid:",
+        '        label: "detail-fields"',
+        "        columns: 2",
+        "        items:"
+      ];
+      const displayFields = fields.length > 0 ? fields.slice(0, 8) : [
+        { name: slugField, type: "string" },
+        { name: "created_at", type: "datetime" },
+        { name: "updated_at", type: "datetime" }
+      ];
+      for (const field of displayFields) {
+        const label = field.name.replace(/_/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+        yamlLines.push(`          - card:`);
+        yamlLines.push(`              label: "${field.name}-field"`);
+        yamlLines.push(`              heading:`);
+        yamlLines.push(`                text: "${label}"`);
+        yamlLines.push(`                textSize: "h4"`);
+        yamlLines.push(`              content:`);
+        yamlLines.push(`                - text: "{{ ${entity}.${field.name} }}"`);
+        yamlLines.push(`                  textSize: "body1"`);
+      }
+      yamlLines.push('        background: "background"');
+      const yaml = yamlLines.join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u{1F4C4} Generated Detail Page for: ${entity}
+
+\`\`\`yaml
+${yaml}
+\`\`\`
+
+\u{1F4A1} Add this to pages/${entity}/[${slugField}]/content.yml and validate.`
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/clarification.ts
+import { z as z5 } from "zod";
+import { spawn } from "child_process";
+import { tmpdir } from "os";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { existsSync, unlinkSync } from "fs";
+var activeServers = /* @__PURE__ */ new Map();
+async function startPythonServer(sessionId) {
+  const socketPath = join(tmpdir(), `otter-raft-${randomUUID()}.sock`);
+  const port = 8765 + Math.floor(Math.random() * 100);
+  return new Promise((resolve, reject) => {
+    const pythonPath = process.platform === "win32" ? "python" : "python3";
+    const packageRoot = findPythonPackageRoot();
+    const proc = spawn(
+      pythonPath,
+      ["-m", "stackwright_pro.raft.server", "--socket", socketPath, "--port", String(port)],
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          PYTHONPATH: packageRoot
+        }
+      }
+    );
+    activeServers.set(sessionId, proc);
+    let startupOutput = "";
+    let started = false;
+    proc.stdout?.on("data", (data) => {
+      startupOutput += data.toString();
+      if (startupOutput.includes("Server ready") || startupOutput.includes("HTTP server")) {
+        started = true;
+        resolve({ port, socketPath });
+      }
+    });
+    proc.stderr?.on("data", (data) => {
+      if (!startupOutput.includes("Starting")) {
+        console.error("[Python Clarification]", data.toString().trim());
+      }
+    });
+    proc.on("error", (err) => {
+      if (!started) {
+        activeServers.delete(sessionId);
+        reject(new Error(`Failed to start Python server: ${err.message}`));
+      }
+    });
+    proc.on("exit", (code) => {
+      activeServers.delete(sessionId);
+      if (existsSync(socketPath)) {
+        try {
+          unlinkSync(socketPath);
+        } catch {
+        }
+      }
+    });
+    setTimeout(() => {
+      if (!started) {
+        proc.kill();
+        activeServers.delete(sessionId);
+        reject(new Error("Python server startup timeout"));
+      }
+    }, 1e4);
+  });
+}
+async function stopPythonServer(sessionId) {
+  const proc = activeServers.get(sessionId);
+  if (proc) {
+    proc.kill("SIGTERM");
+    activeServers.delete(sessionId);
+  }
+}
+async function httpRequest(host, port, path3, body) {
+  const http = await import("http");
+  return new Promise((resolve, reject) => {
+    const url = new URL(path3, `http://${host}:${port}`);
+    const reqOptions = {
+      hostname: host,
+      port,
+      path: url.pathname,
+      method: body ? "POST" : "GET",
+      headers: {
+        "Content-Type": "application/json"
+      }
+    };
+    const req = http.request(reqOptions, (res) => {
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk.toString();
+      });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (res.statusCode && res.statusCode >= 400) {
+            reject(new Error(parsed.detail || parsed.error || `HTTP ${res.statusCode}`));
+          } else {
+            resolve(parsed);
+          }
+        } catch (e) {
+          reject(new Error(`Failed to parse response: ${data}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    if (body) {
+      req.write(JSON.stringify(body));
+    }
+    req.end();
+  });
+}
+function findPythonPackageRoot() {
+  const candidates = [
+    join(__dirname, "../../python/src"),
+    join(__dirname, "../../../python/src"),
+    join(process.cwd(), "python/src")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return process.cwd();
+}
+function registerClarificationTools(server2) {
+  server2.tool(
+    "stackwright_pro_clarify",
+    "Ask the user for clarification when an otter encounters ambiguity. This is for MID-EXECUTION questions, not upfront question collection. Use this when the otter needs user input to proceed. Returns the user's decision which should be used to continue execution.",
+    {
+      context: z5.string().optional().describe("Context about what the otter is trying to do"),
+      question_type: z5.enum(["closed_choice", "open_text", "conditional", "multi_step", "reconciliation"]).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 or multi_step questions"),
+      priority: z5.enum(["blocking", "preferred", "optional"]).optional().describe("How critical is this clarification? Default: preferred"),
+      target_field: z5.string().optional().describe("What field/config does this clarify?")
+    },
+    async ({ context, question_type, question, choices, priority = "preferred", target_field }) => {
+      const sessionId = `mcp_${randomUUID().slice(0, 8)}`;
+      try {
+        const { port } = await startPythonServer(sessionId);
+        await httpRequest(port === 8765 ? "127.0.0.1" : "127.0.0.1", port, "/sessions", {});
+        if (context) {
+          await httpRequest(
+            port === 8765 ? "127.0.0.1" : "127.0.0.1",
+            port,
+            `/sessions/${sessionId}/context`,
+            { context: { purpose: context } }
+          );
+        }
+        const request = {
+          ...context !== void 0 && { context },
+          question_type,
+          question,
+          ...choices !== void 0 && { choices },
+          priority,
+          ...target_field !== void 0 && { target_field }
+        };
+        const response = await httpRequest(
+          port === 8765 ? "127.0.0.1" : "127.0.0.1",
+          port,
+          "/clarify",
+          { request }
+        );
+        await stopPythonServer(sessionId);
+        const decision = response.decision;
+        const value = decision.value;
+        const source = decision.source;
+        const explicit = decision.explicit ? "explicitly" : "via fallback";
+        if (response.fallback_used) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u26A0\uFE0F Clarification fallback used: ${response.fallback_reason || "No user input available"}
+
+Default value used: ${JSON.stringify(value)}
+
+\u{1F4A1} Consider following up with the user later if this default isn't appropriate.`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u2705 User clarified (${source}): ${JSON.stringify(value)}
+
+Use this value to continue execution.`
+            }
+          ]
+        };
+      } catch (error) {
+        await stopPythonServer(sessionId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u274C Clarification failed: ${error instanceof Error ? error.message : "Unknown error"}
+
+Cannot proceed without user input. Consider:
+1. Using a reasonable default
+2. Asking the user directly in your response
+3. Skipping this step if optional`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "stackwright_pro_detect_conflict",
+    "Detect when a user's stated preference conflicts with their selected choices. Use this to identify when users might be indecisive or misunderstood a question. 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")
+    },
+    async ({ stated_preference, selected_values }) => {
+      const sessionId = `mcp_${randomUUID().slice(0, 8)}`;
+      try {
+        const { port } = await startPythonServer(sessionId);
+        const response = await httpRequest(
+          port === 8765 ? "127.0.0.1" : "127.0.0.1",
+          port,
+          "/conflict",
+          { stated_preference, selected_values }
+        );
+        await stopPythonServer(sessionId);
+        if (response.conflict) {
+          const data = response.data;
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u26A0\uFE0F CONFLICT DETECTED
+
+User stated: "${stated_preference}"
+But selected: ${JSON.stringify(selected_values)}
+
+Conflict: ${data.description}
+
+Resolution options: ${data.options?.join(", ") || "Ask user to clarify"}
+
+\u{1F4A1} Consider asking the user to reconcile this conflict.`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u2705 No conflict detected between stated preference and selections.`
+            }
+          ]
+        };
+      } catch (error) {
+        await stopPythonServer(sessionId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u274C Conflict detection failed: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "stackwright_pro_get_defaults",
+    "Get the current clarification defaults from config. Use this to understand what fallback values will be used if user doesn't provide input.",
+    {
+      config_path: z5.string().optional().describe("Path to config file. Default: .stackwright/clarification.yaml")
+    },
+    async ({ config_path }) => {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u{1F4CB} Clarification defaults
+
+Configuration is loaded from:
+- Environment: CLARIFICATION_* variables
+- Config file: ${config_path || ".stackwright/clarification.yaml"}
+- CLI args: --clarify-* flags
+
+Default behaviors:
+- allow_dont_know: true (users can skip)
+- default_timeout: 120 seconds
+- channel_priority: [tui, cli_args, config, defaults]
+
+\u{1F4A1} Set CLARIFICATION_DEFAULT_<FIELD>=value to change defaults.`
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/packages.ts
+import { z as z6 } from "zod";
+import { readFileSync, writeFileSync, existsSync as existsSync2, realpathSync, lstatSync } from "fs";
+import { execSync } from "child_process";
+import path2 from "path";
+function registerPackageTools(server2) {
+  server2.tool(
+    "stackwright_pro_setup_packages",
+    "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.",
+    {
+      // 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" }'
+      ),
+      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(
+        "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.")
+    },
+    async ({ packages, devPackages, scripts, targetDir, runInstall }) => {
+      const result = setupPackages({
+        packages,
+        runInstall,
+        ...devPackages !== void 0 ? { devPackages } : {},
+        ...scripts !== void 0 ? { scripts } : {},
+        ...targetDir !== void 0 ? { targetDir } : {}
+      });
+      const statusLine = result.success ? `\u2705 package.json updated: ${result.packageJsonPath}` : `\u274C Failed: ${result.error}`;
+      const lines = [
+        statusLine,
+        "",
+        result.added.length > 0 ? `Added (${result.added.length}): ${result.added.join(", ")}` : "Added: none",
+        result.skipped.length > 0 ? `Skipped/already present (${result.skipped.length}): ${result.skipped.join(", ")}` : "Skipped: none",
+        result.scriptsAdded.length > 0 ? `Scripts added (${result.scriptsAdded.length}): ${result.scriptsAdded.join(", ")}` : "Scripts added: none",
+        `pnpm install: ${result.installed ? "ran successfully" : result.success && runInstall ? "failed (non-fatal)" : "skipped"}`
+      ];
+      return {
+        content: [
+          {
+            type: "text",
+            text: lines.join("\n")
+          },
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ]
+      };
+    }
+  );
+}
+function setupPackages(opts) {
+  const emptyResult = {
+    added: [],
+    skipped: [],
+    scriptsAdded: [],
+    installed: false,
+    packageJsonPath: ""
+  };
+  try {
+    const cwd = process.cwd();
+    const resolvedTarget = opts.targetDir ? path2.resolve(opts.targetDir) : cwd;
+    const cwdWithSep = cwd.endsWith(path2.sep) ? cwd : cwd + path2.sep;
+    if (resolvedTarget !== cwd && !resolvedTarget.startsWith(cwdWithSep)) {
+      return {
+        success: false,
+        added: [],
+        skipped: [],
+        scriptsAdded: [],
+        installed: false,
+        packageJsonPath: "",
+        // FIX 5 (M-4): do not leak absolute paths in error messages
+        error: `Path traversal rejected: target directory is outside the allowed working directory`
+      };
+    }
+    const preResolvePackageJsonPath = path2.join(resolvedTarget, "package.json");
+    if (!existsSync2(preResolvePackageJsonPath)) {
+      return {
+        success: false,
+        ...emptyResult,
+        error: `No package.json found in ${resolvedTarget}`
+      };
+    }
+    let realTarget;
+    try {
+      realTarget = realpathSync(resolvedTarget);
+    } catch {
+      return {
+        success: false,
+        added: [],
+        skipped: [],
+        scriptsAdded: [],
+        installed: false,
+        packageJsonPath: "",
+        error: `Could not resolve real path of target directory`
+      };
+    }
+    const realCwd = realpathSync(cwd);
+    const realCwdWithSep = realCwd.endsWith(path2.sep) ? realCwd : realCwd + path2.sep;
+    if (realTarget !== realCwd && !realTarget.startsWith(realCwdWithSep)) {
+      return {
+        success: false,
+        added: [],
+        skipped: [],
+        scriptsAdded: [],
+        installed: false,
+        packageJsonPath: "",
+        // FIX 5 (M-4): do not leak absolute paths in error messages
+        error: `Path traversal rejected: target directory resolved to a location outside the allowed working directory`
+      };
+    }
+    const realPackageJsonPath = path2.join(realTarget, "package.json");
+    const pkgStat = lstatSync(realPackageJsonPath);
+    if (pkgStat.isSymbolicLink()) {
+      return {
+        ...emptyResult,
+        success: false,
+        error: `package.json is a symlink \u2014 refusing to read or write`
+      };
+    }
+    const VALID_PKG_NAME_RE = /^(@[a-z0-9][a-z0-9\-._~]*\/)?[a-z0-9][a-z0-9\-._~]*$/;
+    const allPkgNames = [
+      ...Object.keys(opts.packages ?? {}),
+      ...Object.keys(opts.devPackages ?? {})
+    ];
+    for (const pkg of allPkgNames) {
+      if (!VALID_PKG_NAME_RE.test(pkg)) {
+        return {
+          ...emptyResult,
+          success: false,
+          error: `Invalid package name: '${pkg}' \u2014 must match npm package name specification`
+        };
+      }
+    }
+    const SAFE_VERSION_RE = /^(workspace:[*^~]?|\*|latest|next|beta|alpha|canary|rc|[~^><=*|, ]*[\d.x*][\d.x*\-+a-zA-Z.~^><=*|, ]*)$/;
+    const allVersionEntries = [
+      ...Object.entries(opts.packages ?? {}),
+      ...Object.entries(opts.devPackages ?? {})
+    ];
+    for (const [pkg, version] of allVersionEntries) {
+      if (!SAFE_VERSION_RE.test(version.trim())) {
+        return {
+          ...emptyResult,
+          success: false,
+          error: `Unsafe version specifier for '${pkg}': '${version}' \u2014 only semver ranges, workspace:*, and dist-tags (latest/next/beta) are permitted`
+        };
+      }
+    }
+    const BLOCKED_LIFECYCLE_KEYS = /* @__PURE__ */ new Set([
+      "preinstall",
+      "install",
+      "postinstall",
+      "prepare",
+      "prepublish",
+      "prepublishOnly",
+      "prepack",
+      "postpack",
+      "dependencies"
+      // pnpm hook key
+    ]);
+    if (opts.scripts) {
+      for (const key of Object.keys(opts.scripts)) {
+        if (BLOCKED_LIFECYCLE_KEYS.has(key)) {
+          return {
+            ...emptyResult,
+            success: false,
+            error: `Blocked lifecycle script key: '${key}' \u2014 writing npm lifecycle hooks is not permitted`
+          };
+        }
+      }
+    }
+    const raw = readFileSync(realPackageJsonPath, "utf8");
+    const PackageJsonSchema = z6.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()
+    }).passthrough();
+    const schemaResult = PackageJsonSchema.safeParse(JSON.parse(raw));
+    if (!schemaResult.success) {
+      return {
+        ...emptyResult,
+        success: false,
+        error: `Invalid package.json structure: ${schemaResult.error.message}`
+      };
+    }
+    const parsed = schemaResult.data;
+    const added = [];
+    const skipped = [];
+    const scriptsAdded = [];
+    const claimedPkgs = /* @__PURE__ */ new Set([
+      ...Object.keys(parsed.dependencies ?? {}),
+      ...Object.keys(parsed.devDependencies ?? {})
+    ]);
+    parsed.dependencies = parsed.dependencies ?? {};
+    for (const [pkg, version] of Object.entries(opts.packages)) {
+      if (claimedPkgs.has(pkg)) {
+        skipped.push(pkg);
+      } else {
+        parsed.dependencies[pkg] = version;
+        claimedPkgs.add(pkg);
+        added.push(pkg);
+      }
+    }
+    if (opts.devPackages && Object.keys(opts.devPackages).length > 0) {
+      parsed.devDependencies = parsed.devDependencies ?? {};
+      for (const [pkg, version] of Object.entries(opts.devPackages)) {
+        if (claimedPkgs.has(pkg)) {
+          skipped.push(pkg);
+        } else {
+          parsed.devDependencies[pkg] = version;
+          claimedPkgs.add(pkg);
+          added.push(pkg);
+        }
+      }
+    }
+    if (opts.scripts && Object.keys(opts.scripts).length > 0) {
+      parsed.scripts = parsed.scripts ?? {};
+      for (const [key, value] of Object.entries(opts.scripts)) {
+        if (parsed.scripts[key] === void 0) {
+          parsed.scripts[key] = value;
+          scriptsAdded.push(key);
+        }
+      }
+    }
+    writeFileSync(realPackageJsonPath, JSON.stringify(parsed, null, 2) + "\n");
+    let installed = false;
+    let installError;
+    if (opts.runInstall) {
+      try {
+        execSync("pnpm install", { cwd: realTarget, stdio: "pipe", timeout: 6e4 });
+        installed = true;
+      } catch (err) {
+        installed = false;
+        const spawnErr = err;
+        installError = spawnErr.stderr?.toString().trim() || (err instanceof Error ? err.message : "unknown error");
+      }
+    }
+    return {
+      success: true,
+      added,
+      skipped,
+      scriptsAdded,
+      installed,
+      packageJsonPath: realPackageJsonPath,
+      ...installError !== void 0 ? { installError } : {}
+    };
+  } catch (err) {
+    return {
+      ...emptyResult,
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+
+// package.json
+var package_default = {
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "@stackwright-pro/cli-data-explorer": "workspace:*",
+    zod: "^4.3.6"
+  },
+  devDependencies: {
+    "@types/node": "^24.1.0",
+    tsup: "^8.5.0",
+    typescript: "^5.8.3",
+    vitest: "^4.0.18"
+  },
+  scripts: {
+    build: "tsup src/server.ts --format cjs,esm --dts --clean",
+    dev: "tsup src/server.ts --format cjs,esm --dts --watch",
+    start: "node dist/server.js",
+    test: "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  name: "@stackwright-pro/mcp",
+  version: "0.0.0-beta-20260417191149",
+  description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
+  license: "PROPRIETARY",
+  main: "./dist/server.js",
+  module: "./dist/server.mjs",
+  types: "./dist/server.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/server.d.ts",
+      import: "./dist/server.mjs",
+      require: "./dist/server.js"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/server.ts
+var server = new McpServer({
+  name: "stackwright-pro",
+  version: package_default.version
+});
+registerDataExplorerTools(server);
+registerSecurityTools(server);
+registerIsrTools(server);
+registerDashboardTools(server);
+registerClarificationTools(server);
+registerPackageTools(server);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Stackwright Pro MCP server running on stdio");
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=server.mjs.map