@stackwright-pro/mcp 0.2.0-alpha.111 → 0.2.0-alpha.113

package/dist/server.mjs

@@ -556,7 +556,7 @@ function registerDashboardTools(server2) {
         yamlLines.push(`          header: Status`);
         yamlLines.push(`          type: badge`);
       }
-      const yaml3 = yamlLines.join("\n");
+      const yaml4 = yamlLines.join("\n");
       return {
         content: [
           {
@@ -566,7 +566,7 @@ function registerDashboardTools(server2) {
 Layout: ${layout}
 
 \`\`\`yaml
-${yaml3}
+${yaml4}
 \`\`\`
 
 \u{1F4A1} Add this to pages/dashboard/content.yml and validate with stackwright_validate_pages.`
@@ -647,7 +647,7 @@ ${yaml3}
       yamlLines.push("          action: navigate");
       yamlLines.push(`          href: "/${entity}"`);
       yamlLines.push("          style: secondary");
-      const yaml3 = yamlLines.join("\n");
+      const yaml4 = yamlLines.join("\n");
       return {
         content: [
           {
@@ -655,7 +655,7 @@ ${yaml3}
             text: `\u{1F4C4} Generated Detail Page for: ${entity}
 
 \`\`\`yaml
-${yaml3}
+${yaml4}
 \`\`\`
 
 \u{1F4A1} Add this to pages/${entity}/[${slugField}]/content.yml and validate.`
@@ -2826,21 +2826,40 @@ function readAllManifestPages(artifactsDir) {
     return allPages;
   }
   for (const entry of entries) {
-    if (!entry.endsWith("-manifest.json")) continue;
-    const filePath = join5(artifactsDir, entry);
-    try {
-      const raw = JSON.parse(readFileSync5(filePath, "utf-8"));
-      if (!Array.isArray(raw.pages)) continue;
-      for (const page of raw.pages) {
-        if (typeof page.slug !== "string" || !page.slug) continue;
+    if (entry.endsWith("-manifest.json")) {
+      const filePath = join5(artifactsDir, entry);
+      try {
+        const raw = JSON.parse(readFileSync5(filePath, "utf-8"));
+        if (!Array.isArray(raw.pages)) continue;
+        for (const page of raw.pages) {
+          if (typeof page.slug !== "string" || !page.slug) continue;
+          allPages.push({
+            slug: page.slug,
+            authRequired: page.authRequired,
+            requiredRoles: page.requiredRoles,
+            source: entry
+          });
+        }
+      } catch {
+      }
+      continue;
+    }
+    if (entry === "workflow-config.json" || entry.startsWith("workflow-config-")) {
+      const filePath = join5(artifactsDir, entry);
+      try {
+        const raw = JSON.parse(readFileSync5(filePath, "utf-8"));
+        const route = raw.workflow?.route;
+        if (typeof route !== "string" || !route) continue;
+        const slug = route.startsWith("/") ? route.slice(1) : route;
         allPages.push({
-          slug: page.slug,
-          authRequired: page.authRequired,
-          requiredRoles: page.requiredRoles,
+          slug,
+          authRequired: true,
+          requiredRoles: void 0,
           source: entry
         });
+      } catch {
       }
-    } catch {
+      continue;
     }
   }
   return allPages;
@@ -2848,7 +2867,7 @@ function readAllManifestPages(artifactsDir) {
 function registerReadAuthManifestsTool(server2) {
   server2.tool(
     "stackwright_pro_read_auth_manifests",
-    "Read ALL *-manifest.json files from the pipeline artifacts directory (pages-manifest.json, dashboard-manifest.json, geo-manifest.json, etc.) and deterministically derive protectedRoutes and uncoveredSlugs. Uses the both-forms invariant (swp-n7kk): every authRequired route registers BOTH /{slug} (exact) AND /{slug}/:path* (sub-path). Call this in Step 1 of auth configuration instead of manually reading each manifest file. Fixes the Bead C issue where dashboard-manifest.json and geo-manifest.json were silently missed.",
+    "Read ALL route-producing artifacts from the pipeline artifacts directory: *-manifest.json files (pages, dashboard, geo, form-wizard) AND workflow-config.json / workflow-config-*.json (different shape: workflow.route). Deterministically derives protectedRoutes and uncoveredSlugs. Uses the both-forms invariant (swp-n7kk): every authRequired route registers BOTH /{slug} (exact) AND /{slug}/:path* (sub-path). Workflow routes appear in uncoveredSlugs (no requiredRoles declared) for auth-reconcile to resolve via cross-cutting rules from auth-config.json. Extended by swp-hng0 to cover all four manifest types (was: pages+dashboard only).",
     {
       rbacRoles: z11.array(z11.string()).describe(
         'RBAC role hierarchy in descending privilege order, e.g. ["ESF8_COORDINATOR", "HOSPITAL_EM", "OBSERVER"]. Used to compute the lowestRole for each authRequired page.'
@@ -2994,7 +3013,7 @@ function enrichErrors(issues, synonyms) {
   });
 }
 function handleValidateYamlFragment(input) {
-  const { schemaName, yaml: yaml3 } = input;
+  const { schemaName, yaml: yaml4 } = input;
   if (!SUPPORTED_SCHEMA_NAMES.includes(schemaName)) {
     return {
       valid: false,
@@ -3004,7 +3023,7 @@ function handleValidateYamlFragment(input) {
   const name = schemaName;
   let parsed;
   try {
-    parsed = yamlLoad2(yaml3);
+    parsed = yamlLoad2(yaml4);
   } catch (err) {
     return {
       valid: false,
@@ -3030,8 +3049,8 @@ function registerValidateYamlFragmentTool(server2) {
       ),
       yaml: z12.string().describe("YAML string to validate (can also be JSON \u2014 js-yaml parses both)")
     },
-    async ({ schemaName, yaml: yaml3 }) => {
-      const result = handleValidateYamlFragment({ schemaName, yaml: yaml3 });
+    async ({ schemaName, yaml: yaml4 }) => {
+      const result = handleValidateYamlFragment({ schemaName, yaml: yaml4 });
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
@@ -3244,6 +3263,9 @@ var MANIFEST_NAME_TO_PHASE = {
   "stackwright-pro-dashboard-otter": "dashboard",
   "stackwright-pro-form-wizard-otter": "workflow",
   "stackwright-pro-geo-otter": "geo",
+  // auth-reconcile runs AFTER pages+dashboard+geo+workflow (wave 6)
+  // Reads auth-config.json + all four manifests; emits auth-reconcile-config.json + stackwright.auth.yml
+  "stackwright-pro-auth-reconcile-otter": "auth-reconcile",
   "stackwright-pro-polish-otter": "polish",
   "stackwright-services-otter": "services",
   "stackwright-pro-qa-otter": "qa"
@@ -3459,13 +3481,19 @@ var PHASE_ORDER = [
   "api",
   "data",
   "auth",
-  // moved earlier — only depends on design-language.json (designer)
+  // wave 2 — moved earlier, only depends on design-language.json (designer)
   "geo",
   "workflow",
   "services",
   "pages",
   "dashboard",
+  // auth-reconcile: wave 6 — post-manifest reconciliation
+  // Reads auth-config.json + pages/dashboard/geo/workflow manifests;
+  // emits auth-reconcile-config.json + stackwright.auth.yml (Gate 4 single source of truth)
+  "auth-reconcile",
+  // wave 7: polish — depends on auth-reconcile (replaces auth-config.json direct dep)
   "polish",
+  // wave 8: qa — terminal QA gate, depends on polish + transitively everything
   "qa"
 ];
 var PHASE_ARTIFACT = {
@@ -3479,6 +3507,7 @@ var PHASE_ARTIFACT = {
   dashboard: "dashboard-manifest.json",
   workflow: "workflow-config.json",
   services: "services-config.json",
+  "auth-reconcile": "auth-reconcile-config.json",
   polish: "polish-manifest.json",
   geo: "geo-manifest.json",
   qa: "qa-findings.json"
@@ -3493,16 +3522,36 @@ var PHASE_TO_OTTER2 = {
   pages: "stackwright-pro-page-otter",
   dashboard: "stackwright-pro-dashboard-otter",
   workflow: "stackwright-pro-form-wizard-otter",
+  "auth-reconcile": "stackwright-pro-auth-reconcile-otter",
   services: "stackwright-services-otter",
   polish: "stackwright-pro-polish-otter",
   geo: "stackwright-pro-geo-otter",
   qa: "stackwright-pro-qa-otter"
 };
+var AUTO_EXECUTE_PHASES = /* @__PURE__ */ new Set(["auth-reconcile"]);
+var PhaseStatusSchema = z14.object({
+  status: z14.enum(["pending", "running", "completed", "skipped", "failed"]).default("pending"),
+  questionsCollected: z14.boolean().default(false),
+  answered: z14.boolean().default(false),
+  executed: z14.boolean().default(false),
+  artifactWritten: z14.boolean().default(false),
+  retryCount: z14.number().default(0),
+  inFlight: z14.boolean().default(false)
+});
+var PipelineStateSchema = z14.object({
+  version: z14.literal("1.0"),
+  currentPhase: z14.string(),
+  status: z14.enum(["setup", "questions", "execution", "done"]),
+  phases: z14.record(z14.string(), PhaseStatusSchema),
+  startedAt: z14.string(),
+  updatedAt: z14.string()
+});
 function isValidPhase2(phase) {
   return PHASE_ORDER.includes(phase);
 }
 function defaultPhaseStatus() {
   return {
+    status: "pending",
     questionsCollected: false,
     answered: false,
     executed: false,
@@ -3533,10 +3582,9 @@ function readState(cwd) {
   const p = statePath(cwd);
   if (!existsSync7(p)) return createDefaultState();
   const raw = JSON.parse(safeReadSync(p));
-  if (typeof raw !== "object" || raw === null || raw.version !== "1.0") {
-    return createDefaultState();
-  }
-  return raw;
+  const result = PipelineStateSchema.safeParse(raw);
+  if (!result.success) return createDefaultState();
+  return result.data;
 }
 function safeWriteSync(filePath, content) {
   if (existsSync7(filePath)) {
@@ -3625,13 +3673,16 @@ function handleSetPipelineState(input) {
       isError: true
     };
   }
-  const VALID_FIELDS = [
-    "questionsCollected",
-    "answered",
-    "executed",
-    "artifactWritten",
-    "inFlight"
-  ];
+  if (input.field === "artifactWritten") {
+    return {
+      text: JSON.stringify({
+        error: true,
+        message: "Cannot set 'artifactWritten' directly. Use stackwright_pro_validate_artifact instead \u2014 it verifies the file exists on disk before flagging."
+      }),
+      isError: true
+    };
+  }
+  const VALID_FIELDS = ["questionsCollected", "answered", "executed", "inFlight"];
   if (input.field && !VALID_FIELDS.includes(input.field)) {
     return {
       text: JSON.stringify({
@@ -3652,6 +3703,15 @@ function handleSetPipelineState(input) {
           isError: true
         };
       }
+      if (update.field === "artifactWritten") {
+        return {
+          text: JSON.stringify({
+            error: true,
+            message: "Cannot set 'artifactWritten' directly. Use stackwright_pro_validate_artifact instead \u2014 it verifies the file exists on disk before flagging."
+          }),
+          isError: true
+        };
+      }
       if (!VALID_FIELDS.includes(update.field)) {
         return {
           text: JSON.stringify({
@@ -3677,6 +3737,9 @@ function handleSetPipelineState(input) {
         if (input.field && input.value !== void 0) {
           phaseState[input.field] = input.value;
         }
+        if (input.phaseStatus !== void 0) {
+          phaseState.status = input.phaseStatus;
+        }
         if (input.incrementRetry) {
           phaseState.retryCount += 1;
         }
@@ -3703,16 +3766,6 @@ function handleSetPipelineState(input) {
         },
         { cwd }
       );
-      if (input.field === "artifactWritten" && input.value === true && input.phase) {
-        emit({ type: "phase_complete", phase: input.phase }, { cwd });
-      }
-      if (input.updates) {
-        for (const update of input.updates) {
-          if (update.field === "artifactWritten" && update.value === true) {
-            emit({ type: "phase_complete", phase: update.phase }, { cwd });
-          }
-        }
-      }
     } catch {
     }
     return { text: JSON.stringify(state), isError: false };
@@ -3732,6 +3785,9 @@ function handleCheckExecutionReady(_cwd, phase) {
         isError: true
       };
     }
+    if (AUTO_EXECUTE_PHASES.has(phase)) {
+      return { text: JSON.stringify({ ready: true, phase, autoExecute: true }), isError: false };
+    }
     const answerFile = join7(cwd, ".stackwright", "answers", `${phase}.json`);
     if (!existsSync7(answerFile)) {
       return {
@@ -3761,6 +3817,10 @@ function handleCheckExecutionReady(_cwd, phase) {
     const answeredPhases = [];
     const missingPhases = [];
     for (const phase2 of PHASE_ORDER) {
+      if (AUTO_EXECUTE_PHASES.has(phase2)) {
+        answeredPhases.push(phase2);
+        continue;
+      }
       const answerFile = join7(answersDir, `${phase2}.json`);
       if (existsSync7(answerFile)) {
         try {
@@ -4089,6 +4149,8 @@ var PHASE_REQUIRED_KEYS = {
   dashboard: ["version", "generatedBy"],
   workflow: ["version", "generatedBy"],
   services: ["version", "generatedBy", "flows"],
+  // auth-reconcile: must have version, generatedBy, and merged protectedRoutes
+  "auth-reconcile": ["version", "generatedBy", "protectedRoutes"],
   polish: ["version", "generatedBy"],
   geo: ["version", "generatedBy", "geoCollections"],
   // qa: skipped=true path only needs version+generatedBy+skipped;
@@ -4368,6 +4430,28 @@ var PHASE_ARTIFACT_SCHEMA = {
     null,
     2
   ),
+  "auth-reconcile": JSON.stringify(
+    {
+      version: "1.0",
+      generatedBy: "stackwright-pro-auth-reconcile-otter",
+      authType: "<oidc|saml|cac|oauth2>",
+      rbacRoles: ["<HIGHEST_ROLE>", "<MID_ROLE>", "<LOWEST_ROLE>"],
+      rbacDefaultRole: "<LOWEST_ROLE>",
+      protectedRoutes: [
+        { pattern: "/dashboard", requiredRole: "<role>" },
+        { pattern: "/dashboard/:path*", requiredRole: "<role>" }
+      ],
+      uncoveredSlugs: [],
+      manifestsRead: ["pages-manifest.json", "dashboard-manifest.json", "geo-manifest.json"],
+      summary: {
+        totalRoutes: 2,
+        manifestDerived: 2,
+        crossCutting: 0
+      }
+    },
+    null,
+    2
+  ),
   polish: JSON.stringify(
     {
       version: "1.0",
@@ -4791,6 +4875,7 @@ function _validateArtifactInner(input) {
       if (!state.phases[phase]) state.phases[phase] = defaultPhaseStatus();
       const ps = state.phases[phase];
       ps.artifactWritten = true;
+      ps.status = "completed";
     });
     const topKeys = Object.keys(artifact).slice(0, 5).join(", ");
     const result = {
@@ -4818,6 +4903,7 @@ function handleValidateArtifact(input) {
     const parsed = JSON.parse(result.text);
     if (parsed.valid === true && parsed.artifactPath) {
       emit({ type: "file_write", path: parsed.artifactPath, phase }, { cwd });
+      emit({ type: "phase_complete", phase }, { cwd });
     }
     emit(
       {
@@ -4918,12 +5004,19 @@ function registerPipelineTools(server2) {
     `Atomic read\u2192modify\u2192write pipeline state. ${DESC}`,
     {
       phase: z14.string().optional().describe('Phase to update, e.g. "designer"'),
-      field: z14.enum(["questionsCollected", "answered", "executed", "artifactWritten", "inFlight"]).optional().describe("Boolean field to set"),
+      field: z14.enum(["questionsCollected", "answered", "executed", "inFlight"]).optional().describe(
+        "Boolean field to set. NOTE: artifactWritten is intentionally absent \u2014 use stackwright_pro_validate_artifact instead (it verifies the file exists on disk before flagging)."
+      ),
       // inFlight: set true BEFORE specialist invoke (dataflow mode, swp-ioc7); false after.
       value: boolCoerce(z14.boolean().optional()).describe(
         'Value for the field \u2014 must be a JSON boolean (true/false), NOT the string "true"/"false"'
       ),
-      status: z14.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
+      // phaseStatus: per-phase execution enum — DISTINCT from top-level `status` (pipeline flow).
+      // Named `phaseStatus` to avoid ambiguity. Sets PhaseStatus.status on the given phase.
+      phaseStatus: z14.enum(["pending", "running", "completed", "skipped", "failed"]).optional().describe(
+        "Per-phase execution status (pending/running/completed/skipped/failed). Distinct from top-level `status` (pipeline flow). Use phaseStatus: 'skipped' when a specialist otter is unregistered."
+      ),
+      status: z14.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level pipeline flow status override \u2014 distinct from phaseStatus"),
       incrementRetry: boolCoerce(z14.boolean().optional()).describe(
         "Bump retryCount by 1 \u2014 must be a JSON boolean"
       ),
@@ -4935,8 +5028,8 @@ function registerPipelineTools(server2) {
               "questionsCollected",
               "answered",
               "executed",
-              "artifactWritten",
               "inFlight"
+              // artifactWritten intentionally absent — use validate_artifact (swp-og9c)
             ]),
             value: z14.boolean()
           })
@@ -4948,6 +5041,7 @@ function registerPipelineTools(server2) {
         ...args.phase != null ? { phase: args.phase } : {},
         ...args.field != null ? { field: args.field } : {},
         ...args.value != null ? { value: args.value } : {},
+        ...args.phaseStatus != null ? { phaseStatus: args.phaseStatus } : {},
         ...args.status != null ? { status: args.status } : {},
         ...args.incrementRetry != null ? { incrementRetry: args.incrementRetry } : {},
         ...args.updates != null ? { updates: args.updates } : {}
@@ -5109,6 +5203,20 @@ var OTTER_WRITE_ALLOWLISTS = {
       description: "Stackwright config (themeName + customTheme writeback)"
     }
   ],
+  // swp-hng0: auth-reconcile otter — reads all manifests, re-emits auth-reconcile-config.json
+  // AND overwrites stackwright.auth.yml (Gate 4: single source of truth after reconciliation)
+  "stackwright-pro-auth-reconcile-otter": [
+    {
+      prefix: ".stackwright/artifacts/",
+      suffix: ".json",
+      description: "Auth reconcile artifact (auth-reconcile-config.json)"
+    },
+    {
+      prefix: "stackwright.auth.",
+      suffix: ".yml",
+      description: "Canonical auth sidecar (stackwright.auth.yml \u2014 Gate 4 rewrite)"
+    }
+  ],
   "stackwright-pro-auth-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Auth config artifact" },
     {
@@ -6532,7 +6640,11 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "eee511fa214203ce88d51996c6b1b483b6ad3a0ae474cc7be5d380fdbbc43bb1"
+    "c9302132ac4180c70dd452814eb4aa4fb9a1d6a9683f6e01ffce509a6001c6cf"
+  ],
+  [
+    "stackwright-pro-auth-reconcile-otter.json",
+    "7ffd67d51568c7b2a1eb2ea0ac2b2a8041eb9ddd9c1eb5b95744e55ba049b385"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
@@ -6540,7 +6652,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-data-otter.json",
-    "be4e3d6f530ae2d6b79d6412e8d2d6defb3caffddedf5be4f928976a72206074"
+    "7d1de846488d84eebf8798aef4d75f4f4d250c1ae070ce1200ead3bb8a545eaf"
   ],
   [
     "stackwright-pro-designer-otter.json",
@@ -6552,7 +6664,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "88c4101154d44a7c5470ded13562402a39323ee570ed3a90a73b8d85d7fd2817"
+    "65aa3273274b2b1859d432c3d1166c4a73971861036bf18c35acd8a5357fcf26"
   ],
   [
     "stackwright-pro-form-wizard-otter.json",
@@ -6568,7 +6680,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "4b8223d89af7f92b9051fee7bb29fc4b1ee2a5a9ab87e8e67a6d8be6122fa029"
+    "3ae1252a60727ebca67e33a807d5061cafb88de52f3b98a9d4641f9db725a6ed"
   ],
   [
     "stackwright-pro-qa-otter.json",
@@ -8482,12 +8594,181 @@ function registerListSpecsTool(server2) {
   );
 }
 
-// src/tools/consolidate-integrations.ts
+// src/tools/describe-endpoint.ts
 import { z as z25 } from "zod";
-import { readdirSync as readdirSync10, readFileSync as readFileSync16, writeFileSync as writeFileSync10, existsSync as existsSync16, mkdirSync as mkdirSync9 } from "fs";
+import { readFileSync as readFileSync16 } from "fs";
+import { extname as extname2 } from "path";
+import yaml2 from "js-yaml";
+function resolveRef(root, ref) {
+  if (!ref.startsWith("#/")) {
+    throw new Error(`[describe_endpoint] External $refs not supported: "${ref}"`);
+  }
+  const parts = ref.slice(2).split("/");
+  let current = root;
+  for (const part of parts) {
+    const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (current == null || typeof current !== "object") {
+      throw new Error(
+        `[describe_endpoint] $ref "${ref}" cannot be resolved \u2014 segment "${key}" not found`
+      );
+    }
+    current = current[key];
+  }
+  if (current == null || typeof current !== "object") {
+    throw new Error(`[describe_endpoint] $ref "${ref}" resolved to a non-object value`);
+  }
+  return current;
+}
+function deref(root, obj) {
+  if (obj == null || typeof obj !== "object") return {};
+  const o = obj;
+  if (typeof o["$ref"] === "string") {
+    const resolved = resolveRef(root, o["$ref"]);
+    return deref(root, resolved);
+  }
+  return o;
+}
+function loadSpec(specPath) {
+  const raw = readFileSync16(specPath, "utf-8");
+  const ext = extname2(specPath).toLowerCase();
+  if (ext === ".json") {
+    return JSON.parse(raw);
+  }
+  const parsed = yaml2.load(raw);
+  if (parsed == null || typeof parsed !== "object") {
+    throw new Error(`[describe_endpoint] Spec file "${specPath}" did not parse to an object`);
+  }
+  return parsed;
+}
+function extractParams(root, pathItem, operation) {
+  const pathLevelRaw = Array.isArray(pathItem["parameters"]) ? pathItem["parameters"] : [];
+  const opLevelRaw = Array.isArray(operation["parameters"]) ? operation["parameters"] : [];
+  const merged = /* @__PURE__ */ new Map();
+  for (const raw of [...pathLevelRaw, ...opLevelRaw]) {
+    const param = deref(root, raw);
+    const name = String(param["name"] ?? "");
+    const inVal = String(param["in"] ?? "");
+    if (name && inVal) {
+      merged.set(`${name}:${inVal}`, param);
+    }
+  }
+  const pathParams = [];
+  const queryParams = [];
+  for (const param of merged.values()) {
+    const inVal = String(param["in"] ?? "");
+    const name = String(param["name"] ?? "");
+    const schema = deref(root, param["schema"] ?? {});
+    if (inVal === "path") {
+      pathParams.push({ name, in: "path", required: true, schema });
+    } else if (inVal === "query") {
+      const required = param["required"] === true;
+      queryParams.push({ name, in: "query", required, schema });
+    }
+  }
+  return { pathParams, queryParams };
+}
+function extractSecurity(root, globalSecurity, operationSecurity) {
+  const securityRequirements = operationSecurity !== void 0 ? operationSecurity : globalSecurity;
+  if (securityRequirements.length === 0) return [];
+  const schemes = root["components"]?.["securitySchemes"];
+  if (!schemes || typeof schemes !== "object") return [];
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const req of securityRequirements) {
+    if (!req || typeof req !== "object") continue;
+    for (const schemeName of Object.keys(req)) {
+      if (seen.has(schemeName)) continue;
+      seen.add(schemeName);
+      const schemeRaw = schemes[schemeName];
+      if (!schemeRaw) continue;
+      const scheme = deref(root, schemeRaw);
+      const type = String(scheme["type"] ?? "unknown");
+      if (type === "apiKey") {
+        const inVal = String(scheme["in"] ?? "header");
+        const paramName = String(scheme["name"] ?? schemeName);
+        result.push({ name: schemeName, type, in: inVal, paramName });
+      } else if (type === "http") {
+        const httpScheme = String(scheme["scheme"] ?? "bearer").toLowerCase();
+        result.push({ name: schemeName, type, in: "bearer", paramName: "Authorization" });
+        void httpScheme;
+      } else if (type === "oauth2") {
+        result.push({ name: schemeName, type, in: "bearer", paramName: "Authorization" });
+      } else if (type === "openIdConnect") {
+        result.push({ name: schemeName, type, in: "bearer", paramName: "Authorization" });
+      } else {
+        result.push({ name: schemeName, type, in: "unknown", paramName: schemeName });
+      }
+    }
+  }
+  return result;
+}
+function handleDescribeEndpoint(input) {
+  const { specPath, path: path5, method } = input;
+  const normalizedMethod = method.toLowerCase();
+  const root = loadSpec(specPath);
+  const globalSecurity = Array.isArray(root["security"]) ? root["security"] : [];
+  const paths = root["paths"];
+  if (!paths) {
+    return { pathParams: [], queryParams: [], security: [] };
+  }
+  const pathItem = deref(root, paths[path5]);
+  if (!pathItem || Object.keys(pathItem).length === 0) {
+    throw new Error(`[describe_endpoint] Path "${path5}" not found in spec "${specPath}"`);
+  }
+  const operation = deref(root, pathItem[normalizedMethod]);
+  if (!operation || Object.keys(operation).length === 0) {
+    throw new Error(
+      `[describe_endpoint] Method "${method.toUpperCase()}" not found at path "${path5}" in spec "${specPath}"`
+    );
+  }
+  const { pathParams, queryParams } = extractParams(root, pathItem, operation);
+  const operationSecurity = Array.isArray(operation["security"]) ? operation["security"] : void 0;
+  const security = extractSecurity(root, globalSecurity, operationSecurity);
+  return { pathParams, queryParams, security };
+}
+function registerDescribeEndpointTool(server2) {
+  server2.tool(
+    "stackwright_pro_describe_endpoint",
+    [
+      "Inspect an OpenAPI 3.0/3.1 spec and return resolved parameter and security details for a",
+      "specific operation. Deterministic \u2014 no LLM. Handles $ref resolution within the spec document.",
+      "",
+      "Returns:",
+      "  pathParams   \u2014 path parameters [{name, in, required, schema}]",
+      "  queryParams  \u2014 query parameters [{name, in, required, schema}]",
+      "  security     \u2014 applicable security schemes [{name, type, in, paramName}]",
+      "",
+      "Used by the data-otter to populate params: entries in stackwright.collections.yml",
+      "from required query params and resolved auth query params (swp-8r8i + swp-1l6l)."
+    ].join("\n"),
+    {
+      specPath: z25.string().describe("Absolute path to the OpenAPI spec file (.yaml, .yml, or .json)"),
+      path: z25.string().describe('The API path to inspect (e.g. "/stations/{stationId}/observations")'),
+      method: z25.string().describe('HTTP method (case-insensitive: "get", "post", "put", etc.)')
+    },
+    async ({ specPath, path: path5, method }) => {
+      try {
+        const result = handleDescribeEndpoint({ specPath, path: path5, method });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/consolidate-integrations.ts
+import { z as z26 } from "zod";
+import { readdirSync as readdirSync10, readFileSync as readFileSync17, writeFileSync as writeFileSync10, existsSync as existsSync16, mkdirSync as mkdirSync9 } from "fs";
 import { lockSync as lockSync2 } from "proper-lockfile";
 import { join as join17, basename as basename3 } from "path";
-import yaml2 from "js-yaml";
+import yaml3 from "js-yaml";
 var BASE_MOCK_PORT = 4011;
 var STRIP_SUFFIXES2 = ["-openapi", "-asyncapi", "-api", "-spec"];
 function deriveNameFromFilename(filename) {
@@ -8520,7 +8801,7 @@ function handleConsolidateIntegrations(input) {
   entries.forEach((filename, index) => {
     let artifact = {};
     try {
-      const raw = readFileSync16(join17(artifactsDir, filename), "utf-8");
+      const raw = readFileSync17(join17(artifactsDir, filename), "utf-8");
       artifact = JSON.parse(raw);
     } catch {
     }
@@ -8557,8 +8838,8 @@ function handleConsolidateIntegrations(input) {
   let existing = {};
   if (existsSync16(integrationsYmlPath)) {
     try {
-      const raw = readFileSync16(integrationsYmlPath, "utf-8");
-      existing = yaml2.load(raw) ?? {};
+      const raw = readFileSync17(integrationsYmlPath, "utf-8");
+      existing = yaml3.load(raw) ?? {};
     } catch {
       existing = {};
     }
@@ -8575,7 +8856,7 @@ function handleConsolidateIntegrations(input) {
   try {
     const header = `# stackwright.integrations.yml \u2014 Auto-generated by stackwright_pro_consolidate_integrations
 `;
-    const body = yaml2.dump(merged, { lineWidth: 120, noRefs: true });
+    const body = yaml3.dump(merged, { lineWidth: 120, noRefs: true });
     writeFileSync10(integrationsYmlPath, header + body, "utf-8");
   } finally {
     release();
@@ -8604,7 +8885,7 @@ function registerConsolidateIntegrationsTool(server2) {
       "no per-spec artifacts are found."
     ].join(" "),
     {
-      projectRoot: z25.string().describe("Absolute path to the project root directory")
+      projectRoot: z26.string().describe("Absolute path to the project root directory")
     },
     async ({ projectRoot }) => {
       try {
@@ -8662,7 +8943,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.111",
+  version: "0.2.0-alpha.113",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -8745,6 +9026,7 @@ registerCompileTools(server);
 registerStripLegacyIntegrationsTool(server);
 registerEmitterTools(server);
 registerListSpecsTool(server);
+registerDescribeEndpointTool(server);
 registerConsolidateIntegrationsTool(server);
 registerContentTypeTools(server);
 registerPageTools(server);