@integraledger/lcp-mcp-server 0.9.0

package/dist/well-known.js

@@ -0,0 +1,45 @@
+/** LCP §2.1: the one location a service publishes its legal context at. */
+export const WELL_KNOWN_PATH = "/.well-known/legal-context.json";
+/**
+ * The canonical discovery URL for a service, from either a bare origin or the well-known URL itself.
+ *
+ * IDEMPOTENT over both spellings on purpose: an agent that already holds the full
+ * `https://seller.example/.well-known/legal-context.json` and one that holds only `https://seller.example`
+ * are the same caller a moment apart, and appending the path twice would 404 against a conformant seller.
+ *
+ * PARSED, NEVER CONCATENATED, and the refusals are why. Appending to the raw string put the well-known path
+ * INSIDE whatever the input already carried: `https://x.example?level=3` became
+ * `https://x.example?level=3/.well-known/legal-context.json`, which fails on the wire as a broken discovery
+ * document at the service root instead of as the input error it is. So the input is parsed, and three
+ * shapes are refused BY NAME rather than silently rewritten:
+ *
+ *  - **A query or a fragment.** LCP §2.1 defines the well-known URI with no parameters, and a query a
+ *    conformant seller ignores is a request for behaviour the standard does not define — appending one as
+ *    a private hint only works against a server that already agreed to read it. The level a document
+ *    satisfies is read off the document.
+ *  - **Credentials in the authority.** `URL`'s `origin` drops them, so parsing `https://u:p@h.example`
+ *    would hand back a URL addressed differently from the one the caller supplied — the one thing
+ *    concatenation got right. Silently changing who is being talked to is worse than refusing.
+ *  - **No network origin at all.** `mailto:`, `data:`, `file:`, `urn:` — each accepted by the tools'
+ *    `z.url()`, and none of them has a well-known location.
+ *
+ * SCHEME IS NOT CHECKED HERE. `agent-guard`'s fetcher is HTTPS-only and refuses `http:` on the way out; a
+ * second copy of that rule in this function would be duplicated truth with nothing keeping the two in step.
+ *
+ * A THROW is the right shape inside a tool handler: the MCP SDK surfaces a handler throw as an
+ * `isError: true` `tools/call` result, so the model reads the refusal rather than a transport failure.
+ */
+export function legalContextUrl(serviceUrl) {
+    const url = new URL(serviceUrl);
+    if (url.origin === "null")
+        throw new Error(`not a service URL — \`${serviceUrl}\` has no network origin, so it has no well-known location`);
+    if (url.search !== "" || url.hash !== "")
+        throw new Error(`not a service URL — \`${serviceUrl}\` carries a query or fragment, and LCP §2.1 defines the well-known URI with neither`);
+    if (url.username !== "" || url.password !== "")
+        throw new Error(`not a service URL — \`${serviceUrl}\` carries credentials in its authority, which the well-known location does not preserve`);
+    const path = url.pathname.replace(/\/+$/, "");
+    return path.endsWith(WELL_KNOWN_PATH)
+        ? `${url.origin}${path}`
+        : `${url.origin}${path}${WELL_KNOWN_PATH}`;
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAAG,iCAAiC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;QACvB,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,4DAA4D,CAChG,CAAC;IACJ,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE;QACtC,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,sFAAsF,CAC1H,CAAC;IACJ,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE;QAC5C,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,0FAA0F,CAC9H,CAAC;IACJ,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC;QACnC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE;QACxB,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,eAAe,EAAE,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@integraledger/lcp-mcp-server",
+  "version": "0.9.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "lcp-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IntegraLedger/integra-agent-guard.git",
+    "directory": "packages/lcp-mcp-server"
+  },
+  "dependencies": {
+    "@integraledger/lcp-authority": "0.10.1",
+    "@integraledger/lcp-binding-core": "0.10.1",
+    "@integraledger/lcp-discovery": "0.10.1",
+    "@integraledger/lcp-evidence": "0.10.1",
+    "@integraledger/lcp-kernel": "0.10.1",
+    "@integraledger/lcp-placement-ack": "0.10.1",
+    "@integraledger/lcp-placement-ap2": "0.10.1",
+    "@integraledger/lcp-placements": "0.10.1",
+    "@integraledger/lcp-verify": "0.10.1",
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.4.3",
+    "@integraledger/agent-guard": "0.9.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "vitest": "4.1.10"
+  },
+  "license": "Apache-2.0",
+  "description": "Read-only Model Context Protocol server exposing Legal Context Protocol tools to an AI agent — verify before pay, compute an atrHash, extract and place references across the nine commerce protocols that have one. Works against any seller.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "mcp",
+    "model-context-protocol",
+    "agentic-commerce",
+    "ai-agent",
+    "verify-before-pay",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-agent-guard/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-agent-guard/tree/main/packages/lcp-mcp-server#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/annotations.ts

