@thehammer/schema-mcp-server 1.0.8 → 1.0.10

package/dist/api-client.d.ts

@@ -41,10 +41,27 @@ export declare function submitQualityGateReview(itemId: number, status: string,
 /**
  * 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.
+ * NON-BLOCKING. A single HTTP round-trip. The agent NEVER waits inside MCP —
+ * blocking hides dispatch failures behind timeouts and ties up the agent when
+ * it could be doing other productive work.
+ *
+ * Returns one of:
+ * - `passed`  — all items green (cache hit or fresh review)
+ * - `failed`  — items need fixes; response includes each item's `analysis`
+ * - `running` — a reviewer is dispatched (or already in flight); call again later
+ * - `error`   — a prior reviewer dispatch failed at this iteration; manual
+ *   intervention needed. Do NOT retry on this category; surface to the user
+ *   via an annotation.
+ *
+ * Recommended pattern:
+ *   1. Call `quality_gate(A)` — reviewer is launched by the backend on the
+ *      first running-with-pending-items response
+ *   2. Do other productive work (work on other categories, read annotations,
+ *      preview templates, call `quality_gate(B)` in parallel)
+ *   3. Call `quality_gate(A)` again later to poll. The backend is idempotent:
+ *      won't launch a second reviewer while the first is running.
+ *   4. When the agent has no other productive work, it still polls — each poll
+ *      is cheap, short, and carries minimal context.
  */
 export declare function callQualityGate(category: string, message?: string): Promise<ApiResponse>;
 /**

package/dist/api-client.js

@@ -180,10 +180,27 @@ 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.
+ * NON-BLOCKING. A single HTTP round-trip. The agent NEVER waits inside MCP —
+ * blocking hides dispatch failures behind timeouts and ties up the agent when
+ * it could be doing other productive work.
+ *
+ * Returns one of:
+ * - `passed`  — all items green (cache hit or fresh review)
+ * - `failed`  — items need fixes; response includes each item's `analysis`
+ * - `running` — a reviewer is dispatched (or already in flight); call again later
+ * - `error`   — a prior reviewer dispatch failed at this iteration; manual
+ *   intervention needed. Do NOT retry on this category; surface to the user
+ *   via an annotation.
+ *
+ * Recommended pattern:
+ *   1. Call `quality_gate(A)` — reviewer is launched by the backend on the
+ *      first running-with-pending-items response
+ *   2. Do other productive work (work on other categories, read annotations,
+ *      preview templates, call `quality_gate(B)` in parallel)
+ *   3. Call `quality_gate(A)` again later to poll. The backend is idempotent:
+ *      won't launch a second reviewer while the first is running.
+ *   4. When the agent has no other productive work, it still polls — each poll
+ *      is cheap, short, and carries minimal context.
  */
 export async function callQualityGate(category, message) {
     return apiRequest("POST", mcpPath("quality-gate"), {

package/dist/index.js

@@ -681,14 +681,18 @@ if (shouldRegister("quality_gate_submit_review"))
         return jsonResult(result);
     });
 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: " +
+    server.tool("quality_gate", "Dispatch or poll the quality gate for a single category (schema, directive, or template). " +
+        "NON-BLOCKING — the call returns immediately. 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.", {
+        "'running' means a reviewer was dispatched (or one is already in flight) — do other " +
+        "productive work, then call this tool again later to check status; " +
+        "'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 " +
+        "via an annotation and stop on that category (do NOT retry). " +
+        "You may call this for multiple categories in parallel. The backend is idempotent — " +
+        "calling while a reviewer is running returns 'running' without launching a duplicate. " +
+        "When you have no other productive work, continue polling — each call is cheap.", {
         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.10",
   "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
   "license": "MIT",
   "repository": {