@thehammer/schema-mcp-server 1.0.13 → 1.0.15

package/dist/index.js

@@ -14,22 +14,11 @@
  *   SCHEMA_API_TOKEN - Bearer token for SchemaMcpAuthMiddleware
  *   SCHEMA_DEFINITION_ID - ID of the schema being built
  */
-import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as api from "./api-client.js";
-import { assertVersionCurrent } from "./version-check.js";
-const require = createRequire(import.meta.url);
-const pkg = require("../package.json");
-/**
- * Version frozen into memory at module load. Compared against the on-disk
- * package.json before every tool handler runs, so if the server's own
- * installation is updated during runtime (npm publish, npm install,
- * manual replacement) the next tool call halts the process instead of
- * silently serving stale code.
- */
-const LOADED_VERSION = pkg.version;
+import { LOADED_VERSION, assertVersionCurrent } from "./version-check.js";
 const server = new McpServer({
     name: "schema-mcp-server",
     version: LOADED_VERSION,
@@ -44,19 +33,27 @@ const server = new McpServer({
  * then delegates to the original implementation. New tools added in the future
  * are covered automatically — no per-tool bookkeeping required.
  *
- * The check reads package.json via fs.readFileSync + JSON.parse on every call.
- * `require()` would cache the first read and defeat the purpose. Sync fs reads
- * of a ~500-byte file are measured in microseconds, so no caching is needed.
+ * Fail-loud invariants:
+ * - The handler is always the last argument across every current SDK overload.
+ *   A runtime `typeof` guard throws immediately if a future SDK overload
+ *   breaks this assumption — the wrapper never silently wraps the wrong arg.
+ * - `assertVersionCurrent()` reads package.json on every call via
+ *   `fs.readFileSync` (never `require()`, which caches). Sync reads of a
+ *   ~500-byte file are microsecond-scale — no throttling needed.
  */
-const __origTool = server.tool.bind(server);
+const originalTool = server.tool.bind(server);
 server.tool = (...args) => {
     const handlerIdx = args.length - 1;
     const handler = args[handlerIdx];
+    if (typeof handler !== "function") {
+        throw new Error("[schema-mcp-server] server.tool override: expected last argument to be a handler function. SDK overload change detected — rewire the override before continuing.");
+    }
+    const originalHandler = handler;
     args[handlerIdx] = async (...handlerArgs) => {
-        assertVersionCurrent(LOADED_VERSION);
-        return handler(...handlerArgs);
+        assertVersionCurrent();
+        return originalHandler(...handlerArgs);
     };
-    return __origTool(...args);
+    return originalTool(...args);
 };
 /**
  * Role-based tool registration.
@@ -113,7 +110,6 @@ const ROLE_TOOLS = {
         "schema_update_model",
         "schema_remove_model",
         "schema_update_root",
-        "quality_gate_submit_review",
     ]),
     "behavior-builder": new Set([
         ...COMMON_TOOLS,
@@ -121,7 +117,6 @@ const ROLE_TOOLS = {
         "directive_create",
         "directive_update",
         "directive_delete",
-        "quality_gate_submit_review",
     ]),
     "template-builder": new Set([
         ...COMMON_TOOLS,
@@ -130,7 +125,6 @@ const ROLE_TOOLS = {
         "template_update",
         "template_patch",
         "template_set_sample_data",
-        "quality_gate_submit_review",
         "style_list",
         "annotation_create", // Question annotations for missing fields → orchestrator decides
     ]),
@@ -140,6 +134,7 @@ const ROLE_TOOLS = {
         "style_list",
         "context_workflow_inputs",
         "context_workflow_input_pages",
+        "quality_gate_submit_review",
     ]),
 };
 /**
@@ -735,24 +730,33 @@ if (shouldRegister("quality_gate_submit_review"))
         return jsonResult(result);
     });
 if (shouldRegister("quality_gate"))
-    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: " +
+    server.tool("quality_gate", "BLOCKING — dispatch a quality gate reviewer for a single category and wait for the " +
+        "result. This tool does NOT return until the reviewer finishes. Call this for each " +
+        "category you want reviewed (schema, directive, template) — call multiple categories " +
+        "in parallel so they run simultaneously. " +
+        "Response statuses: " +
         "'passed' means all items in the category are green (safe to move on); " +
-        "'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.", {
+        "via an annotation and stop on that category (do NOT retry).", {
         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);
+        let result = await api.callQualityGate(category, message);
+        // Poll until the reviewer finishes — the backend returns 'running'
+        // while a reviewer is in flight. We block here so the orchestrator
+        // agent gets a single tool result with the final verdict instead of
+        // burning dozens of tool calls in a polling loop.
+        while (result &&
+            typeof result === "object" &&
+            "status" in result &&
+            result.status === "running") {
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+            result = await api.callQualityGate(category, message);
+        }
         return jsonResult(result);
     });
 if (shouldRegister("complete"))

package/dist/version-check.d.ts

@@ -1 +1,15 @@
-export declare function assertVersionCurrent(loadedVersion: string): void;
+export declare const LOADED_VERSION: string;
+/**
+ * Halt the process if the on-disk `package.json` version has drifted from
+ * `LOADED_VERSION`.
+ *
+ * Called from the `server.tool` override in `index.ts` before every tool
+ * handler runs. Uses `fs.readFileSync` + `JSON.parse` on every call —
+ * `require()` would cache the first read and defeat the check.
+ *
+ * Side effect: on mismatch (or if the disk read itself fails), writes a
+ * clear error line to stderr and calls `process.exit(1)`. There is no graceful
+ * shutdown window, no retry, no returned error object. The MCP stdio client
+ * sees the disconnect and surfaces it as a dispatch failure.
+ */
+export declare function assertVersionCurrent(): void;

package/dist/version-check.js

@@ -1,20 +1,66 @@
 /**
- * Runtime version check: compares the MCP server's in-memory version to its
- * on-disk package.json and halts the process on mismatch so stale-code runs
- * fail loudly instead of serving old behavior silently.
+ * Runtime version check — single source of truth for the MCP server's version
+ * identity.
  *
- * Wired in once at the top of index.ts via a `server.tool` override — every
- * tool handler runs this check before doing any work. See the override block
- * in index.ts for the single call site.
+ * Owns BOTH:
+ *   1. `LOADED_VERSION`: the version captured into memory the first time this
+ *      module is loaded (one fs read at module load).
+ *   2. `assertVersionCurrent()`: compares the on-disk package.json version to
+ *      `LOADED_VERSION` and halts the process via `process.exit(1)` on
+ *      mismatch so stale-code runs fail loudly instead of serving old behavior
+ *      silently.
+ *
+ * Dist layout assumption: `../package.json` resolves from both
+ * `src/version-check.ts` AND `dist/version-check.js` to `mcp-server/package.json`
+ * because both files live one level below the package root. If tsconfig ever
+ * emits to a nested output dir (e.g. `dist/src/`), this assumption breaks and
+ * must be re-pinned here.
+ *
+ * Wired in once at the top of `index.ts` via a `server.tool` override — every
+ * tool handler runs the assertion before doing any work. See that override
+ * block for the single injection site.
  */
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
-export function assertVersionCurrent(loadedVersion) {
-    const diskVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
-        .version;
-    if (diskVersion !== loadedVersion) {
-        console.error(`[schema-mcp-server] VERSION MISMATCH: loaded v${loadedVersion} in memory, v${diskVersion} on disk. Restart required.`);
+/**
+ * Version frozen into memory at module load. Any later mismatch between this
+ * value and the on-disk `package.json` triggers `assertVersionCurrent()` to
+ * halt the process — there is no recovery path, no graceful shutdown, no retry.
+ *
+ * Read at module load via `fs.readFileSync` (not `require()`, which would
+ * cache the result and make the runtime check always pass). If `package.json`
+ * is missing or malformed at startup, the exception is intentionally
+ * uncaught — fail-loud is the correct behavior before the server even begins
+ * serving requests.
+ */
+const loadedPkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+export const LOADED_VERSION = loadedPkg.version;
+/**
+ * Halt the process if the on-disk `package.json` version has drifted from
+ * `LOADED_VERSION`.
+ *
+ * Called from the `server.tool` override in `index.ts` before every tool
+ * handler runs. Uses `fs.readFileSync` + `JSON.parse` on every call —
+ * `require()` would cache the first read and defeat the check.
+ *
+ * Side effect: on mismatch (or if the disk read itself fails), writes a
+ * clear error line to stderr and calls `process.exit(1)`. There is no graceful
+ * shutdown window, no retry, no returned error object. The MCP stdio client
+ * sees the disconnect and surfaces it as a dispatch failure.
+ */
+export function assertVersionCurrent() {
+    let diskVersion;
+    try {
+        const diskPkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        diskVersion = diskPkg.version;
+    }
+    catch (err) {
+        console.error(`[schema-mcp-server] VERSION CHECK FAILED: unable to read ${pkgPath}. Restart required. Cause:`, err);
+        process.exit(1);
+    }
+    if (diskVersion !== LOADED_VERSION) {
+        console.error(`[schema-mcp-server] VERSION MISMATCH: loaded v${LOADED_VERSION} in memory, v${diskVersion} on disk. Restart required.`);
         process.exit(1);
     }
 }

package/package.json

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