@integraledger/lcp-mcp-server 0.9.0

package/src/tools/generate-legal-context.ts

@@ -0,0 +1,127 @@
+import {
+  emit,
+  isKnownTermsFormat,
+  KNOWN_TERMS_FORMATS,
+  type LegalContextJson,
+} from "@integraledger/lcp-discovery";
+import { hashAtr } from "@integraledger/lcp-kernel";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { readOnlyToolAnnotations } from "../annotations.js";
+import type { LcpMcpPorts } from "../ports.js";
+
+const inputSchema = z.object({
+  termsUrl: z
+    .url()
+    .describe("HTTPS URL of the terms document. Fetched, so it must be live."),
+  termsFormat: z
+    .string()
+    .describe(
+      `The LCP §2.5 format token for the terms document — one of: ${KNOWN_TERMS_FORMATS.join(", ")}.`,
+    ),
+  acceptanceRequired: z
+    .boolean()
+    .optional()
+    .describe(
+      "Set true where the service requires explicit signed acceptance before transacting (LCP §3, Level 3).",
+    ),
+  disputeResolution: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      "The service's dispute-resolution metadata (LCP §3, Level 4), e.g. { method, jurisdiction }.",
+    ),
+  returns: z.string().optional().describe("URL of the returns policy."),
+  api: z
+    .url()
+    .optional()
+    .describe("Entry point to richer legal functionality (LCP §3, Level 4)."),
+});
+
+const outputSchema = z.object({
+  terms: z.string().describe("The terms document URL, echoed from the input."),
+  termsFormat: z.string().describe("The LCP §2.5 format token."),
+  atrHash: z
+    .string()
+    .describe("SHA-256 over the bytes served at `terms`, computed here."),
+  acceptanceRequired: z
+    .boolean()
+    .optional()
+    .describe("Present only where the input declared it."),
+  disputeResolution: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Present only where the input declared it."),
+  returns: z
+    .string()
+    .optional()
+    .describe("Present only where the input declared it."),
+  api: z
+    .string()
+    .optional()
+    .describe("Present only where the input declared it."),
+});
+
+/**
+ * `lcp_generate_legal_context` — build a ready-to-publish `/.well-known/legal-context.json`.
+ *
+ * Grounded on `discovery.emit`, which drops undefined fields and then VALIDATES what is left, so a profile
+ * this tool cannot legally emit fails loudly here rather than 404-ing an agent later. The `atrHash` is
+ * `kernel.hashAtr` over the bytes actually served at `termsUrl` — never a value the caller supplies, because
+ * a hash the author asserts rather than computes is the one field an author can get wrong and never notice.
+ *
+ * `termsFormat` is checked against `discovery.KNOWN_TERMS_FORMATS` rather than re-declared as an enum here:
+ * the token set is the protocol's, and a second copy in this package would be free to drift from it. The
+ * free-string `termsFormat` invites values like `text/plain` and `application/pdf`,
+ * neither of which is an LCP §2.5 token.
+ *
+ * IT RETURNS THE DOCUMENT; IT DOES NOT PUBLISH ONE. Serving it is the deployment's act, on the deployment's
+ * origin, under the deployment's name.
+ */
+export function registerGenerateLegalContext(
+  server: McpServer,
+  ports: LcpMcpPorts,
+): void {
+  server.registerTool(
+    "lcp_generate_legal_context",
+    {
+      description:
+        "Build a ready-to-publish `/.well-known/legal-context.json` document. Fetches `termsUrl`, " +
+        "computes the ATR hash over the served bytes, validates the result against the LCP discovery " +
+        "schema, and returns the document to serve. It does not publish anything.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations(
+        "Generate LCP legal-context.json",
+        "network",
+      ),
+    },
+    async (args) => {
+      if (!isKnownTermsFormat(args.termsFormat))
+        throw new Error(
+          `termsFormat "${args.termsFormat}" is not an LCP §2.5 token — expected one of: ${KNOWN_TERMS_FORMATS.join(", ")}`,
+        );
+      const bytes = (await ports.fetcher.fetch(args.termsUrl)).bytes;
+      const profile: LegalContextJson = {
+        terms: args.termsUrl,
+        termsFormat: args.termsFormat,
+        atrHash: await hashAtr(bytes),
+        ...(args.acceptanceRequired !== undefined
+          ? { acceptanceRequired: args.acceptanceRequired }
+          : {}),
+        ...(args.disputeResolution !== undefined
+          ? { disputeResolution: args.disputeResolution }
+          : {}),
+        ...(args.returns !== undefined ? { returns: args.returns } : {}),
+        ...(args.api !== undefined ? { api: args.api } : {}),
+      };
+      const doc = emit(profile);
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(doc, null, 2) },
+        ],
+        structuredContent: doc,
+      };
+    },
+  );
+}