@@ -0,0 +1,53 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/server";
+
+/**
+ * Does the tool reach outside this process?
+ *
+ * The ONLY axis on which this server's tools differ. Everything here reads; nothing writes, publishes,
+ * files, or settles — see the mandate boundary in `server.ts`.
+ */
+export type ToolReach = "network" | "closed";
+
+/**
+ * The annotations every tool on this server carries, per the LIVE MCP `ToolAnnotations` definition
+ * (`schema/2026-07-28/schema.ts`, read 2026-07-30; the specification check behind that date is recorded in
+ * this package's README).
+ *
+ * THE DEFAULTS ARE WHY THESE ARE STATED RATHER THAN OMITTED. MCP documents `destructiveHint` as
+ * **`Default: true`** and `openWorldHint` as **`Default: true`**, with `readOnlyHint` and `idempotentHint`
+ * defaulting to `false`. An unannotated tool therefore reads to a client as *possibly destructive, possibly
+ * non-idempotent, open to an arbitrary external world* — the most alarming reading available. Every value
+ * below is the honest one for a surface that computes, fetches and reads, so stating them is not decoration:
+ * omission would actively misdescribe the tools.
+ *
+ * THIS IS ALSO WHERE LCP's APPENDIX C IS AN ILLUSTRATION AND THE HOST PROTOCOL BINDS. LCP v1.38 §C.9
+ * says tool annotations "such as `destructiveHint` and `openWorldHint` signal that LCP-aware tools perform
+ * legally significant actions". MCP's own definition says something narrower and different:
+ * `destructiveHint` means "the tool may perform destructive updates to **its environment**", and it is
+ * "meaningful only when `readOnlyHint == false`". There is no MCP annotation that means "legally
+ * significant", and repurposing one to imply it would be an assertion MCP's clients cannot read. So the
+ * annotations here say what MCP defines them to say — `destructiveHint: false`, because none of these tools
+ * updates anything — and the legal significance is carried where a client can actually read it: in each
+ * tool's `description`.
+ *
+ * `destructiveHint: false` is stated even though `readOnlyHint: true` makes it formally not-meaningful. The
+ * spec says the property is meaningful only when `readOnlyHint === false`; it does not require a client to
+ * consult `readOnlyHint` first, and a client that reads `annotations.destructiveHint` directly would
+ * otherwise inherit the `true` default. Stating it closes that read at no cost.
+ *
+ * A last honesty note that belongs in the code rather than only in a doc: MCP requires clients to
+ * "consider tool annotations to be untrusted unless they come from trusted servers". These are hints a
+ * server asserts about itself. They are not a security control and nothing here treats them as one.
+ */
+export function readOnlyToolAnnotations(
+  title: string,
+  reach: ToolReach,
+): ToolAnnotations {
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: reach === "network",
+  };
+}

package/src/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { nodePorts } from "./node-ports.js";
+import { serveLcpStdio } from "./stdio.js";
+
+serveLcpStdio(nodePorts(process.env));

package/src/dispatch.ts

