@thehammer/answer-key-mcp-server 1.0.0 → 1.0.1

package/dist/api-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * HTTP client for the gpt-manager answer-key MCP endpoints.
+ *
+ * Every request carries the dispatch's Bearer token for
+ * `AgentDispatchTokenMiddleware`, whose route group pins `dispatchable_type` to
+ * `AnswerKey` — a token minted for any other kind of dispatch is rejected 403
+ * before a controller runs.
+ *
+ * This client is a PURE PROXY. It holds no audit logic of any kind: it does not
+ * decide a verdict, does not compare a value to anything, and never sees an
+ * expected value. All of that lives behind the three endpoints.
+ */
+declare const ANSWER_KEY_ID: string;
+/**
+ * Raw API result — every tool in this package uses it.
+ *
+ * A 409 `lease_lost`, an empty queue, and a 422 confidence rejection are all
+ * things the AGENT has to act on: re-lease, stop, or resubmit. Collapsing them
+ * into a thrown Error would strip the structured body that says which.
+ */
+export interface RawApiResult {
+    ok: boolean;
+    status: number;
+    body: unknown;
+}
+/**
+ * SG-377: copied from `mcp-server/src/api-client.ts` (`apiRequestRaw`), which is
+ * module-private there and so cannot be imported even in principle.
+ *
+ * The shape test for extracting a shared core is ALREADY MET and this copies
+ * anyway — a recorded debt, not a deferral. It is one mechanism end to end (URL
+ * join, AbortController against a 30s default, the Bearer/Content-Type/Accept
+ * header set, JSON.stringify on non-GET, parse-or-null, the {ok, status, body}
+ * return, one AbortError -> timeout arm), differing only in the two module
+ * constants `SCHEMA_*` vs `AUDIT_*`.
+ *
+ * Two blast-radius reasons, neither of them a headcount: (1) the extraction edits
+ * an ALREADY-PUBLISHED package, which means the exact `make publish-mcp` version
+ * bump and `~/.npm/_npx` cache purge this separate package exists to keep away
+ * from an audit release — the schema server's own source records SG-171, a
+ * concurrent publish turning into `MCP error -32000: Connection closed` inside a
+ * live dispatch; (2) `npx -y` re-resolves the dependency graph at every dispatch,
+ * so a shared core inherits that hazard unless the pin is decided, and
+ * exact-pinned-published versus vendored-at-build-time is a real design decision
+ * with a real failure mode.
+ *
+ * REPAYMENT TRIGGER, concrete: extract at the NEXT `make publish-mcp` that is
+ * happening for an unrelated reason. At that moment both objections stop
+ * applying — the version bump and the cache purge are already being accepted, so
+ * the extraction rides along at zero additional hazard. The trigger says WHEN,
+ * not WHAT: the pin decision is still owed at extraction time. Do not re-derive
+ * "wait until there are N servers" — that argument is retired.
+ */
+export declare function apiRequestRaw(method: string, path: string, body?: Record<string, unknown>, timeoutMs?: number): Promise<RawApiResult>;
+/** The answer-key-scoped MCP route prefix. */
+export declare function mcpPath(endpoint: string): string;
+/**
+ * The three endpoints, as an interface so the tool modules can be driven by a
+ * fake in tests without touching the network.
+ */
+export interface AuditHttpClient {
+    input(filters: {
+        format?: "manifest" | "image" | "text" | "both";
+        file_id?: string;
+        page_start?: number;
+        page_end?: number;
+    }): Promise<RawApiResult>;
+    leaseUnaudited(payload: {
+        limit?: number;
+        message?: string;
+    }): Promise<RawApiResult>;
+    storeResult(payload: Record<string, unknown>): Promise<RawApiResult>;
+}
+export declare const auditHttpClient: AuditHttpClient;
+export { ANSWER_KEY_ID };

package/dist/api-client.js