package/src/tools/place-reference.ts

@@ -0,0 +1,96 @@
+import { decodeLegalContextString } from "@integraledger/lcp-binding-core";
+import { supportedProtocols } from "@integraledger/lcp-placements";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { readOnlyToolAnnotations } from "../annotations.js";
+import {
+  manifestSummary,
+  PLACEMENT_SUMMARY_SCHEMA,
+  refusalResult,
+  resolveAdapter,
+} from "../dispatch.js";
+import type { LcpMcpPorts } from "../ports.js";
+
+/** A host protocol document, as JSON. One shape, used for the argument and for the result. */
+const documentShape = z.record(z.string(), z.unknown());
+
+const inputSchema = z.object({
+  protocol: z
+    .string()
+    .describe(
+      "The commerce protocol whose document this is. See `lcp_place_reference`'s description for the set this build can place into.",
+    ),
+  reference: z
+    .string()
+    .describe(
+      "The LCP §8.1 carrier string, `lcp:{type}:{value}` — exactly what `lcp_compute_atrhash` returns as `reference`.",
+    ),
+  document: documentShape.describe(
+    "The host protocol's own document, as JSON. Returned unchanged with the reference added; the input is never mutated.",
+  ),
+});
+
+const outputSchema = z.object({
+  document: documentShape.describe(
+    "The host document with the reference placed.",
+  ),
+  placement: PLACEMENT_SUMMARY_SCHEMA,
+});
+
+/**
+ * `lcp_place_reference` — put an LCP reference into any commerce protocol's own document.
+ *
+ * The tool that makes this server protocol-independent in the sense LCP §10 means: an agent transacting
+ * under ACP, x402, UCP, AP2, ACK, MPP, A2A, Visa TAP or Mastercard VI calls the SAME tool, and the
+ * registry decides where the reference belongs. Adding a protocol is a registry release, not a change here.
+ *
+ * The returned `placement` block is the manifest's own account of what happened — which tier it is (does
+ * this work against stock implementations today, §8.3), which pattern, and the exact field — so a caller
+ * can tell a declared protocol extension from an advisory metadata ride without reading our documentation.
+ *
+ * IT RETURNS A DOCUMENT; IT DOES NOT SEND ONE. The placement adapters are pure and never mutate their
+ * input, and this tool adds no transport. Whether the document goes on the wire is the agent's decision,
+ * made with its own credentials — this server holds none.
+ */
+export function registerPlaceReference(
+  server: McpServer,
+  ports: LcpMcpPorts,
+): void {
+  server.registerTool(
+    "lcp_place_reference",
+    {
+      description:
+        "Place an LCP legal-context reference into a commerce protocol's own document, at the field that " +
+        "protocol's placement manifest declares. Supported protocols in this build: " +
+        `${supportedProtocols().join(", ")}. Returns the updated document plus the placement manifest's ` +
+        "tier, pattern and field. This is a legally significant act: the resulting document asserts which " +
+        "terms govern the transaction. It returns the document — it does not transmit it.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations("Place an LCP reference", "closed"),
+    },
+    (args) => {
+      const adapter = resolveAdapter(args.protocol, ports);
+      const ref = decodeLegalContextString(args.reference);
+      if (ref === undefined)
+        throw new Error(
+          `"${args.reference}" is not a recognized LCP §8.1 carrier string — expected lcp:{type}:{value} with a registered type`,
+        );
+      const outcome = adapter.place(ref, args.document);
+      if (!("ok" in outcome)) return refusalResult(outcome);
+      // `place` is typed `Outcome<unknown>` because a host document is whatever the host protocol says it
+      // is. Parsing rather than casting keeps the widening honest: an adapter that somehow returned a
+      // non-object would fail here and say so, instead of reaching the wire as a malformed tool result.
+      const out = {
+        document: documentShape.parse(outcome.value),
+        placement: manifestSummary(adapter.manifest),
+      };
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(out, null, 2) },
+        ],
+        structuredContent: out,
+      };
+    },
+  );
+}