@@ -0,0 +1,122 @@
+import {
+  isKnownProtocolId,
+  KNOWN_PROTOCOL_IDS,
+  type PlacementManifest,
+  type ReferencePlacementAdapter,
+  type Refusal,
+} from "@integraledger/lcp-binding-core";
+import {
+  placementFor,
+  supportedProtocols,
+} from "@integraledger/lcp-placements";
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { LcpMcpPorts } from "./ports.js";
+
+/**
+ * The one place this server turns a wire token into a placement adapter — `@integraledger/lcp-placements`,
+ * the placement registry, and nothing else. No local map, no `switch`, no import of an individual
+ * `placement-*` package: a protocol added to the registry is served here the moment it is published, and
+ * a protocol the registry does not carry is reported as an absence rather than guessed at.
+ *
+ * TWO DISTINCT FAILURES, and collapsing them would lose the fix. `"acp2"` is not a protocol — a typo, and
+ * the answer is the closed set. `"mcp"` IS a protocol id and has no field placement at all: LCP §C.9 and
+ * §10 make MCP a delivery mechanism, which is what THIS PACKAGE is, so there is no document field for a
+ * reference to ride in. Answering "unknown protocol" there would invite someone to go build
+ * `placement-mcp`, which should not exist.
+ */
+export function resolveAdapter(
+  protocol: string,
+  ports: LcpMcpPorts,
+): ReferencePlacementAdapter {
+  if (!isKnownProtocolId(protocol))
+    throw new Error(
+      `"${protocol}" is not an LCP protocol id — known ids: ${KNOWN_PROTOCOL_IDS.join(", ")}`,
+    );
+  const adapter = placementFor(protocol, ports.deployment);
+  if (adapter === undefined)
+    throw new Error(
+      `no reference placement is registered for "${protocol}" — this build can place into: ${supportedProtocols().join(", ")}`,
+    );
+  return adapter;
+}
+
+/**
+ * The manifest facts a caller needs to understand where the reference went, without shipping the whole
+ * manifest (its `specRef` prose and alias table are documentation, not a tool result).
+ *
+ * DECLARED ONCE, and both placement tools use it, so the two cannot describe the same block differently.
+ *
+ * `container` reports the KIND only. The container is a discriminated union whose tagged-array arm carries
+ * the array path, tag field, tag value and value field — everything a reader needs is already in `field`,
+ * which the manifest keeps as the human-readable locator precisely so a stranger does not have to
+ * reassemble one from the walker's parts.
+ */
+export const PLACEMENT_SUMMARY_SCHEMA: z.ZodObject<{
+  protocol: z.ZodString;
+  tier: z.ZodString;
+  pattern: z.ZodString;
+  container: z.ZodString;
+  encoding: z.ZodString;
+  field: z.ZodString;
+}> = z
+  .object({
+    protocol: z.string().describe("The LCP protocol id."),
+    tier: z
+      .string()
+      .describe(
+        "§8.3 wire compatibility: A works against stock today, B needs upstream change.",
+      ),
+    pattern: z.string().describe("The §8.3 binding pattern this carrier is."),
+    container: z
+      .string()
+      .describe(
+        "How the field is reached: object-path, tagged-array or header-map.",
+      ),
+    encoding: z.string().describe("How the reference sits in the field."),
+    field: z
+      .string()
+      .describe("The host-protocol field the reference occupies."),
+  })
+  .describe(
+    "The placement manifest's own account of where the reference sits.",
+  );
+
+export function manifestSummary(manifest: PlacementManifest): {
+  protocol: string;
+  tier: string;
+  pattern: string;
+  container: string;
+  encoding: string;
+  field: string;
+} {
+  return {
+    protocol: manifest.protocol,
+    tier: manifest.tier,
+    pattern: manifest.pattern,
+    container: manifest.container.kind,
+    encoding: manifest.encoding,
+    field: manifest.field,
+  };
+}
+
+/**
+ * A placement refusal, as MCP sees it.
+ *
+ * Refusals are VALUES in this codebase, never exceptions — and they stay values here: the halt class and
+ * the stable code travel in `structuredContent` where a caller can branch on them, while `isError: true` is
+ * what makes MCP hand the whole thing to the model instead of swallowing it.
+ */
+export function refusalResult(refusal: Refusal): CallToolResult {
+  const out = {
+    refused: true,
+    haltClass: refusal.haltClass,
+    code: refusal.code,
+    ...(refusal.detail !== undefined ? { detail: refusal.detail } : {}),
+  };
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(out, null, 2) }],
+    structuredContent: out,
+    isError: true,
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  readOnlyToolAnnotations,
+  type ToolReach,
+} from "./annotations.js";
+export {
+  manifestSummary,
+  refusalResult,
+  resolveAdapter,
+} from "./dispatch.js";
+export { isoNow, nodePorts, REVERSE_DOMAIN_ENV } from "./node-ports.js";
+export type { LcpMcpPorts } from "./ports.js";
+export { createLcpMcpServer, LCP_TOOL_NAMES, SERVER_NAME } from "./server.js";
+export { serveLcpStdio } from "./stdio.js";
+export { serverVersion } from "./version.js";
+export { legalContextUrl, WELL_KNOWN_PATH } from "./well-known.js";

