@thehammer/schema-mcp-server 1.0.8 → 1.0.9

package/dist/api-client.d.ts

@@ -38,14 +38,6 @@ export declare function getTemplatePreviewHtml(templateId: number, teamObjectId?
 export declare function getStyleList(): Promise<ApiResponse>;
 export declare function listQualityGateItems(): Promise<ApiResponse>;
 export declare function submitQualityGateReview(itemId: number, status: string, analysis: string, message?: string): Promise<ApiResponse>;
-/**
- * Check (or kick off) quality gate review for a single category.
- *
- * Returns one of: passed (cache hit), running (reviewer dispatched or in flight),
- * failed (items need fixes with analysis). The orchestrator uses this as its
- * primary quality-gate entry point — call once per category when 100% done with
- * that category's work.
- */
 export declare function callQualityGate(category: string, message?: string): Promise<ApiResponse>;
 /**
  * Orchestrator finalization — mandatory last action before exit.

package/dist/api-client.js

@@ -180,16 +180,55 @@ export async function submitQualityGateReview(itemId, status, analysis, message)
 /**
  * Check (or kick off) quality gate review for a single category.
  *
- * Returns one of: passed (cache hit), running (reviewer dispatched or in flight),
- * failed (items need fixes with analysis). The orchestrator uses this as its
- * primary quality-gate entry point — call once per category when 100% done with
- * that category's work.
+ * BLOCKING BY DESIGN. This call dispatches a reviewer (if one isn't already
+ * running) and then polls the backend until the gate for that category reaches
+ * a terminal state (`passed`, `failed`, or `error`). The agent sees exactly
+ * one call per category — no polling loop in agent context, no wasted context
+ * on intermediate `running` responses.
+ *
+ * Returns one of:
+ * - `passed` — all items green (cache hit or fresh review)
+ * - `failed` — items need fixes (with `analysis`)
+ * - `error`  — a prior reviewer dispatch failed at this iteration; manual
+ *   intervention needed (the agent must surface this to the user)
+ *
+ * Polling cadence: POLL_INTERVAL_MS between requests, capped at MAX_POLL_MS
+ * total wall time. If the cap is reached the function returns a synthetic
+ * `timeout` status so the agent doesn't hang forever.
  */
+const QUALITY_GATE_POLL_INTERVAL_MS = 3_000;
+const QUALITY_GATE_MAX_POLL_MS = 15 * 60 * 1_000; // 15 minutes
 export async function callQualityGate(category, message) {
-    return apiRequest("POST", mcpPath("quality-gate"), {
-        category,
-        message,
-    });
+    const terminal = new Set(["passed", "failed", "error", "timeout"]);
+    const deadline = Date.now() + QUALITY_GATE_MAX_POLL_MS;
+    let attempt = 0;
+    while (true) {
+        attempt += 1;
+        // Only pass the agent-authored message on the FIRST call — subsequent
+        // polls are internal and shouldn't spam the backend logs with duplicates.
+        const body = { category };
+        if (attempt === 1 && message) {
+            body.message = message;
+        }
+        const result = await apiRequest("POST", mcpPath("quality-gate"), body);
+        const status = String(result.status ?? "");
+        if (terminal.has(status)) {
+            return result;
+        }
+        if (status !== "running") {
+            // Unknown status — surface it verbatim so bugs are loud rather
+            // than swallowed by the polling loop.
+            return result;
+        }
+        if (Date.now() >= deadline) {
+            return {
+                ...result,
+                status: "timeout",
+                message: `quality_gate(${category}) did not reach a terminal state within ${QUALITY_GATE_MAX_POLL_MS / 1000}s. The reviewer dispatch may be stuck — check dispatch status and retry.`,
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, QUALITY_GATE_POLL_INTERVAL_MS));
+    }
 }
 /**
  * Orchestrator finalization — mandatory last action before exit.

package/dist/index.js

@@ -682,13 +682,19 @@ if (shouldRegister("quality_gate_submit_review"))
     });
 if (shouldRegister("quality_gate"))
     server.tool("quality_gate", "Run the quality gate for a single category (schema, directive, or template). " +
-        "Call this when you are 100% done with that category's work — it either returns cached " +
-        "results instantly or dispatches a reviewer. Response statuses: " +
-        "'passed' means all items in the category are green (safe to move on); " +
-        "'running' means a reviewer is in flight — do other useful work and call again later; " +
-        "'failed' means items need fixes — read each item's `analysis`, apply fixes via mutation " +
-        "tools (which auto-invalidate the category), then re-call this tool. " +
-        "You may call this for different categories in parallel while sub-agents are running.", {
+        "BLOCKING — this call dispatches a reviewer (if one isn't already running) and waits " +
+        "until the gate reaches a terminal state. You receive ONE response per call: never " +
+        "poll the same category repeatedly. Response statuses: " +
+        "'passed' means all items are green (safe to move on); " +
+        "'failed' means items need fixes — read each item's `analysis`, apply fixes via " +
+        "mutation tools (which auto-invalidate the category), then call this tool again; " +
+        "'error' means the reviewer dispatch itself failed — surface the error to the user " +
+        "and stop (do NOT retry the same category); " +
+        "'timeout' means the call hit its 15-minute wall-time cap — the reviewer may be " +
+        "stuck, report it and move on. " +
+        "Parallelism is still available via concurrent tool calls for DIFFERENT categories " +
+        "(e.g. schema + directive in parallel). Do NOT call this tool twice for the same " +
+        "category before the first call returns.", {
         category: z
             .enum(["schema", "directive", "template"])
             .describe("The quality gate category to check. Must be one of: schema, directive, template."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/schema-mcp-server",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
   "license": "MIT",
   "repository": {