package/src/tools/scaffold-integration.ts

@@ -0,0 +1,183 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { readOnlyToolAnnotations } from "../annotations.js";
+
+const inputSchema = z.object({
+  target: z
+    .enum(["seller", "buyer"])
+    .describe(
+      "Which side to scaffold: 'seller' (publish legal-context.json and place the reference) or " +
+        "'buyer' (verify before signing or paying).",
+    ),
+});
+
+const outputSchema = z.object({
+  target: z.enum(["seller", "buyer"]).describe("The side that was scaffolded."),
+  scaffold: z
+    .string()
+    .describe("Markdown: the steps, and the code to paste, for that side."),
+});
+
+const SELLER_SCAFFOLD = `# LCP seller integration
+
+Two obligations, and the second is the one most integrations forget.
+
+## 1. Publish /.well-known/legal-context.json
+
+Terms must be a standalone, downloadable artifact at a stable URL (LCP §2.2) — not a section of a page,
+not dynamically rendered HTML. The atrHash is the SHA-256 over the exact bytes you serve.
+
+\`\`\`ts
+import { emit } from "@integraledger/lcp-discovery";
+import { hashAtr } from "@integraledger/lcp-kernel";
+
+// A bare \`fetch\` is right HERE and wrong on the buyer side, and the asymmetry is the point: this URL is
+// YOUR OWN, chosen by you at build time. The buyer fetches a URL a counterparty chose, which is why the
+// buyer scaffold below goes through the SSRF-guarded fetcher instead.
+const bytes = new Uint8Array(await (await fetch(TERMS_URL)).arrayBuffer());
+
+// emit() drops undefined fields and validates the result — a malformed profile throws here,
+// at build time, rather than 404-ing an agent later.
+export const legalContext = emit({
+  terms: TERMS_URL,
+  termsFormat: "markdown",          // an LCP §2.5 token: markdown | json | plain | html | pdf
+  atrHash: await hashAtr(bytes),
+  acceptanceRequired: true,          // Level 3: explicit signed acceptance before transacting
+  disputeResolution: { method: "...", jurisdiction: "..." },   // Level 4
+});
+
+// Serve it, with the exact bytes you hashed still at TERMS_URL:
+//   GET /.well-known/legal-context.json  ->  Response.json(legalContext)
+\`\`\`
+
+Recompute and republish the hash on EVERY terms change. A stale atrHash halts every conformant buyer.
+
+## 2. Carry the reference on the transaction itself
+
+The discovery document says what your terms are. It does not bind them to a particular transaction —
+that is the placement's job, and where it goes is the host protocol's decision, not yours.
+
+\`\`\`ts
+import { placementFor } from "@integraledger/lcp-placements";
+
+const adapter = placementFor("acp");            // or x402, ucp, ap2, ack, mpp, a2a, visa-tap …
+const outcome = adapter?.place(
+  { type: "sha256", value: legalContext.atrHash },
+  checkoutSession,
+);
+if (outcome === undefined || !("ok" in outcome)) throw new Error("no placement — halt");
+send(outcome.value);
+\`\`\`
+
+Or call the \`lcp_place_reference\` tool on this server, which dispatches through the same registry.
+
+An x402 seller gets both halves plus the settlement weld from Integra's separately licensed seller layer,
+which is not part of this open one — flagged so you know what completes the picture, not as something you
+can npm-install from here.
+`;
+
+const BUYER_SCAFFOLD = `# LCP buyer-agent integration — verify BEFORE you sign or pay (LCP §5.3)
+
+The rule: fetch the terms the counterparty advertised, recompute the fingerprint, and HALT before the
+signing key is invoked if it does not match.
+
+## The check itself
+
+Both URLs below are the COUNTERPARTY's, so both are fetched through the guarded fetcher — HTTPS-only,
+\`redirect: "error"\`, every resolved address re-checked public unicast on every fetch, body capped while
+streaming. A bare \`fetch\` here is an SSRF primitive an agent can be talked into aiming anywhere.
+
+\`\`\`ts
+import { makeCachingFetcher, nodeDnsLookup } from "@integraledger/agent-guard";
+import { checkListingIntegrity, parseLegalContextJson } from "@integraledger/lcp-discovery";
+import { isAtrHash } from "@integraledger/lcp-kernel";
+
+const fetcher = makeCachingFetcher({
+  httpFetch: fetch,
+  now: () => new Date().toISOString(),
+  lookup: nodeDnsLookup,
+});
+
+const doc     = await fetcher.fetch(\`\${SELLER_ORIGIN}/.well-known/legal-context.json\`);
+const listing = parseLegalContextJson(JSON.parse(new TextDecoder().decode(doc.bytes)));
+
+// \`atrHash\` is optional on the record: absent is LCP Level 1, where there is nothing to verify at all.
+// Treat that as a halt, not a pass — the honest answer is that this cannot say the terms are the ones
+// committed to.
+if (listing.atrHash === undefined || !isAtrHash(listing.atrHash))
+  throw new Error("no verifiable fingerprint declared (Level 1) — refusing to pay on an unproven record");
+
+const terms = await fetcher.fetch(listing.terms);
+const dsc2  = await checkListingIntegrity(listing, terms.bytes, listing.atrHash);
+
+if (!dsc2.ok) throw new Error(\`LCP verification failed: \${dsc2.detail} — refusing to pay\`);
+\`\`\`
+
+Or call the \`lcp_verify_before_pay\` tool on this server, which does exactly this.
+
+## The gate around it
+
+A hash check alone is not a policy. \`@integraledger/agent-guard\` runs the whole ladder — required level,
+fingerprint, the buyer's stated policy over the TYPED envelope only, coverage gaps, seller assurance —
+and returns a decision that \`transact\` enforces against a guarded signer, so the key is unreachable on
+anything but Proceed:
+
+\`\`\`ts
+import { makeCachingFetcher, nodeDnsLookup, transact } from "@integraledger/agent-guard";
+
+const fetcher = makeCachingFetcher({
+  httpFetch: fetch,
+  now: () => new Date().toISOString(),
+  lookup: nodeDnsLookup,       // the SSRF guard: the URL came from the counterparty
+});
+const result = await transact(proposal, policy, { fetcher, now, log }, signer);
+// result.kind === "signed" only on Proceed. On Decline or Escalate the signer is never called.
+\`\`\`
+
+Two properties do the work, and neither is a matter of discipline: the typed proposal CANNOT carry
+natural-language prose, so the terms body can never reach policy evaluation (the prompt-injection
+boundary is architectural, LCP §12.7); and a coverage gap is resolved by the buyer's STATED disposition,
+never by a silent default.
+
+Retain the fetched bytes. They are the evidence of what you saw (LCP §5.4).
+`;
+
+/**
+ * `lcp_scaffold_integration` — copy-pasteable starter code for either side of an LCP integration.
+ *
+ * BOTH SCAFFOLDS HAND THE INTEGRATOR THE SHIPPED PACKAGES, deliberately. The alternative an integrator
+ * reaches for unaided is a hand-rolled zero-dependency verifier — a `createHash("sha256")`, a hand-parsed
+ * JWS, and a fetch with no SSRF posture — which is exactly the code nobody should be writing themselves,
+ * and which drifts from the standard the moment the standard moves.
+ *
+ * The `target` tokens are `seller` and `buyer`, matching the vocabulary the rest of this stack uses. The
+ * seller scaffold covers BOTH obligations: publishing the discovery document is not the whole integration,
+ * because it binds no particular transaction.
+ */
+export function registerScaffoldIntegration(server: McpServer): void {
+  server.registerTool(
+    "lcp_scaffold_integration",
+    {
+      description:
+        "Return copy-pasteable starter code and steps for integrating LCP, for `target: 'seller'` " +
+        "(publish legal-context.json and carry the reference on the transaction) or `target: 'buyer'` " +
+        "(verify before signing or paying). The code uses the shipped @integraledger packages.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations(
+        "Scaffold an LCP integration",
+        "closed",
+      ),
+    },
+    (args) => {
+      const out = {
+        target: args.target,
+        scaffold: args.target === "seller" ? SELLER_SCAFFOLD : BUYER_SCAFFOLD,
+      };
+      return {
+        content: [{ type: "text" as const, text: out.scaffold }],
+        structuredContent: out,
+      };
+    },
+  );
+}