package/src/node-ports.ts

@@ -0,0 +1,38 @@
+import { makeCachingFetcher, nodeDnsLookup } from "@integraledger/agent-guard";
+import type { LcpMcpPorts } from "./ports.js";
+
+/** The environment variable a deployment states its own reverse-domain namespace in. */
+export const REVERSE_DOMAIN_ENV = "LCP_MCP_REVERSE_DOMAIN";
+
+/** The wall clock as an ISO-8601 instant — the `now` port the terms fetcher requires. */
+export function isoNow(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * The Node wiring: the real, guarded terms fetcher plus whatever the environment states.
+ *
+ * The fetcher is `agent-guard`'s — HTTPS-only, `redirect: "error"`, every resolved address checked public
+ * unicast on every network fetch, body capped while streaming, LCP §2.6 cache discipline. This server
+ * fetches URLs a COUNTERPARTY chose, so that is not hardening, it is the minimum: bare `fetch` here would
+ * turn `lcp_verify_before_pay` into an SSRF primitive an agent can be talked into aiming anywhere.
+ *
+ * `LCP_MCP_REVERSE_DOMAIN` is absent by default and stays absent. It is only needed by placements whose
+ * carrier is namespaced under the deployment's own domain (Mastercard VI's custom Layer-2 constraint type),
+ * and LCP §8 canonizes no per-protocol integration profile — so a default here would write Integra's domain
+ * into someone else's signed document in every deployment that forgot to set it. Unset, that one placement
+ * throws and names what is missing; every other tool is unaffected.
+ */
+export function nodePorts(
+  env: Readonly<Record<string, string | undefined>>,
+): LcpMcpPorts {
+  const reverseDomain = env[REVERSE_DOMAIN_ENV];
+  return {
+    fetcher: makeCachingFetcher({
+      httpFetch: fetch,
+      now: isoNow,
+      lookup: nodeDnsLookup,
+    }),
+    ...(reverseDomain !== undefined ? { deployment: { reverseDomain } } : {}),
+  };
+}

package/src/ports.ts

@@ -0,0 +1,23 @@
+import type { TermsFetcher } from "@integraledger/agent-guard";
+import type { PlacementDeployment } from "@integraledger/lcp-placements";
+
+/**
+ * What a deployment supplies before this server can serve anything.
+ *
+ * NO DEFAULTS, and both entries are the reason. The fetcher is the buyer gate's own HTTPS-only,
+ * SSRF-guarded, size-capped, LCP §2.6-cached implementation (`agent-guard`'s `makeCachingFetcher`) — the
+ * URLs this server fetches are chosen by a *counterparty*, so a server that quietly defaulted to bare
+ * `fetch` would silently drop the guard that makes those fetches safe. `nodePorts` wires the real one for a
+ * Node deployment; a Workers deployment supplies its own `lookup`.
+ *
+ * `deployment` is genuinely optional rather than defaulted: eight of the nine registered placements are
+ * singletons needing nothing from it, and only Mastercard VI's namespaced factory requires a reverse domain.
+ * Omitting it makes `lcp_place_reference` throw for that ONE protocol, naming what is missing — which is the
+ * registry's own rule, not a second copy of it here.
+ */
+export interface LcpMcpPorts {
+  /** Fetches terms and discovery documents. See `@integraledger/agent-guard`'s `makeCachingFetcher`. */
+  readonly fetcher: TermsFetcher;
+  /** The deployment's own reverse-domain namespace, for namespaced placement registrations. */
+  readonly deployment?: PlacementDeployment;
+}