@@ -0,0 +1,136 @@
+/**
+ * HTTP client for the gpt-manager answer-key MCP endpoints.
+ *
+ * Every request carries the dispatch's Bearer token for
+ * `AgentDispatchTokenMiddleware`, whose route group pins `dispatchable_type` to
+ * `AnswerKey` — a token minted for any other kind of dispatch is rejected 403
+ * before a controller runs.
+ *
+ * This client is a PURE PROXY. It holds no audit logic of any kind: it does not
+ * decide a verdict, does not compare a value to anything, and never sees an
+ * expected value. All of that lives behind the three endpoints.
+ */
+const API_URL = (process.env.AUDIT_API_URL ?? "").replace(/\/+$/, "");
+const API_TOKEN = process.env.AUDIT_API_TOKEN ?? "";
+const ANSWER_KEY_ID = process.env.ANSWER_KEY_ID ?? "";
+/**
+ * Boot gates — all three hard-exit when missing.
+ *
+ * There is deliberately NO fallback base URL. The schema server hard-codes a
+ * loopback default and that is the anti-pattern: a silently-defaulted URL
+ * turns a misconfigured dispatch into a confusing connection-refused cascade at
+ * first tool call instead of one clear line in the worker's stderr at boot. The
+ * Laravel side already treats a silent URL default as a bug
+ * (`AgentDispatchLaunchService::resolveCallbackUrls()` throws rather than
+ * defaulting), and this is the same decision on the other end of the same wire.
+ *
+ * There is no `MAX_RUNTIME_MS` gate either: nothing here reads one, and all
+ * three tools are one-shot with no poll budget to size.
+ */
+for (const [name, value] of [
+    ["AUDIT_API_URL", API_URL],
+    ["AUDIT_API_TOKEN", API_TOKEN],
+    ["ANSWER_KEY_ID", ANSWER_KEY_ID],
+]) {
+    if (!value) {
+        console.error(`${name} is required`);
+        process.exit(1);
+    }
+}
+/** Default timeout for API requests. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * SG-377: copied from `mcp-server/src/api-client.ts` (`apiRequestRaw`), which is
+ * module-private there and so cannot be imported even in principle.
+ *
+ * The shape test for extracting a shared core is ALREADY MET and this copies
+ * anyway — a recorded debt, not a deferral. It is one mechanism end to end (URL
+ * join, AbortController against a 30s default, the Bearer/Content-Type/Accept
+ * header set, JSON.stringify on non-GET, parse-or-null, the {ok, status, body}
+ * return, one AbortError -> timeout arm), differing only in the two module
+ * constants `SCHEMA_*` vs `AUDIT_*`.
+ *
+ * Two blast-radius reasons, neither of them a headcount: (1) the extraction edits
+ * an ALREADY-PUBLISHED package, which means the exact `make publish-mcp` version
+ * bump and `~/.npm/_npx` cache purge this separate package exists to keep away
+ * from an audit release — the schema server's own source records SG-171, a
+ * concurrent publish turning into `MCP error -32000: Connection closed` inside a
+ * live dispatch; (2) `npx -y` re-resolves the dependency graph at every dispatch,
+ * so a shared core inherits that hazard unless the pin is decided, and
+ * exact-pinned-published versus vendored-at-build-time is a real design decision
+ * with a real failure mode.
+ *
+ * REPAYMENT TRIGGER, concrete: extract at the NEXT `make publish-mcp` that is
+ * happening for an unrelated reason. At that moment both objections stop
+ * applying — the version bump and the cache purge are already being accepted, so
+ * the extraction rides along at zero additional hazard. The trigger says WHEN,
+ * not WHAT: the pin decision is still owed at extraction time. Do not re-derive
+ * "wait until there are N servers" — that argument is retired.
+ */
+export async function apiRequestRaw(method, path, body, timeoutMs) {
+    const url = `${API_URL}/api/${path}`;
+    const controller = new AbortController();
+    const resolvedTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), resolvedTimeout);
+    const options = {
+        method,
+        signal: controller.signal,
+        headers: {
+            Authorization: `Bearer ${API_TOKEN}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+    };
+    if (body !== undefined && method !== "GET") {
+        options.body = JSON.stringify(body);
+    }
+    try {
+        const response = await fetch(url, options);
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            parsed = null;
+        }
+        return { ok: response.ok, status: response.status, body: parsed };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error(`API timeout: ${method} ${path} did not respond within ${resolvedTimeout / 1000}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The answer-key-scoped MCP route prefix. */
+export function mcpPath(endpoint) {
+    return `answer-keys/mcp/${ANSWER_KEY_ID}/${endpoint}`;
+}
+export const auditHttpClient = {
+    input(filters) {
+        const qs = [];
+        for (const key of [
+            "format",
+            "file_id",
+            "page_start",
+            "page_end",
+        ]) {
+            const value = filters[key];
+            if (value !== undefined) {
+                qs.push(`${key}=${encodeURIComponent(String(value))}`);
+            }
+        }
+        const suffix = qs.length > 0 ? `?${qs.join("&")}` : "";
+        return apiRequestRaw("GET", mcpPath(`input${suffix}`));
+    },
+    leaseUnaudited(payload) {
+        return apiRequestRaw("POST", mcpPath("unaudited"), payload);
+    },
+    storeResult(payload) {
+        return apiRequestRaw("POST", mcpPath("results"), payload);
+    },
+};
+export { ANSWER_KEY_ID };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Answer Key MCP Server
+ *
+ * A stdio MCP server giving the blind answer-key audit agent exactly three
+ * tools, each a pure proxy over one gpt-manager endpoint:
+ *
+ *   get_input               — the source documents: a manifest, page text, or page images
+ *   get_unaudited_answers   — lease a batch of entries to audit
+ *   store_result            — record what the agent found for one entry
+ *
+ * ## Why this is its own package rather than three tools on the schema server
+ *
+ * Blast radius. `make publish-mcp` bumps a version that every in-flight schema
+ * dispatch's `npx` resolves, and purges the `~/.npm/_npx` cache; the schema
+ * server's own source records SG-171, where exactly that turned into
+ * `MCP error -32000: Connection closed` inside a live dispatch. An audit release
+ * must not be able to do that to a schema build.
+ *
+ * And the schema server is schema-shaped at MODULE level, not merely at its gate:
+ * its api-client binds URL/token/id to `SCHEMA_*` env names, its `mcpPath()`
+ * hardcodes the `schemas/mcp/{id}` prefix, and its index registers every schema
+ * tool unconditionally — so an audit dispatch there would carry ~20 tools that
+ * 404 against an empty `SCHEMA_ID`.
+ *
+ * ## The audit is BLIND
+ *
+ * The agent is never sent the recorded answer, in any match mode, and this
+ * package's obligation on that is DOCUMENTATION, not enforcement — the
+ * withholding itself lives server-side. Every tool description says plainly that
+ * no result ever carries an expected value, so the agent reads its absence as the
+ * normal shape of the data rather than as a fault to report.
+ *
+ * Environment variables — all three are required and the server hard-exits
+ * without them (no silent URL default; see api-client.ts):
+ *   AUDIT_API_URL   — gpt-manager base URL the worker can reach
+ *   AUDIT_API_TOKEN — the dispatch's Bearer token
+ *   ANSWER_KEY_ID   — the key being audited
+ *
+ * There is no MAX_RUNTIME_MS: nothing reads one and all three tools are one-shot.
+ * There is no DANX_SANDBOX_PATH either — this agent has no disk at all, which is
+ * why `get_input` fetches page images itself and returns them as content blocks.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Answer Key MCP Server
+ *
+ * A stdio MCP server giving the blind answer-key audit agent exactly three
+ * tools, each a pure proxy over one gpt-manager endpoint:
+ *
+ *   get_input               — the source documents: a manifest, page text, or page images
+ *   get_unaudited_answers   — lease a batch of entries to audit
+ *   store_result            — record what the agent found for one entry
+ *
+ * ## Why this is its own package rather than three tools on the schema server
+ *
+ * Blast radius. `make publish-mcp` bumps a version that every in-flight schema
+ * dispatch's `npx` resolves, and purges the `~/.npm/_npx` cache; the schema
+ * server's own source records SG-171, where exactly that turned into
+ * `MCP error -32000: Connection closed` inside a live dispatch. An audit release
+ * must not be able to do that to a schema build.
+ *
+ * And the schema server is schema-shaped at MODULE level, not merely at its gate:
+ * its api-client binds URL/token/id to `SCHEMA_*` env names, its `mcpPath()`
+ * hardcodes the `schemas/mcp/{id}` prefix, and its index registers every schema
+ * tool unconditionally — so an audit dispatch there would carry ~20 tools that
+ * 404 against an empty `SCHEMA_ID`.
+ *
+ * ## The audit is BLIND
+ *
+ * The agent is never sent the recorded answer, in any match mode, and this
+ * package's obligation on that is DOCUMENTATION, not enforcement — the
+ * withholding itself lives server-side. Every tool description says plainly that
+ * no result ever carries an expected value, so the agent reads its absence as the
+ * normal shape of the data rather than as a fault to report.
+ *
+ * Environment variables — all three are required and the server hard-exits
+ * without them (no silent URL default; see api-client.ts):
+ *   AUDIT_API_URL   — gpt-manager base URL the worker can reach
+ *   AUDIT_API_TOKEN — the dispatch's Bearer token
+ *   ANSWER_KEY_ID   — the key being audited
+ *
+ * There is no MAX_RUNTIME_MS: nothing reads one and all three tools are one-shot.
+ * There is no DANX_SANDBOX_PATH either — this agent has no disk at all, which is
+ * why `get_input` fetches page images itself and returns them as content blocks.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { auditHttpClient } from "./api-client.js";
+import { registerAuditTools } from "./tools/audit-tools.js";
+import { LOADED_VERSION } from "./version.js";
+const server = new McpServer({
+    name: "answer-key-mcp-server",
+    version: LOADED_VERSION,
+});
+registerAuditTools(server, auditHttpClient);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Answer Key MCP Server ${LOADED_VERSION} running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/tools/_shared.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared helpers for this package's three tool modules.
+ *
+ * All three are SG-377 copies of `mcp-server/src/tools/_shared.ts`. See the long
+ * note on `apiRequestRaw` in `../api-client.ts` for the met shape test, the two
+ * blast-radius reasons this package copies anyway, and the concrete repayment
+ * trigger. Each is repeated here in short because the debt has to be met in the
+ * code by whoever next publishes, not in a card they would have to remember.
+ */
+import { z } from "zod";
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`jsonResult`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ *
+ * Wrap a response body into the MCP tool result format.
+ */
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`messageParam`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ */
+export declare const messageParam: z.ZodOptional<z.ZodString>;
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`idParam`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ *
+ * `z.coerce.number()` because agents pattern-match the id shape off list
+ * responses and frequently send stringified numbers.
+ *
+ * `.int().positive()` is load-bearing rather than decorative: zod's coerce passes
+ * `null` and `""` through to `Number()`, which produces `0` — never a valid
+ * primary key. The endpoint validates `entry_id` as `required|integer` with no
+ * minimum, so a `0` would sail through validation and 404 deep inside the
+ * dispatch as `entry_unknown` instead of failing at the boundary with a legible
+ * parameter error.
+ */
+export declare function idParam(description: string): z.ZodCoercedNumber<unknown>;
+/** A coerced, positive, optional integer — used for `limit` and the page window. */
+export declare function optionalPositiveInt(description: string): z.ZodOptional<z.ZodCoercedNumber<unknown>>;

package/dist/tools/_shared.js

@@ -0,0 +1,71 @@
+/**
+ * Shared helpers for this package's three tool modules.
+ *
+ * All three are SG-377 copies of `mcp-server/src/tools/_shared.ts`. See the long
+ * note on `apiRequestRaw` in `../api-client.ts` for the met shape test, the two
+ * blast-radius reasons this package copies anyway, and the concrete repayment
+ * trigger. Each is repeated here in short because the debt has to be met in the
+ * code by whoever next publishes, not in a card they would have to remember.
+ */
+import { z } from "zod";
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`jsonResult`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ *
+ * Wrap a response body into the MCP tool result format.
+ */
+export function jsonResult(data) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(data, null, 2) },
+        ],
+    };
+}
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`messageParam`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ */
+export const messageParam = z
+    .string()
+    .optional()
+    .describe("Human-readable description of what you're doing (shown in the user's activity feed). " +
+    "Never put page text or quoted source text here — these are patient records.");
+/**
+ * SG-377: copied from `mcp-server/src/tools/_shared.ts` (`idParam`), which is
+ * identical there — the shape test is met and this copies anyway. Blast radius:
+ * extracting it edits an already-published package, forcing the `make publish-mcp`
+ * bump + `~/.npm/_npx` purge this package exists to keep away from an audit
+ * release; and `npx -y` re-resolves at every dispatch, so a shared core inherits
+ * that hazard until the pin is decided. REPAYMENT TRIGGER: extract at the NEXT
+ * `make publish-mcp` happening for an unrelated reason, when the bump and the
+ * purge are already being accepted.
+ *
+ * `z.coerce.number()` because agents pattern-match the id shape off list
+ * responses and frequently send stringified numbers.
+ *
+ * `.int().positive()` is load-bearing rather than decorative: zod's coerce passes
+ * `null` and `""` through to `Number()`, which produces `0` — never a valid
+ * primary key. The endpoint validates `entry_id` as `required|integer` with no
+ * minimum, so a `0` would sail through validation and 404 deep inside the
+ * dispatch as `entry_unknown` instead of failing at the boundary with a legible
+ * parameter error.
+ */
+export function idParam(description) {
+    return z.coerce.number().int().positive().describe(description);
+}
+/** A coerced, positive, optional integer — used for `limit` and the page window. */
+export function optionalPositiveInt(description) {
+    return z.coerce.number().int().positive().optional().describe(description);
+}