package/src/tools/verify-before-pay.ts

@@ -0,0 +1,194 @@
+import {
+  checkListingIntegrity,
+  parseLegalContextJson,
+} from "@integraledger/lcp-discovery";
+import { isAtrHash } from "@integraledger/lcp-kernel";
+import type { CallToolResult, McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { readOnlyToolAnnotations } from "../annotations.js";
+import type { LcpMcpPorts } from "../ports.js";
+import { legalContextUrl } from "../well-known.js";
+
+const inputSchema = z.object({
+  serviceUrl: z
+    .url()
+    .describe(
+      "The service's origin (`https://seller.example`) or its full legal-context URL. " +
+        "`/.well-known/legal-context.json` is appended when absent, and a query string, a fragment or " +
+        "credentials in the authority are REFUSED — LCP §2.1 defines the well-known URI with none of them.",
+    ),
+});
+
+/** The Level 1 readout, as ONE literal: it is the tool's most consequential sentence, and a test pins it. */
+const LEVEL_1_DETAIL =
+  "the document declares no atrHash (LCP Level 1) — there is nothing to verify, so this tool cannot say the served terms are the ones committed to";
+
+const outputSchema = z.object({
+  verdict: z
+    .enum(["verified", "mismatch", "unverifiable"])
+    .describe(
+      "verified: the served terms hash to the declared fingerprint. mismatch: they do not. " +
+        "unverifiable: no fingerprint was declared, or the terms format is not machine-readable.",
+    ),
+  wouldHalt: z
+    .boolean()
+    .describe("True when an agent MUST NOT pay against these terms."),
+  atrHashMatch: z
+    .boolean()
+    .describe("True only on `verified` — the LCP §5.3 comparison itself."),
+  legalContextUrl: z.string().describe("The discovery document actually read."),
+  termsUrl: z.string().describe("The terms document that document points at."),
+  declaredAtrHash: z
+    .string()
+    .optional()
+    .describe("The fingerprint the service declared; absent at Level 1."),
+  computedAtrHash: z
+    .string()
+    .optional()
+    .describe(
+      "The fingerprint recomputed here; absent when nothing was fetched.",
+    ),
+  termsBytes: z
+    .number()
+    .int()
+    .optional()
+    .describe("How many bytes of terms were hashed."),
+  acceptanceRequired: z
+    .boolean()
+    .optional()
+    .describe("Present only where the document declares it (LCP Level 3)."),
+  disputeResolutionDeclared: z
+    .boolean()
+    .describe(
+      "Whether the document carries a disputeResolution block (Level 4).",
+    ),
+  detail: z.string().describe("Why this verdict, in one sentence."),
+});
+
+/**
+ * `lcp_verify_before_pay` — the agent guardrail (LCP §5.3). Fetch the service's discovery document and the
+ * terms it points at, recompute the fingerprint, and say whether an agent must halt before paying.
+ *
+ * RE-GROUNDED on the shipped packages, and three things follow from that which a hand-rolled verifier
+ * typically gets wrong:
+ *
+ *  1. The intake is `discovery.parseLegalContextJson`, which THROWS on a non-conformant document. Reading
+ *     fields off whatever JSON came back would let a document that is not a legal-context document at all
+ *     still produce a verdict. A loud failure is the honest answer.
+ *  2. The comparison is `discovery.checkListingIntegrity` — DSC-2, the shipped rule — not a local
+ *     `sha256` and `===`. It carries a check a hand-rolled comparison omits: a listing whose `termsFormat` is not
+ *     machine-readable is `unverifiable` rather than passed through, because an agent cannot evaluate
+ *     terms it cannot read. That NARROWS the tool: `application/pdf` is refused rather than accepted.
+ *  3. **There is no ES256 `signing` block, and its absence is correct.** A verifier that reads a
+ *     seller-signed ATR JWS out of a `signing` object is reading a field LCP does not define: Level 3 is
+ *     the BUYER's signed acceptance over the fingerprint (§3, §4.2), and `legal-context.json` carries no
+ *     seller signature at any level. Serving one would ship a private extension as though it were LCP.
+ *
+ * ABSENCE OF A FINGERPRINT IS NOT A PASS. A Level 1 document (terms, no `atrHash`) halts: the tool was
+ * asked whether the terms can be trusted before paying, and against a document with nothing to verify the
+ * only truthful answer is that it cannot say. A buyer that intends to transact at Level 1 anyway does so
+ * through its own policy engine (`@integraledger/agent-guard`'s stated `requiredLevel`), never by reading a
+ * green light out of a tool that verified nothing.
+ */
+export function registerVerifyBeforePay(
+  server: McpServer,
+  ports: LcpMcpPorts,
+): void {
+  server.registerTool(
+    "lcp_verify_before_pay",
+    {
+      description:
+        "Verify a service's LCP terms BEFORE paying (LCP §5.3). Fetches /.well-known/legal-context.json and " +
+        "the terms it references, recomputes the SHA-256 ATR hash, and compares it to the declared value. " +
+        "Returns `{ verdict, wouldHalt, atrHashMatch, … }`. If `wouldHalt` is true, DO NOT PAY — this is a " +
+        "legally significant decision, and the absence of a declared fingerprint counts as a halt.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations("LCP verify-before-pay", "network"),
+    },
+    async (args) => {
+      const lcUrl = legalContextUrl(args.serviceUrl);
+      const doc = await ports.fetcher.fetch(lcUrl);
+      // Fail-fast at the trust boundary: a non-conformant document is a loud error, never a soft verdict.
+      const listing = parseLegalContextJson(
+        JSON.parse(new TextDecoder().decode(doc.bytes)),
+      );
+      const common = {
+        legalContextUrl: lcUrl,
+        termsUrl: listing.terms,
+        disputeResolutionDeclared: listing.disputeResolution !== undefined,
+        ...(listing.acceptanceRequired !== undefined
+          ? { acceptanceRequired: listing.acceptanceRequired }
+          : {}),
+      };
+
+      const declared = listing.atrHash;
+      if (declared === undefined)
+        return halt({
+          verdict: "unverifiable",
+          wouldHalt: true,
+          atrHashMatch: false,
+          ...common,
+          detail: LEVEL_1_DETAIL,
+        });
+      // `parseLegalContextJson` has ALREADY rejected any atrHash outside /^0x[0-9a-fA-F]{64}$/ — the
+      // discovery schema is stricter than the TypeScript type it produces, which types `atrHash` as a bare
+      // `string`. This narrowing is a compile-time necessity whose throw arm no parsed document reaches,
+      // and it is written as a fail-loud throw rather than a cast precisely so that a future loosening of
+      // that schema surfaces here instead of silently handing a malformed value to DSC-2.
+      if (!isAtrHash(declared))
+        throw new Error(
+          `the document declares an atrHash that is not a 32-byte 0x fingerprint: ${declared}`,
+        );
+
+      const terms = await ports.fetcher.fetch(listing.terms);
+      const integrity = await checkListingIntegrity(
+        listing,
+        terms.bytes,
+        declared,
+      );
+      // `atrHashMatch` tracks DSC-2's own verdict. A listing refused for its FORMAT never reached the
+      // comparison, and reports `false` for the same reason the tool halts on it: nothing was proved.
+      const out = {
+        verdict:
+          integrity.status === "ok"
+            ? ("verified" as const)
+            : integrity.status === "mismatch"
+              ? ("mismatch" as const)
+              : ("unverifiable" as const),
+        wouldHalt: !integrity.ok,
+        atrHashMatch: integrity.ok,
+        ...common,
+        declaredAtrHash: integrity.advertisedAtrHash,
+        computedAtrHash: integrity.servedAtrHash,
+        termsBytes: terms.bytes.byteLength,
+        detail: integrity.detail,
+      };
+      if (!integrity.ok) return halt(out);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `OK to proceed — LCP verification passed.\n\n${JSON.stringify(out, null, 2)}`,
+          },
+        ],
+        structuredContent: out,
+      };
+    },
+  );
+}
+
+/** A halting verdict is a tool EXECUTION error, not a protocol error: MCP routes those to the model so it
+ *  can act on them, which is exactly what "do not pay" needs to reach. */
+function halt(out: Record<string, unknown>): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `HALT — do NOT pay. LCP verification did not pass.\n\n${JSON.stringify(out, null, 2)}`,
+      },
+    ],
+    structuredContent: out,
+    isError: true,
+  };
+}