package/src/server.ts

@@ -0,0 +1,70 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { LcpMcpPorts } from "./ports.js";
+import { registerComputeAtrHash } from "./tools/compute-atrhash.js";
+import { registerExtractReference } from "./tools/extract-reference.js";
+import { registerGenerateLegalContext } from "./tools/generate-legal-context.js";
+import { registerPlaceReference } from "./tools/place-reference.js";
+import { registerScaffoldIntegration } from "./tools/scaffold-integration.js";
+import { registerVerifyBeforePay } from "./tools/verify-before-pay.js";
+import { serverVersion } from "./version.js";
+
+/**
+ * The MCP server name, and the reason it is not the one the specification illustrates.
+ *
+ * LCP v1.38 §C.9 shows a different tool vocabulary (`get_legal_context`, `verify_terms`, …) and says in the
+ * same breath that "the standard does not canonize a particular tool registry" and that the MCP stewards
+ * are invited to publish canonical names. An appendix example is not an interoperability fact: names an
+ * agent host has already learned are, because a host that has learned a name breaks when it changes.
+ * Renaming these to match an illustration the specification itself declines to canonize would break working
+ * integrations and make nothing canonical in exchange.
+ */
+export const SERVER_NAME = "lcp-mcp";
+
+/**
+ * Every tool this server exposes, in registration order.
+ *
+ * Exported so the boundary can be ASSERTED rather than described. LCP §C.9's illustrative table also lists
+ * `accept_terms`, `create_agreement`, `get_agreement`, `initiate_dispute` and `get_dispute_status`; none of
+ * them is here and none is coming. Recording an acceptance, holding the agreement record, or running the
+ * dispute are the roles of a custodian and a forum — we are neither. Integra is the record engine; the
+ * custodian of the record and the forum for the dispute are the deployment's and the counterparties' own.
+ * A server that offered `initiate_dispute` would be asserting an operating role the mandate forbids, and it
+ * is far easier to not add a seventh tool than to remove it after an agent has learned to call it.
+ */
+export const LCP_TOOL_NAMES = [
+  "lcp_compute_atrhash",
+  "lcp_generate_legal_context",
+  "lcp_verify_before_pay",
+  "lcp_scaffold_integration",
+  "lcp_place_reference",
+  "lcp_extract_reference",
+] as const;
+
+/**
+ * Build the LCP MCP server.
+ *
+ * A FACTORY, not a singleton, because that is what the transports want: `serveStdio` and
+ * `createMcpHandler` both take a factory and may build one instance per connection or per era. Handing
+ * them a shared instance would make one client's state another's.
+ *
+ * The server ends up declaring `tools` and nothing else, and it declares it by REGISTERING tools rather
+ * than by asserting a capability in the constructor. MCP requires a server that supports tools to declare
+ * the capability and does not permit declaring one that is not served; the SDK derives the declaration from
+ * the registrations, so a constructor-side `{ capabilities: { tools: {} } }` is a second statement of the
+ * same fact that cannot be wrong today and could be wrong tomorrow. Measured: removing it changes nothing a
+ * client sees, which is exactly why it does not belong.
+ *
+ * There are no resources and no prompts. §C.9 illustrates both — `lcp://agreement/{id}`,
+ * `dispute_evidence_assembly` — and every one of its examples is an agreement or dispute surface, which is
+ * the boundary above. When there is a resource to serve that is not one of those, it is declared then.
+ */
+export function createLcpMcpServer(ports: LcpMcpPorts): McpServer {
+  const server = new McpServer({ name: SERVER_NAME, version: serverVersion() });
+  registerComputeAtrHash(server, ports);
+  registerGenerateLegalContext(server, ports);
+  registerVerifyBeforePay(server, ports);
+  registerScaffoldIntegration(server);
+  registerPlaceReference(server, ports);
+  registerExtractReference(server, ports);
+  return server;
+}

