@stackwright-pro/mcp 0.1.1 → 0.2.0-alpha.1

package/dist/server.mjs

@@ -1,10 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -22,8 +15,8 @@ function registerDataExplorerTools(server2) {
     },
     async ({ specPath, projectRoot }) => {
       const result = listEntities({
-        specPath,
-        projectRoot
+        ...specPath !== void 0 && { specPath },
+        ...projectRoot !== void 0 && { projectRoot }
       });
       if (!result.success) {
         return {
@@ -73,8 +66,8 @@ function registerDataExplorerTools(server2) {
     async ({ selectedEntities, excludePatterns, projectRoot }) => {
       const result = generateFilter({
         selectedEntities,
-        excludePatterns,
-        projectRoot: projectRoot || process.cwd()
+        ...excludePatterns !== void 0 && { excludePatterns },
+        projectRoot: projectRoot ?? process.cwd()
       });
       if (!result.success) {
         return {
@@ -94,8 +87,8 @@ function registerDataExplorerTools(server2) {
       lines.push("    endpoints:");
       if (result.filter.include && result.filter.include.length > 0) {
         lines.push("      include:");
-        for (const path2 of result.filter.include) {
-          lines.push(`        - ${path2}`);
+        for (const path3 of result.filter.include) {
+          lines.push(`        - ${path3}`);
         }
       }
       if (result.filter.exclude && result.filter.exclude.length > 0) {
@@ -125,6 +118,7 @@ function registerDataExplorerTools(server2) {
 
 // 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) {
@@ -137,7 +131,7 @@ function registerSecurityTools(server2) {
     },
     async ({ specPath, configPath }) => {
       let securityEnabled = false;
-      let allowlist = [];
+      const allowlist = [];
       const configFile = configPath || path.join(process.cwd(), "stackwright.yml");
       if (fs.existsSync(configFile)) {
         try {
@@ -202,8 +196,7 @@ This spec is not on the approved-specs allowlist. Add it using stackwright_pro_a
       if (!specPath.startsWith("http://") && !specPath.startsWith("https://")) {
         if (fs.existsSync(specPath)) {
           const specContent = fs.readFileSync(specPath, "utf8");
-          const crypto = __require("crypto");
-          const sha256 = crypto.createHash("sha256").update(specContent).digest("hex");
+          const sha256 = createHash("sha256").update(specContent).digest("hex");
           if (sha256 !== matchingSpec.sha256) {
             return {
               content: [
@@ -254,8 +247,7 @@ Status: Valid (${allowlist.length} specs on allowlist)`
           sha256 = "<computed-at-build>";
         } else if (fs.existsSync(url)) {
           const specContent = fs.readFileSync(url, "utf8");
-          const crypto = __require("crypto");
-          sha256 = crypto.createHash("sha256").update(specContent).digest("hex");
+          sha256 = createHash("sha256").update(specContent).digest("hex");
         } else {
           return {
             content: [
@@ -460,7 +452,7 @@ import { listEntities as listEntities2 } from "@stackwright-pro/cli-data-explore
 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 collection_listing, data_table, or stats_grid content types. Use this after stackwright_pro_generate_filter to create pages for your API collections.",
+    "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"),
@@ -489,48 +481,44 @@ function registerDashboardTools(server2) {
       ];
       if (layout === "grid" || layout === "mixed") {
         for (const slug of entities) {
-          yamlLines.push(`    - stats_grid:`);
-          yamlLines.push(`        label: "${slug}-stats"`);
-          yamlLines.push(`        heading:`);
-          yamlLines.push(
-            `          text: "${slug.charAt(0).toUpperCase() + slug.slice(1)} Overview"`
-          );
-          yamlLines.push(`          textSize: "h2"`);
-          yamlLines.push(`        stats:`);
-          yamlLines.push(`          - label: "Total"`);
-          yamlLines.push(`            value: "{{ ${slug}.count }}"`);
-          yamlLines.push(`            icon: "Database"`);
-          yamlLines.push(`        source: "${slug}"`);
-          yamlLines.push(`        background: "surface"`);
+          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(`    - collection_listing:`);
-      yamlLines.push(`        label: "${entities[0]}-listing"`);
-      yamlLines.push(`        heading:`);
+      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(
-        `          text: "${entities.map((e) => e.charAt(0).toUpperCase() + e.slice(1)).join(" & ")}"`
+        `      columns: ${entityDetails[0]?.fields?.slice(0, 4).map((f) => f.name).join(", ") || defaultCols.join(", ")}`
       );
-      yamlLines.push(`          textSize: "h2"`);
-      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(`        background: "background"`);
       yamlLines.push("");
       if (layout === "table") {
-        yamlLines.push(`    - data_table:`);
-        yamlLines.push(`        label: "${entities[0]}-table"`);
-        yamlLines.push(`        heading:`);
-        yamlLines.push(`          text: "Detailed View"`);
-        yamlLines.push(`          textSize: "h3"`);
-        yamlLines.push(`        collection: "${entities[0]}"`);
-        yamlLines.push(`        sortableColumns: true`);
-        yamlLines.push(`        exportable: true`);
-        yamlLines.push(`        background: "surface"`);
+        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 {
@@ -632,15 +620,614 @@ ${yaml}
   );
 }
 
+// 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.2.0-alpha.0",
+  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"
+  ]
+};
+
 // src/server.ts
 var server = new McpServer({
   name: "stackwright-pro",
-  version: "0.1.0"
+  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);