@thehammer/schema-mcp-server 1.0.6 → 1.0.8

package/dist/api-client.d.ts

@@ -38,5 +38,24 @@ 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.
+ *
+ * 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,34 @@ export async function submitQualityGateReview(itemId, status, analysis, message)
         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.
+ */
+export async function callQualityGate(category, message) {
+    return apiRequest("POST", mcpPath("quality-gate"), {
+        category,
+        message,
+    });
+}
+/**
+ * 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

@@ -36,7 +36,7 @@ const server = new McpServer({
  *   orchestrator     — Read-only + annotations + context + progress (no mutations)
  *   schema-builder   — Schema mutations + reads (no directives/templates/annotations)
  *   behavior-builder — Directive mutations + reads (no schema/templates/annotations)
- *   template-builder — Template mutations + reads + styles (no schema/directives/annotations)
+ *   template-builder — Template mutations + reads + styles + annotation_create (for missing-field questions)
  *   full (default)   — All tools (backwards compatible, used by reviewer agents)
  */
 const SCHEMA_ROLE = process.env.SCHEMA_ROLE || "full";
@@ -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,
@@ -92,6 +95,7 @@ const ROLE_TOOLS = {
         "template_set_sample_data",
         "quality_gate_submit_review",
         "style_list",
+        "annotation_create", // Question annotations for missing fields → orchestrator decides
     ]),
     reviewer: new Set([
         ...COMMON_TOOLS,
@@ -529,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);
@@ -665,6 +680,36 @@ 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). " +
+        "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.", {
+        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.6",
+  "version": "1.0.8",
   "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
   "license": "MIT",
   "repository": {