package/src/stdio.ts

@@ -0,0 +1,25 @@
+import {
+  type ServeStdioOptions,
+  type StdioServerHandle,
+  serveStdio,
+} from "@modelcontextprotocol/server/stdio";
+import type { LcpMcpPorts } from "./ports.js";
+import { createLcpMcpServer } from "./server.js";
+
+/**
+ * Serve this server over stdio — the transport every desktop agent host speaks.
+ *
+ * `serveStdio` rather than a hand-wired `StdioServerTransport`: the MCP v2 entry owns the era decision for
+ * the connection, pinning ONE instance from the factory for its lifetime, so a 2025-era client and a
+ * 2026-07-28 client are both served correctly from the same registration. Hand-wiring a single transport
+ * would serve only one of them, and which one would depend on the SDK version rather than on the client.
+ *
+ * `options` is passed straight through — a test drives a linked in-memory transport through it, and a
+ * deployment that binds stdio to a socket per MCP's custom-transport guidance uses the same door.
+ */
+export function serveLcpStdio(
+  ports: LcpMcpPorts,
+  options?: ServeStdioOptions,
+): StdioServerHandle {
+  return serveStdio(() => createLcpMcpServer(ports), options);
+}

package/src/tools/compute-atrhash.ts

@@ -0,0 +1,87 @@
+import { encodeLegalContextString } from "@integraledger/lcp-binding-core";
+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({
+  terms: z
+    .string()
+    .optional()
+    .describe(
+      "Raw terms text to hash, as UTF-8 bytes. Provide this OR termsUrl, never both.",
+    ),
+  termsUrl: z
+    .url()
+    .optional()
+    .describe(
+      "HTTPS URL of the terms document to fetch and hash. Provide this OR terms, never both.",
+    ),
+});
+
+const outputSchema = z.object({
+  atrHash: z.string().describe("0x-prefixed SHA-256 of the terms bytes."),
+  bytes: z.number().int().describe("How many bytes were hashed."),
+  reference: z
+    .string()
+    .describe("The LCP §8.1 carrier string, `lcp:sha256:0x…`."),
+});
+
+/**
+ * `lcp_compute_atrhash` — the ATR fingerprint of a terms document, from inline text or a fetchable URL.
+ *
+ * Grounded on `kernel.hashAtr` (the one implementation of the ATR fingerprint) and
+ * `binding-core.encodeLegalContextString` (the one implementation of the §8.1 carrier), rather than on a
+ * local `createHash("sha256")` and a template literal. The carrier string it returns is the exact input
+ * `lcp_place_reference` takes, so compute → place composes without the agent reformatting anything.
+ *
+ * EXACTLY ONE of `terms`/`termsUrl`. Neither is a caller who has not said what to hash; both is a caller
+ * whose two inputs may disagree, and picking one would silently hash something the caller did not mean.
+ */
+export function registerComputeAtrHash(
+  server: McpServer,
+  ports: LcpMcpPorts,
+): void {
+  server.registerTool(
+    "lcp_compute_atrhash",
+    {
+      description:
+        "Compute the LCP ATR hash — the SHA-256 over the exact terms bytes — from inline `terms` text " +
+        "or a fetchable `termsUrl`. Returns `{ atrHash, bytes, reference }`, where `reference` is the " +
+        "canonical `lcp:sha256:0x…` carrier string. A `termsUrl` is fetched over HTTPS only, is not " +
+        "followed through redirects, and is size-capped.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations("Compute LCP ATR hash", "network"),
+    },
+    async (args) => {
+      if (args.terms !== undefined && args.termsUrl !== undefined)
+        throw new Error(
+          "provide exactly one of `terms` or `termsUrl` — both were supplied, and they may disagree",
+        );
+      let bytes: Uint8Array;
+      if (args.termsUrl !== undefined)
+        bytes = (await ports.fetcher.fetch(args.termsUrl)).bytes;
+      else if (args.terms !== undefined)
+        bytes = new TextEncoder().encode(args.terms);
+      else
+        throw new Error(
+          "provide exactly one of `terms` or `termsUrl` — neither was supplied",
+        );
+
+      const atrHash = await hashAtr(bytes);
+      const out = {
+        atrHash,
+        bytes: bytes.byteLength,
+        reference: encodeLegalContextString({ type: "sha256", value: atrHash }),
+      };
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(out, null, 2) },
+        ],
+        structuredContent: out,
+      };
+    },
+  );
+}