package/src/version.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * A package manifest's `version`, or a named failure.
+ *
+ * Takes the manifest URL rather than closing over one so that every refusal arm is REACHABLE from a test.
+ * A manifest with no `version`, a non-string one, an empty one, or JSON that is not an object at all each
+ * has to produce an error naming the file — never a server that declares `undefined` as its version to
+ * every connected client.
+ */
+export function readManifestVersion(manifestUrl: URL): string {
+  const manifest: unknown = JSON.parse(readFileSync(manifestUrl, "utf8"));
+  if (
+    typeof manifest !== "object" ||
+    manifest === null ||
+    !("version" in manifest) ||
+    typeof manifest.version !== "string" ||
+    manifest.version.length === 0
+  )
+    throw new Error(
+      `${manifestUrl.href} states no non-empty string "version" — the server cannot declare an identity it cannot read`,
+    );
+  return manifest.version;
+}
+
+/**
+ * This package's own version, READ from its manifest — never restated in source.
+ *
+ * A FUNCTION, and a `const` only for the name beside it, because the two facts have different owners. The
+ * server name is ours to declare and changing it is a deliberate act. The version is the MANIFEST's to
+ * declare, and `changeset version` rewrites it without touching a line of TypeScript. A hardcoded constant
+ * would keep announcing the previous version over the wire to every MCP client, and nothing in a release
+ * would catch it: the manifest and the constant would both be internally consistent while disagreeing with
+ * each other. Reading the manifest makes that drift impossible rather than merely detectable.
+ *
+ * `../package.json` resolves to the package root from `src/` and from `dist/` alike, and npm includes the
+ * manifest in every tarball regardless of `files`, so the read is as valid installed as it is in the
+ * workspace.
+ */
+export function serverVersion(): string {
+  return readManifestVersion(new URL("../package.json", import.meta.url));
+}