@thehammer/schema-mcp-server 1.0.7 → 1.0.9

package/dist/api-client.d.ts

@@ -38,5 +38,16 @@ 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>;
+export declare function callQualityGate(category: string, message?: string): Promise<ApiResponse>;
+/**
+ * Orchestrator finalization — mandatory last action before exit.
+ *
+ * Returns {ok: true} when every outstanding check has cleared, transitioning the
+ * dispatch to completed. Returns {ok: false, outstanding: [...]} when any category
+ * is pending, any item failed, any template has validation_errors, or any directive
+ * has meta.selector_mismatches / meta.extraction_coverage_errors. In the non-empty
+ * case, the dispatch stays running so the agent can fix the issues and re-call.
+ */
+export declare function completeDispatch(message?: string): Promise<ApiResponse>;
 export declare function postProgress(progressMessage: string, phase?: string): Promise<ApiResponse>;
 export { SCHEMA_ID };

package/dist/api-client.js

@@ -177,6 +177,73 @@ export async function submitQualityGateReview(itemId, status, analysis, message)
         message,
     });
 }
+/**
+ * Check (or kick off) quality gate review for a single category.
+ *
+ * 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) {
+    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.
+ *
+ * Returns {ok: true} when every outstanding check has cleared, transitioning the
+ * dispatch to completed. Returns {ok: false, outstanding: [...]} when any category
+ * is pending, any item failed, any template has validation_errors, or any directive
+ * has meta.selector_mismatches / meta.extraction_coverage_errors. In the non-empty
+ * case, the dispatch stays running so the agent can fix the issues and re-call.
+ */
+export async function completeDispatch(message) {
+    return apiRequest("POST", mcpPath("complete"), {
+        message,
+    });
+}
 export async function postProgress(progressMessage, phase) {
     return apiRequest("POST", mcpPath("progress"), {
         message: progressMessage,

package/dist/index.js

@@ -66,6 +66,9 @@ const ROLE_TOOLS = {
         "context_workflow_inputs",
         "context_workflow_input_pages",
         "context_chat_history",
+        // Agent-driven quality gate lifecycle (orchestrator-only)
+        "quality_gate",
+        "complete",
     ]),
     "schema-builder": new Set([
         ...COMMON_TOOLS,
@@ -530,12 +533,23 @@ if (shouldRegister("template_create"))
         return jsonResult(result);
     });
 if (shouldRegister("template_list"))
-    server.tool("template_list", "List all template definitions for the current schema", {}, async () => {
+    server.tool("template_list", "List all template definitions for the current schema. " +
+        "Each template includes a `validation_errors` field — when non-null it indicates unresolved " +
+        "coherence-check failures (field_warnings, style_warnings, meta_warnings, region_warnings, " +
+        "formatter_warnings, required_warnings) from the most recent mutation. Orchestrators do not " +
+        "need to poll this — `complete` automatically surfaces template validation errors as " +
+        "`template_errors` in its outstanding list.", {}, async () => {
         const result = await api.listTemplates();
         return jsonResult(result);
     });
 if (shouldRegister("template_get"))
-    server.tool("template_get", "Get full details of a template definition including template_json", {
+    server.tool("template_get", "Get full details of a template definition including template_json. " +
+        "The response includes a `validation_errors` field — when non-null it indicates unresolved " +
+        "coherence-check failures (field_warnings, style_warnings, meta_warnings, region_warnings, " +
+        "formatter_warnings, required_warnings). Template-builder sub-agents should inspect this field " +
+        "after their own mutations to self-correct before handing work back. Orchestrators do not need " +
+        "to poll this — `complete` automatically surfaces template validation errors in its " +
+        "outstanding list.", {
         template_id: z.number().describe("ID of the template to fetch"),
     }, async ({ template_id }) => {
         const result = await api.getTemplateDetails(template_id);
@@ -666,6 +680,42 @@ if (shouldRegister("quality_gate_submit_review"))
         const result = await api.submitQualityGateReview(quality_gate_item_id, status, analysis, message);
         return jsonResult(result);
     });
+if (shouldRegister("quality_gate"))
+    server.tool("quality_gate", "Run the quality gate for a single category (schema, directive, or template). " +
+        "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."),
+        message: messageParam,
+    }, async ({ category, message }) => {
+        const result = await api.callQualityGate(category, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("complete"))
+    server.tool("complete", "MANDATORY final action — call this to finalize your dispatch. Aggregates every known " +
+        "failure surface (pending quality gate categories, failed items, template validation " +
+        "errors, directive meta errors) and either transitions your dispatch to completed " +
+        "when everything is clean (returns {ok: true}) or returns {ok: false, outstanding: [...]} " +
+        "listing exactly what still needs fixing. When outstanding is non-empty, work through " +
+        "each item and call this tool again. Do NOT exit your session without calling this tool " +
+        "successfully — your dispatch will be marked dead by the heartbeat watchdog instead.", {
+        message: messageParam,
+    }, async ({ message }) => {
+        const result = await api.completeDispatch(message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Style Library Tools (read-only)
 // ============================================================================

package/package.json

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