package/src/tools/extract-reference.ts

@@ -0,0 +1,86 @@
+import { encodeLegalContextString } 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";
+
+const inputSchema = z.object({
+  protocol: z
+    .string()
+    .describe(
+      "The commerce protocol this document belongs to. See the description for the set this build reads.",
+    ),
+  document: z
+    .record(z.string(), z.unknown())
+    .describe("The host protocol's own document, as JSON."),
+});
+
+const outputSchema = z.object({
+  reference: z
+    .string()
+    .describe("The LCP §8.1 carrier string recovered from the document."),
+  type: z.string().describe("The §8.2 carrier type, e.g. `sha256`."),
+  value: z.string().describe("The carrier value, e.g. the 0x ATR hash."),
+  placement: PLACEMENT_SUMMARY_SCHEMA,
+});
+
+/**
+ * `lcp_extract_reference` — recover an LCP reference from a commerce protocol's own document.
+ *
+ * The read half of `lcp_place_reference`, through the same placement registry, so a document one produces the
+ * other reads. It is what lets an agent on the receiving side of a counterparty's ACP session, x402
+ * challenge or A2A task ask "which terms does this document say govern it?" without knowing where that
+ * protocol keeps them.
+ *
+ * A DOCUMENT WITH NO REFERENCE REFUSES; it never returns a placeholder. That refusal is the answer — the
+ * counterparty placed nothing — and an empty string or a null would read as a reference to nothing.
+ *
+ * The adapter reads the manifest's declared field AND its declared aliases, so a counterparty using a
+ * spelling the manifest records as accepted is read rather than refused. Which spellings those are is the
+ * manifest's data, not this tool's opinion.
+ */
+export function registerExtractReference(
+  server: McpServer,
+  ports: LcpMcpPorts,
+): void {
+  server.registerTool(
+    "lcp_extract_reference",
+    {
+      description:
+        "Recover the LCP legal-context reference from a commerce protocol's own document, reading the " +
+        "field that protocol's placement manifest declares. Supported protocols in this build: " +
+        `${supportedProtocols().join(", ")}. Returns the \`lcp:{type}:{value}\` carrier string and where ` +
+        "it was found. A document carrying no reference is refused, not answered with an empty value.",
+      inputSchema,
+      outputSchema,
+      annotations: readOnlyToolAnnotations(
+        "Extract an LCP reference",
+        "closed",
+      ),
+    },
+    (args) => {
+      const adapter = resolveAdapter(args.protocol, ports);
+      const outcome = adapter.extract(args.document);
+      if (!("ok" in outcome)) return refusalResult(outcome);
+      const out = {
+        reference: encodeLegalContextString(outcome.value),
+        type: outcome.value.type,
+        value: outcome.value.value,
+        placement: manifestSummary(adapter.manifest),
+      };
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(out, null, 2) },
+        ],
+        structuredContent: out,
+      };
+    },
+  );
+}