@integraledger/lcp-mcp-server 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @integraledger/lcp-mcp-server
+
+## 0.9.0
+
+**First public release** — Apache-2.0, free forever, no account and no token to install.
+
+`lcp-mcp-server` exposes read-only Legal Context Protocol tools to an AI agent over the Model Context
+Protocol: verify before pay, compute an atrHash, and extract or place a terms reference across the nine
+commerce protocols that have a defined placement.
+
+### Six tools, all read-only
+
+`lcp_verify_before_pay` · `lcp_compute_atrhash` · `lcp_extract_reference` · `lcp_place_reference` ·
+`lcp_generate_legal_context` · `lcp_scaffold_integration`
+
+Every tool declares `readOnlyHint` to the host. The annotations are stated rather than omitted because
+MCP documents `destructiveHint` and `openWorldHint` as defaulting to **true** — an unannotated tool reads
+to a client as possibly destructive and open to an arbitrary external world, which is the most alarming
+reading available and not the honest one for this surface.
+
+The **only** network egress is the counterparty terms fetch, and it goes through the same injected,
+SSRF-guarded port the guard uses: HTTPS-only, no redirects, public-unicast re-checked on every fetch, and
+a streaming byte cap. Nothing calls home.
+
+### Wiring
+
+Stdio transport for desktop agent hosts, served so that both current and `2026-07-28` clients resolve
+correctly from one registration. Built against the live MCP `ToolAnnotations` definition
+(`schema/2026-07-28/schema.ts`); the specification check behind that date is recorded in this package's
+README.
+
+### Packaging
+
+- Apache-2.0. LICENSE and NOTICE ship in the tarball; NOTICE states the trademark reservation, names
+  Integra Ledger and AAA-ICDR as the Legal Context Protocol's co-stewards, and records that the
+  seller-side application is separately licensed and not part of this distribution.
+- Consumed as a runnable server over `npx`, so the `@integraledger/lcp-*` protocol line and
+  `@integraledger/agent-guard` are ordinary exact dependencies — there is no second line for it to
+  collide with.
+- `files` ships `src` alongside `dist`, so published source maps resolve inside the tarball.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,16 @@
+Integra LCP MCP Server
+Copyright 2026 Integra Ledger
+
+This product includes software developed by Integra Ledger (https://integraledger.com).
+
+"Integra", "Integra Ledger", and the Integra logo are trademarks of Integra Ledger.
+Trademark use is not granted by the Apache License 2.0 (see Section 6).
+
+The Legal Context Protocol is co-stewarded by Integra Ledger and AAA-ICDR. This package exposes
+read-only LCP tools over the Model Context Protocol and is published free under the Apache License 2.0;
+the specification itself is published at https://legalcontextprotocol.org/standard and is not part of
+this distribution.
+
+Its tools read and verify documents served by ANY party, whether or not that party uses Integra
+software. The seller-side application referenced in the scaffolding output is separately licensed and is
+not part of this distribution.

package/README.md

@@ -0,0 +1,121 @@
+# @integraledger/lcp-mcp-server
+
+The LCP delivery surface for MCP. An agent host that already speaks the Model Context Protocol gains
+legal-context capability with no per-platform integration — and the same server works whichever commerce
+protocol the agent is transacting under, because where the reference belongs is the placement registry's
+decision, not this server's.
+
+```bash
+npm install @integraledger/lcp-mcp-server
+```
+
+> **Free and open source (Apache-2.0). No account, no key, no token, nothing to sign up for.**
+>
+> Every tool is **read-only** and works against **any** counterparty's documents — whether or not they use
+> Integra software. Nothing here calls home: no telemetry, no callback.
+
+Run it over stdio, which is what every desktop agent host speaks:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "lcp": { "command": "npx", "args": ["-y", "@integraledger/lcp-mcp-server"] }
+  }
+}
+```
+
+Or mount it yourself, supplying the ports:
+
+```ts
+import {
+  createLcpMcpServer,
+  nodePorts,
+  serveLcpStdio,
+} from "@integraledger/lcp-mcp-server";
+
+const ports = nodePorts(process.env);
+
+serveLcpStdio(ports); // stdio, ports wired for Node
+const server = createLcpMcpServer(ports); // or build one and connect any MCP transport
+```
+
+## The tools
+
+| Tool | What it does |
+|---|---|
+| `lcp_compute_atrhash` | SHA-256 over terms bytes (inline or fetched) → `atrHash` and the `lcp:sha256:0x…` carrier |
+| `lcp_generate_legal_context` | Builds a validated, ready-to-publish `/.well-known/legal-context.json` |
+| `lcp_verify_before_pay` | Verify before sign (LCP §5.3): fetch, recompute, compare, and say whether an agent must halt |
+| `lcp_scaffold_integration` | Starter code for the seller side or the buyer side |
+| `lcp_place_reference` | Puts a reference into any registered commerce protocol's own document |
+| `lcp_extract_reference` | Reads one back out |
+
+**These `lcp_*` names are stable.** LCP v1.38 §C.9 illustrates a different vocabulary
+(`get_legal_context`, `verify_terms`, …) and says in the same breath that the standard canonizes no tool
+registry. Names a deployed server already answers to are the stronger interoperability fact, so renaming
+them to match an appendix's example would break working integrations and make nothing canonical.
+
+**There is no `create_agreement`, `accept_terms`, `initiate_dispute` or `get_dispute_status`, and there will
+not be.** §C.9's table lists all four. Each asserts a custodian or forum role: holding the agreement record,
+recording the acceptance, running the dispute. Integra is the record engine; the custodian and the forum are
+the deployment's and the counterparties' own. A test asserts their absence.
+
+Every tool **reads**. Nothing here publishes a document, transmits one, or holds a credential:
+`lcp_generate_legal_context` returns a document for you to serve, and `lcp_place_reference` returns a
+document for your agent to send with its own keys.
+
+## Ports
+
+`LcpMcpPorts` has no defaults, and both entries are the reason:
+
+- **`fetcher`** — `agent-guard`'s `makeCachingFetcher`: HTTPS-only, `redirect: "error"`, every resolved
+  address checked public unicast on *every* network fetch, body capped while streaming, LCP §2.6 cache
+  discipline. The URLs this server fetches are chosen by a counterparty, so bare `fetch` here would turn
+  `lcp_verify_before_pay` into an SSRF primitive an agent can be talked into aiming anywhere.
+- **`deployment.reverseDomain`** — optional, and absent by default. Only namespaced placements need it
+  (Mastercard VI's custom Layer-2 constraint type). LCP §8 canonizes no per-protocol integration profile, so
+  a default would write *our* domain into someone else's signed document. Set `LCP_MCP_REVERSE_DOMAIN` and
+  `nodePorts` passes it through.
+
+## One protocol line in the tree
+
+Every `@integraledger/*` package pins its own dependencies **exactly**, so a published version states the
+protocol line it was cut against and cannot be argued out of it. This server and `agent-guard` release
+against the same `@integraledger/lcp-*` line, so installing this puts **one** line of the protocol packages
+in `node_modules`. If a mixed install ever puts two lines in one tree — exact pinning makes that expected
+rather than pathological — the seam stays safe: what this package takes from `agent-guard` is the fetcher
+and nothing else — `makeCachingFetcher`, `nodeDnsLookup`, and the `TermsFetcher` type — whose entire
+vocabulary is `fetch(url: string)` in, `{ bytes, format, fetchedAt }` out, plus a `{ address, family }` DNS
+answer. Not one of those names an `lcp-kernel`, `lcp-binding-core` or `lcp-discovery` type in either
+direction, so two lines never exchange a value.
+
+## Checked against the live MCP specification — 2026-07-30
+
+Checked against the **live MCP specification**, revision `2026-07-28`, not against LCP's Appendix C.
+
+| Checked | Source | Finding |
+|---|---|---|
+| Tool registration | `modelcontextprotocol.io/specification/2026-07-28/server/tools` | `tools/list` + `tools/call`; a server supporting tools MUST declare the capability; tool names SHOULD be `[A-Za-z0-9_.-]`, 1–128 chars, unique per server. `lcp_*` conforms. |
+| Annotation semantics | `schema/2026-07-28/schema.ts`, `ToolAnnotations` | **Defaults are `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`.** `destructiveHint` is "meaningful only when `readOnlyHint == false`". |
+| Trust posture | same page, Data Types → Tool | "clients **MUST** consider tool annotations to be untrusted unless they come from trusted servers". |
+| Result shape | same page, Tool Result | Structured results conform to `outputSchema` when declared; a tool returning structured content SHOULD also return the serialized JSON in a text block. Business-logic failures are `isError: true` in the result, not JSON-RPC errors. |
+| SDK | `@modelcontextprotocol/server@2.0.0`, published 2026-07-27T23:55Z | v2 is the stable line implementing this revision; v1's monolithic `@modelcontextprotocol/sdk` is superseded. Age checked against the workspace's 24h `minimumReleaseAge` on 2026-07-30 — clear. The quarantine exclusion covers `@integraledger/*` only. |
+
+**One finding corrects the plan.** LCP §C.9 says annotations "such as `destructiveHint` and `openWorldHint`
+signal that LCP-aware tools perform legally significant actions". MCP defines `destructiveHint` as *may
+perform destructive updates to its environment* — there is no annotation meaning "legally significant", and
+repurposing one would assert something no client can read. Every tool here is therefore
+`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, with `openWorldHint` true for
+exactly the three that fetch. The legal significance is carried where a client *does* read it: in each
+tool's `description`. Stating `destructiveHint: false` rather than omitting it is load-bearing — the default
+is `true`, so silence would describe every one of these as possibly destructive.
+
+**One finding narrows a tool.** A verifier that reads an ES256 `signing` block out of
+`legal-context.json` is reading a field LCP does not define — Level 3 is the *buyer's* signed acceptance over the
+fingerprint (§3, §4.2), and the discovery document carries no seller signature at any level. Re-grounding on
+`@integraledger/lcp-discovery` drops it, because promoting it would have shipped a private extension as LCP.
+`lcp_verify_before_pay` also inherits DSC-2's machine-readable-format rule, so a `pdf` listing is reported
+`unverifiable` rather than passed through.
+
+Part of [Integra Agent Guard](https://github.com/IntegraLedger/integra-agent-guard).

package/dist/annotations.d.ts

@@ -0,0 +1,41 @@
+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 declare function readOnlyToolAnnotations(title: string, reach: ToolReach): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,GACf,eAAe,CAQjB"}

package/dist/annotations.js

@@ -0,0 +1,41 @@
+/**
+ * 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, reach) {
+    return {
+        title,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: reach === "network",
+    };
+}
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAa,EACb,KAAgB;IAEhB,OAAO;QACL,KAAK;QACL,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK,KAAK,SAAS;KACnC,CAAC;AACJ,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

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

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,53 @@
+import { type PlacementManifest, type ReferencePlacementAdapter, type Refusal } from "@integraledger/lcp-binding-core";
+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 declare function resolveAdapter(protocol: string, ports: LcpMcpPorts): ReferencePlacementAdapter;
+/**
+ * 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 declare const PLACEMENT_SUMMARY_SCHEMA: z.ZodObject<{
+    protocol: z.ZodString;
+    tier: z.ZodString;
+    pattern: z.ZodString;
+    container: z.ZodString;
+    encoding: z.ZodString;
+    field: z.ZodString;
+}>;
+export declare function manifestSummary(manifest: PlacementManifest): {
+    protocol: string;
+    tier: string;
+    pattern: string;
+    container: string;
+    encoding: string;
+    field: string;
+};
+/**
+ * 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 declare function refusalResult(refusal: Refusal): CallToolResult;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,OAAO,EACb,MAAM,iCAAiC,CAAC;AAKzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,WAAW,GACjB,yBAAyB,CAW3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,SAAS,CAAC;IACjD,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;IACtB,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC;IACvB,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;IACtB,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC;CACpB,CAqBE,CAAC;AAEJ,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CASA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAY9D"}

package/dist/dispatch.js

@@ -0,0 +1,81 @@
+import { isKnownProtocolId, KNOWN_PROTOCOL_IDS, } from "@integraledger/lcp-binding-core";
+import { placementFor, supportedProtocols, } from "@integraledger/lcp-placements";
+import { z } from "zod";
+/**
+ * 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, ports) {
+    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
+    .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) {
+    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) {
+    const out = {
+        refused: true,
+        haltClass: refusal.haltClass,
+        code: refusal.code,
+        ...(refusal.detail !== undefined ? { detail: refusal.detail } : {}),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+        structuredContent: out,
+        isError: true,
+    };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,GAInB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,YAAY,EACZ,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,KAAkB;IAElB,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,IAAI,QAAQ,4CAA4C,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxF,CAAC;IACJ,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,OAAO,KAAK,SAAS;QACvB,MAAM,IAAI,KAAK,CACb,6CAA6C,QAAQ,kCAAkC,kBAAkB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzH,CAAC;IACJ,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAOhC,CAAC;KACH,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACrD,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CACP,gFAAgF,CACjF;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACzE,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,CACP,oEAAoE,CACrE;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACrE,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CAAC,iDAAiD,CAAC;CAC/D,CAAC;KACD,QAAQ,CACP,mEAAmE,CACpE,CAAC;AAEJ,MAAM,UAAU,eAAe,CAAC,QAA2B;IAQzD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI;QAClC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,GAAG,GAAG;QACV,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;IACF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACxE,iBAAiB,EAAE,GAAG;QACtB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}