package/dist/tools/audit-tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The audit agent's entire tool surface: `get_input`, `get_unaudited_answers`,
+ * `store_result`.
+ *
+ * All three are pure proxies — every decision lives behind the gpt-manager
+ * endpoints. The one thing this module does on its own is fetch page image bytes
+ * (see `get_input`), because the agent has no disk to stage them on.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AuditHttpClient } from "../api-client.js";
+/**
+ * How many page images one `get_input` call may return.
+ *
+ * One MCP tool result is a single model turn, so an unbounded image window is a
+ * context blowout rather than a slow response. Text pages keep the server's own
+ * 20-page cap.
+ */
+export declare const IMAGE_PAGES_PER_CALL = 4;
+export declare function registerAuditTools(server: McpServer, client: AuditHttpClient, fetchImpl?: typeof fetch): void;

package/dist/tools/audit-tools.js

@@ -0,0 +1,221 @@
+/**
+ * The audit agent's entire tool surface: `get_input`, `get_unaudited_answers`,
+ * `store_result`.
+ *
+ * All three are pure proxies — every decision lives behind the gpt-manager
+ * endpoints. The one thing this module does on its own is fetch page image bytes
+ * (see `get_input`), because the agent has no disk to stage them on.
+ */
+import { z } from "zod";
+import { idParam, jsonResult, messageParam, optionalPositiveInt } from "./_shared.js";
+/**
+ * How many page images one `get_input` call may return.
+ *
+ * One MCP tool result is a single model turn, so an unbounded image window is a
+ * context blowout rather than a slow response. Text pages keep the server's own
+ * 20-page cap.
+ */
+export const IMAGE_PAGES_PER_CALL = 4;
+/**
+ * Fetch one page image and return it as an MCP image content block.
+ *
+ * The block SHAPE is copied from the schema server's `_shared.ts`. Its
+ * `multiPageImageResult` helper is deliberately NOT imported: it has zero callers
+ * there and is dead, and it expects inline `images_base64` on each page — which
+ * this endpoint never returns, because gpt-manager hands back URLs only.
+ *
+ * This does not widen the SG-320 boundary. gpt-manager returns URLs; the shim
+ * fetches storage directly; the bytes move between this process and the model and
+ * never through gpt-manager.
+ */
+async function fetchImageBlock(page, fetchImpl) {
+    if (!page.url) {
+        return {
+            type: "text",
+            text: `Page ${page.page} of ${page.file_id} has no image url.`,
+        };
+    }
+    const response = await fetchImpl(page.url);
+    if (!response.ok) {
+        return {
+            type: "text",
+            text: `Page ${page.page} of ${page.file_id} could not be fetched (HTTP ${response.status}).`,
+        };
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    return {
+        type: "image",
+        data: buffer.toString("base64"),
+        mimeType: page.mime || "image/jpeg",
+    };
+}
+export function registerAuditTools(server, client, fetchImpl = fetch) {
+    server.tool("get_input", "Read the source documents this answer key was built from. " +
+        "Call this FIRST with the default 'manifest' format to see what documents exist and how many pages each has; " +
+        "then request windows of pages.\n\n" +
+        "format=manifest returns one descriptor per document {file_id, filename, mime, size, url, page_count, is_transcoding, text_transcode_names}.\n" +
+        "format=text returns page text (server caps a window at 20 pages).\n" +
+        `format=image returns page IMAGES as content blocks, at most ${IMAGE_PAGES_PER_CALL} per call — ` +
+        "a wider window is refused before any image is fetched, with {error: 'window_too_large', max, returned}; narrow the window and iterate.\n" +
+        "format=both returns text and images together under the same image cap.\n\n" +
+        "Never copy page text into a `message` or a `reason` — these are patient records.", {
+        format: z
+            .enum(["manifest", "image", "text", "both"])
+            .optional()
+            .describe("manifest (default) lists the documents; image/text/both return pages"),
+        file_id: z
+            .string()
+            .optional()
+            .describe("Restrict to one document. This is a UUID STRING as returned by the manifest, not a numeric id."),
+        page_start: optionalPositiveInt("First page of the window (1-based, inclusive)"),
+        page_end: optionalPositiveInt("Last page of the window (1-based, inclusive)"),
+    }, async ({ format, file_id, page_start, page_end }) => {
+        const result = await client.input({
+            format,
+            file_id,
+            page_start,
+            page_end,
+        });
+        if (!result.ok) {
+            return jsonResult(result.body);
+        }
+        const wantsImages = format === "image" || format === "both";
+        if (!wantsImages) {
+            return jsonResult(result.body);
+        }
+        const body = (result.body ?? {});
+        const pages = (body.pages ?? []);
+        const imagePages = pages.filter((page) => page.url !== undefined);
+        // The cap is decided from the DESCRIPTOR COUNT the endpoint just
+        // returned — after the URL-only call, which is cheap, and BEFORE a
+        // single image byte is fetched. A pre-request check on
+        // page_start/page_end cannot work: both are optional server-side and
+        // the server silently caps the window at 20, so the number of pages
+        // actually coming back is not knowable until it answers.
+        if (imagePages.length > IMAGE_PAGES_PER_CALL) {
+            return jsonResult({
+                error: "window_too_large",
+                max: IMAGE_PAGES_PER_CALL,
+                returned: imagePages.length,
+            });
+        }
+        const content = [];
+        for (const page of imagePages) {
+            content.push({
+                type: "text",
+                text: `--- ${page.file_id} page ${page.page} ---`,
+            });
+            content.push(await fetchImageBlock(page, fetchImpl));
+        }
+        const withoutUrls = pages.map((page) => {
+            const clean = { ...page };
+            delete clean.url;
+            return clean;
+        });
+        content.push({
+            type: "text",
+            text: JSON.stringify({ ...body, pages: withoutUrls }, null, 2),
+        });
+        return { content };
+    });
+    server.tool("get_unaudited_answers", "Lease a batch of entries to audit. Each entry is a QUESTION about one record in the documents:\n" +
+        "{entry_id, object_type, identity, identity_display, field_path, occurrence_idx, match_mode, attempts}, " +
+        "plus {remaining_count, lease_expires_at} on the batch.\n\n" +
+        "THE RESULT NEVER CARRIES AN EXPECTED VALUE. Not in any match mode — not exact, numeric, normalized, " +
+        "contains, regex, not_null, count, each_item, parentage, and not absent, must_not_contain, if_present or " +
+        "one_of either. It also never carries quoted source text or the pages the value was recorded on. " +
+        "That absence is the NORMAL shape of every entry you will ever see: it is not missing, not corrupt, " +
+        "not a special mode, and never something to report as a fault, skip an entry over, or ask for. " +
+        "You derive the value from the documents; the server holds the recorded answer and decides agreement itself.\n\n" +
+        "`match_mode` tells you the KIND of question, never the answer. exact/numeric/normalized/contains/regex: " +
+        "find the value the record states. count/each_item: report the list you find. not_null: report the value " +
+        "if the record states one. absent: say whether anything is there at all. must_not_contain: report what the " +
+        "record says (the forbidden text is not shown to you and you do not need it). if_present/one_of: report the " +
+        "value you find (the accepted set is not shown to you and you do not need it). parentage: report the parent " +
+        "identity you resolve.\n\n" +
+        "THE ONE THING THE PAYLOAD CANNOT WITHHOLD is `identity` and `identity_display` — your only handle on the " +
+        "record you are being asked about. For some entries the field being GRADED is that identity, so the identity " +
+        "handed to you is also the recorded answer, and you are never told which entries those are (the result carries " +
+        "no flag for it, deliberately, so every entry looks alike). It happens in three ways: the graded field_path is " +
+        "'name', so the anchor's primary IS the answer; the graded field_path is a key of the identity's secondary map, " +
+        "so the accepted forms sit in the payload under that key; or the entry's anchor is a KEYWORD anchor, whose " +
+        "primary and secondary are empty by construction — so no field_path test can see it — and whose keywords are " +
+        "substrings of the free text the entry grades.\n\n" +
+        "The identity is a LOCATOR, not an answer. Finding it in the payload is not finding it in the documents. " +
+        "Echoing it back is worthless: it will be counted as an agreement while proving nothing. " +
+        "Return `not_found` instead — it is a first-class, valuable answer.\n\n" +
+        "Lease in batches, work them, then lease again. When `entries` comes back EMPTY the pass is over: stop.", {
+        limit: optionalPositiveInt("How many entries to lease (server validates 1..25, default 10)"),
+        message: messageParam,
+    }, async ({ limit, message }) => {
+        const result = await client.leaseUnaudited({ limit, message });
+        return jsonResult(result.body);
+    });
+    server.tool("store_result", "Record what YOU found for one leased entry. The value must be the one you derived from the documents.\n\n" +
+        "verdict: 'certain' (you read the value on a page), 'possible' (you found something but are not sure — " +
+        "supply `confidence` 1..99), or 'not_found' (you could not find the record or the value). " +
+        "`value` is required for certain and possible, and must be OMITTED for not_found. " +
+        "`confidence` is required for possible and must be omitted for the other two.\n\n" +
+        "CITE EVERY certain AND EVERY possible with at least one {file_id, page} naming a page you actually read the " +
+        "value on. Nothing server-side forces this — `citations` is nullable — so it is an INSTRUCTION, and it is the " +
+        "only thing in the record that distinguishes a derived answer from a copied one. An uncited `certain` on an " +
+        "entry whose identity you were handed is indistinguishable from an echo and will be read as one.\n\n" +
+        "`reason` is always required. Never put page text or quoted source text in `reason` or `message` — patient records.\n\n" +
+        "THE SERVER DECIDES THE VERDICT. The result is " +
+        "{entry_id, audit_verdict, matched, identity_disclosed, remaining_count}. `audit_verdict` is one of " +
+        "confirmed | disputed | proposed | not_found — derived server-side from your value and the recorded answer, " +
+        "never from anything you send. `identity_disclosed` is a QUALIFIER on that verdict, never a fifth verdict: it " +
+        "is derived server-side by AnswerKeyEntry::isIdentityDisclosed() under all three disclosure shapes above, and " +
+        "is ignored if you send it. It marks an entry where a `confirmed` proves that the machine returned a value " +
+        "consistent with a name the payload handed it, and does NOT prove the machine independently found the record " +
+        "in the documents — while a `disputed` or `not_found` on the same entry IS real evidence, because nothing in " +
+        "the payload would produce that answer.\n\n" +
+        "Stop when a lease comes back with no entries. A 409 {reason: 'lease_lost'} means your claim expired or was " +
+        "retired: lease again rather than retrying this write.", {
+        entry_id: idParam("entry_id from the lease result"),
+        verdict: z
+            .enum(["certain", "possible", "not_found"])
+            .describe("certain: you read it on a page. possible: you found something but are unsure. not_found: you could not find it."),
+        value: z
+            .unknown()
+            .optional()
+            .describe("The value YOU derived from the documents. Required for certain and possible, omitted for not_found. " +
+            "For count/each_item modes it is a list; for every other mode it is a scalar."),
+        confidence: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(99)
+            .optional()
+            .describe("Required for verdict=possible, omitted otherwise"),
+        citations: z
+            .array(z.object({
+            file_id: z
+                .string()
+                .describe("Document UUID string from the manifest"),
+            page: z.coerce
+                .number()
+                .int()
+                .positive()
+                .describe("1-based page number you read the value on"),
+        }))
+            .optional()
+            .describe("Pages you actually read the value on. Supply at least one for every certain and every possible."),
+        reason: z
+            .string()
+            .describe("Why you reached this verdict. Always required. Never quote page text here."),
+        message: messageParam,
+    }, async (args) => {
+        // Only keys the agent actually supplied are forwarded: the endpoint
+        // uses `missing_if` rules, so sending `confidence: null` on a
+        // `certain` verdict is a 422 rather than an omission.
+        const payload = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (value !== undefined) {
+                payload[key] = value;
+            }
+        }
+        const result = await client.storeResult(payload);
+        return jsonResult(result.body);
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const LOADED_VERSION: string;

package/dist/version.js

@@ -0,0 +1,19 @@
+/**
+ * The package's published version, read from package.json at module load and
+ * reported as `serverInfo.version` in the MCP initialize handshake.
+ *
+ * Dist layout assumption: `../package.json` resolves from BOTH
+ * `src/version.ts` and `dist/version.js` because both live one level below the
+ * package root. If tsconfig ever emits to a nested output dir, re-pin it here.
+ *
+ * There is deliberately NO disk-vs-memory drift assertion. The schema server
+ * carried one and retired it (SG-171): a concurrent publish clears
+ * `~/.npm/_npx/*` and the drift check then crashed in-flight dispatches with
+ * `MCP error -32000: Connection closed`. A running server serves its own loaded
+ * code; future spawns naturally fetch the newer version.
+ */
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+const loadedPkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+export const LOADED_VERSION = loadedPkg.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/answer-key-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for the blind answer-key audit agent - three proxy tools over gpt-manager's answer-key MCP endpoints",
   "license": "MIT",
   "repository": {