@x207/mcp 0.0.0-stage → 0.0.2

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/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# @x207/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server for x207, the mutual-credit settlement layer for x402 agent payments on NEAR. It lets a model such as Claude read a circle: its rules and members, one member's position and limit, the result of an epoch, a clearing proposal checked by the contract, the marketplace, and one order.
+
+Status: version 0.0.1, pre-release. By default the server has **read tools only**: it signs nothing, sends nothing and holds no key. The eight **write tools** exist only on stdio, only when you turn them on, and only behind the guards below. Node 22.22.2 or newer.
+
+## The six read tools
+
+| Tool | What it answers | Reads |
+| --- | --- | --- |
+| `x207_circle_overview` | The circle and its rules, and its members | contract views `get_circle`, `get_params`; read API `GET /members` (the view `list_members` when there is no read API) |
+| `x207_member_inspect` | One member: status, stake, position, credit limit | read API `GET /members/{account}` and `GET /members/{account}/limits` (the views `member` and `limit` when there is no read API) |
+| `x207_epoch_report` | One clearing epoch, the current one by default: phase, deadlines, cleared ratio and settlements | contract view `get_epoch`; read API `GET /epochs/{n}`, `GET /epochs/{n}/metrics`, `GET /epochs/{n}/settlements` (the view `list_positions` when there is no read API) |
+| `x207_simulate_clearing` | Whether a proposed clearing is valid, and what it would clear | contract view `simulate_clearing` |
+| `x207_search_listings` | Marketplace listings, filtered by account, asset type and class | read API `GET /listings` (needs the read API) |
+| `x207_order_status` | One service order, or a list of orders by party and status | read API `GET /orders/{hash}` and `GET /orders` (needs the read API) |
+
+All six are marked `readOnlyHint: true`. Credit amounts are decimal strings in the smallest unit (6 decimals). A tool that fails returns an error result with a short reason, and a part of an answer that could not be read (for example a read API that is down) is reported in `warnings` while the rest is returned. A result longer than 100,000 characters is cut and says so.
+
+## Configuration
+
+Everything comes from the environment. No variable holds a secret.
+
+| Variable | Meaning |
+| --- | --- |
+| `X207_CIRCLE_CONTRACT` | **Required.** The circle contract account, for example `x207-v013.testnet`. |
+| `X207_CIRCLE_ID` | The circle id in the read API paths. Default `agents-main`. |
+| `X207_RPC_URL` | NEAR JSON-RPC endpoints, comma separated, tried in order. Default: `https://rpc.testnet.fastnear.com` then `https://rpc.testnet.near.org` for a `.testnet` contract, otherwise the mainnet endpoints of `@x207/core`. An endpoint that fails or answers 429 hands over to the next. |
+| `X207_BACKEND_URL` | Base URL of the x207 read API, for example `http://127.0.0.1:8080`. Optional; without it `x207_search_listings` and `x207_order_status` explain what is missing and the other tools answer from the contract. |
+| `X207_TIMEOUT_MS` | Timeout of one RPC or read API call. Default 10000. |
+
+## Use with Claude Desktop (stdio)
+
+Install the package, then add the server to `claude_desktop_config.json`:
+
+```bash
+npm install -g @x207/mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "x207": {
+      "command": "x207-mcp",
+      "env": {
+        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
+        "X207_BACKEND_URL": "http://127.0.0.1:8080"
+      }
+    }
+  }
+}
+```
+
+From a checkout of the repository, build once with `npm run build` and point `command` at `node` with `"args": ["/path/to/sdk/packages/mcp/dist/cli.js"]`. Restart Claude Desktop, then ask for example: "Give me the overview of the x207 circle", "Inspect the member alice.x207-v013.testnet", or "Report epoch 1".
+
+## Write tools (stdio only, off by default)
+
+Set `X207_MCP_WRITE=1` and give the agent's account and keys in the environment. The HTTP server never has these tools, whatever the environment says.
+
+| Tool | What it does | Signs with | Off unless |
+| --- | --- | --- | --- |
+| `x207_pay_request` | Fetches a URL; on an x207 402 it signs a credit voucher and repeats the request. The facilitator of the seller registers the voucher; this tool sends nothing to the chain. | voucher key | a voucher key |
+| `x207_list_offer` | Signs a listing (what the agent offers, what it seeks) and posts it to the marketplace book. | voucher key | a voucher key and `X207_BACKEND_URL` |
+| `x207_make_offer` | Signs an offer or a counter-offer (`in_reply_to`) on a listing and posts it. | voucher key | a voucher key and `X207_BACKEND_URL` |
+| `x207_accept_offer` | Previews the acceptance at the backend, checks what the agent would pay, signs the bundle and posts the acceptance. | voucher key | a voucher key and `X207_BACKEND_URL` |
+| `x207_confirm_milestone` | Signs a notice for a milestone of an order (`confirmed`, `disputed`, `delivered`, `cancelled`) and posts it. | voucher key | a voucher key and `X207_BACKEND_URL` |
+| `x207_join` | Joins the circle and stakes USDT: `join` with the 0.35 NEAR storage deposit, then `ft_transfer_call`. | NEAR key | `X207_ALLOW_OUTFLOWS=1` and `X207_ALLOW_FULL_ACCESS_KEY=1` |
+| `x207_settle` | Pays the residual the agent owes for an epoch (at most the amount due): `ft_transfer_call` with the `settle` message. | NEAR key | `X207_ALLOW_OUTFLOWS=1` and `X207_ALLOW_FULL_ACCESS_KEY=1` |
+| `x207_claim` | Claims what the agent is owed for an epoch, to its own account or its Intents balance: `claim` with 1 yoctoNEAR. | NEAR key | `X207_ALLOW_FULL_ACCESS_KEY=1` |
+
+A tool whose key or switch is missing is not listed at all. The **voucher key** is an off-chain ed25519 key of the agent (`ed25519:<base58>`); it is not a NEAR access key. The **NEAR key** is an access key of the agent's account.
+
+| Variable | Meaning |
+| --- | --- |
+| `X207_MCP_WRITE` | `1` turns the write tools on. Default: off. |
+| `X207_AGENT_ACCOUNT` | The NEAR account of the agent, a member of the circle. Required with `X207_MCP_WRITE=1`. |
+| `X207_AGENT_VOUCHER_KEY` | Voucher secret key. Signs vouchers, listings, offers, acceptances and notices. |
+| `X207_AGENT_NEAR_KEY` | NEAR secret key of the agent account. Signs the transactions of `x207_join`, `x207_settle` and `x207_claim` only. |
+| `X207_MAX_SPEND_SESSION` | Most the agent may commit in one run of the server, in credit units (6 decimals). Default `1000000` (1 credit). |
+| `X207_MAX_PRICE_PER_CALL` | Most one payment, offer or milestone may be. Default `100000` (0.1 credit). |
+| `X207_ALLOWED_COUNTERPARTIES` | Comma separated accounts the agent may deal with. Empty: any active member of the circle. |
+| `X207_ALLOW_OUTFLOWS` | `1` allows `x207_join` and `x207_settle`, which move USDT from the agent into the circle. Default off. |
+| `X207_ALLOW_FULL_ACCESS_KEY` | `1` allows the NEAR key to be a full-access key. Default off. |
+| `X207_ALLOW_PRIVATE_URLS` | `1` lets `x207_pay_request` fetch a URL on this machine or in a private network, for a seller you run yourself. Default off. |
+
+### The guards
+
+1. **Budget of the session.** Every voucher signed, every payment an acceptance would make, every milestone confirmed and every stake or residual paid counts against `X207_MAX_SPEND_SESSION`. A commitment that does not fit is refused before it is signed; one that fails afterwards is given back.
+2. **Price per call.** An amount above `X207_MAX_PRICE_PER_CALL` is refused. The price in a 402 comes from the seller, so the server does not trust it: the check runs on the requirement before the voucher is signed.
+3. **Risky tools are off.** `x207_join` and `x207_settle` stay off until the operator sets `X207_ALLOW_OUTFLOWS=1`.
+4. **Counterparties.** The other party of a payment, offer, acceptance or milestone must be an **active member** of the circle (a contract view), must be in `X207_ALLOWED_COUNTERPARTIES` when that list is set, and is never the agent itself.
+5. **Network.** The URL given to `x207_pay_request` comes from a model, so it can come from a prompt injection. The tool refuses a URL whose host is, or resolves to, a loopback, private, link-local (the metadata service of a cloud machine), carrier-grade NAT, multicast or unspecified address, and names such as `localhost`, `*.local` and `*.internal`. It does not follow redirects (the answer says where a redirect points), gives each call 30 seconds, and reads at most 1 MiB of an answer. `X207_ALLOW_PRIVATE_URLS=1` turns the address check off for a seller on your own machine.
+6. **Keys.** Keys come from the environment only. No result, error or log line contains a key: every text that leaves the server is scrubbed of the configured keys and of anything shaped like an ed25519 secret key. Before a tool sends a transaction the server reads the permission of the NEAR key (`view_access_key`). **A function-call key cannot attach a deposit, and join, stake, settle and claim all attach one** (NEAR protocol rule), so with a function-call key those tools refuse and send nothing. With a full-access key they run only if `X207_ALLOW_FULL_ACCESS_KEY=1`; use a dedicated agent account with a small balance. The tools that sign with the voucher key send no transaction, so they do not need a NEAR key at all.
+
+Also: the backend returns the terms of a bundle together with their hash, and `x207_accept_offer` refuses when the hash does not match the terms; `x207_make_offer` refuses when the listing the book returns does not hash to the hash that was asked for.
+
+### Security limit: the balance of the agent account is the largest possible loss
+
+A NEAR deposit cannot be attached by a function-call key, so the tools that send one (`x207_join`, `x207_settle`, `x207_claim`) need a **full-access key** of the agent account. A full-access key can do anything the account can do, and none of the guards above limits what a stolen or misused key does outside this server. So use a **dedicated agent account** that holds only what the agent may lose: whatever NEAR and USDT sit on that account is the most that can be lost. The session budget and the price cap protect against a model that misbehaves; they do not protect against someone who has the key. Leave `X207_ALLOW_FULL_ACCESS_KEY` unset, and the three tools off, if the agent only needs to pay, list, offer, accept and confirm: those tools sign with the voucher key and never need a NEAR key.
+
+### Claude Desktop with the write tools
+
+```json
+{
+  "mcpServers": {
+    "x207-agent": {
+      "command": "x207-mcp",
+      "env": {
+        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
+        "X207_BACKEND_URL": "http://127.0.0.1:8080",
+        "X207_MCP_WRITE": "1",
+        "X207_AGENT_ACCOUNT": "agent.x207-v013.testnet",
+        "X207_AGENT_VOUCHER_KEY": "ed25519:…",
+        "X207_MAX_SPEND_SESSION": "500000",
+        "X207_MAX_PRICE_PER_CALL": "50000"
+      }
+    }
+  }
+}
+```
+
+Keep the keys out of any file you commit. Then ask for example: "List a translation service for 0.05 credit", "Pay https://seller.example/api/summarize", or "Confirm milestone 1 of order …".
+
+## Use over Streamable HTTP
+
+```bash
+X207_CIRCLE_CONTRACT=x207-v013.testnet X207_BACKEND_URL=http://127.0.0.1:8080 x207-mcp --http --port 3207
+```
+
+The endpoint is `POST http://127.0.0.1:3207/mcp`. It is stateless (no session) and serves **only the read tools**, so it can be shown to anybody who can already read the contract and the read API. `GET /healthz` answers 200. It listens on `127.0.0.1` unless `--host` says otherwise; put a reverse proxy with TLS and a rate limit in front of it before you expose it. On a loopback address it serves only the `Host` names of the loopback (`127.0.0.1`, `localhost`, `[::1]`), so a web page cannot reach it through DNS rebinding; behind a proxy set `X207_ALLOWED_HOSTS=mcp.example.org` (comma separated) to serve exactly those names.
+
+To try it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3207/mcp --transport http --method tools/list
+```
+
+## Use as a library
+
+```ts
+import { configFromEnv, createX207McpServer } from "@x207/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = createX207McpServer(configFromEnv(), "stdio"); // "http" gives the read tools only
+await server.connect(new StdioServerTransport());
+```
+
+## Example output (real data)
+
+Run against the circle `x207-v013.testnet` (contract views from the testnet RPC) and a local read API (`backend`) that served the read model of that circle with its three demo accounts. The tool results below are real; long fields (signatures, hashes of the order spec) are left out and marked by the keys that remain.
+
+`x207_member_inspect` with `{"account": "x207-demo-seller.testnet"}`:
+
+```json
+{
+  "account": "x207-demo-seller.testnet",
+  "member": {
+    "account": "x207-demo-seller.testnet",
+    "status": "active",
+    "stake": "100000000",
+    "limit": "80000000",
+    "outstandingDebt": "0",
+    "headroom": "80000000",
+    "joinedAt": "2026-11-04T04:25:29Z"
+  },
+  "limits": {
+    "items": [
+      {
+        "epoch": null,
+        "oldLimit": "0",
+        "newLimit": "80000000",
+        "status": "active",
+        "reason": "stake",
+        "blockHeight": 276145725
+      }
+    ]
+  },
+  "source": "read API",
+  "warnings": []
+}
+```
+
+`x207_search_listings` with `{"account": "x207-demo-seller.testnet", "limit": 1}`:
+
+```json
+{
+  "items": [
+    {
+      "listingHash": "6eb11d3068ba7e5f84503d9d454242e891fedd676ffd1e03324d4889a304fa41",
+      "account": "x207-demo-seller.testnet",
+      "offer": {
+        "assetType": "near-rpc:access",
+        "assetClass": "B",
+        "quantity": 1,
+        "value": "2000000"
+      },
+      "want": {
+        "assetType": "usdc",
+        "assetClass": "A",
+        "quantity": 1,
+        "value": "2000000"
+      },
+      "expiresAt": "2026-12-31T00:00:00Z",
+      "status": "open"
+    }
+  ],
+  "nextCursor": "eyJhIjoxfQ"
+}
+```
+
+`x207_order_status` with the `hash` of the order of `x207-demo-buyer.testnet`:
+
+```json
+{
+  "orderHash": "332b9bddcc9e17578ba2e55b1fd7d8c0323f7a8225f4ebc03a83b7c0668840a3",
+  "buyer": "x207-demo-buyer.testnet",
+  "seller": "x207-demo-seller.testnet",
+  "status": "open",
+  "budget": "30000000",
+  "unit": "credit",
+  "decimals": 6,
+  "milestones": [
+    {
+      "index": 1,
+      "amount": "10000000",
+      "dueAt": 1796947200,
+      "status": "open"
+    },
+    {
+      "index": 2,
+      "amount": "20000000",
+      "dueAt": 1797811200,
+      "status": "open"
+    }
+  ]
+}
+```
+
+Without a read API the same server still answers `x207_circle_overview`, `x207_member_inspect`, `x207_epoch_report` and `x207_simulate_clearing` from the contract alone: on `x207-v013.testnet` `x207_circle_overview` returns `member_count` 24 and the rules (`epoch_length` 600, fees 10 and 5 bps, `prune_delay_epochs` 2), and `x207_epoch_report` for epoch 1 shows the phase `finalized` with 210 edges and 15 participants.
+
+## Safety
+
+- The read tools call contract views and `GET` requests only; there is no code path in them that signs, sends or changes anything. The write tools are described above and are off by default.
+- Inputs are checked before any call: account ids, hashes, amounts as integer strings, at most 300 edges for a simulation, at most 200 items per page.
+- Path segments are encoded, so an input cannot reach another endpoint of the read API.
+- A circle on testnet reads from a testnet endpoint by default.
+
+## Develop
+
+```bash
+npm run build          # from the repository root of sdk
+npx vitest run packages/mcp
+```
+
+The tests play the NEAR RPC and the read API with a mock `fetch`, run the HTTP transport on a local port, and drive the built `x207-mcp` over stdio (that test skips itself when `dist` is not built).
+
+## License
+
+Apache-2.0

package/dist/backend.d.ts

@@ -0,0 +1,25 @@
+/** The most of one read API answer that the server reads (security review batch 8): a broken or hostile backend cannot fill the memory of the server. */
+export declare const MAX_BACKEND_BYTES = 4194304;
+export type BackendGet = (path: string, query?: Record<string, string | number | boolean | undefined>) => Promise<unknown>;
+export declare class BackendError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** `path` is relative to `/x207/circles/{circle}` and made of fixed words and `seg(...)` parts. */
+export declare function createBackendGet(options: {
+    baseUrl: string;
+    circleId: string;
+    timeoutMs: number;
+    fetch?: typeof fetch;
+}): BackendGet;
+/** One path segment, encoded. */
+export declare const seg: (value: string | number) => string;
+/** A POST with a JSON body against the read API / marketplace book. Used only by the write tools (SD-082), which sign the body first. */
+export type BackendPost = (path: string, body: unknown) => Promise<unknown>;
+export declare function createBackendPost(options: {
+    baseUrl: string;
+    circleId: string;
+    timeoutMs: number;
+    fetch?: typeof fetch;
+}): BackendPost;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.js

@@ -0,0 +1,83 @@
+import { readCapped } from "./net-guard.js";
+/** The most of one read API answer that the server reads (security review batch 8): a broken or hostile backend cannot fill the memory of the server. */
+export const MAX_BACKEND_BYTES = 4_194_304;
+export class BackendError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "BackendError";
+    }
+}
+/** `path` is relative to `/x207/circles/{circle}` and made of fixed words and `seg(...)` parts. */
+export function createBackendGet(options) {
+    const fetchFn = options.fetch ?? fetch;
+    return async (path, query = {}) => {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined)
+                qs.set(k, String(v));
+        const url = `${options.baseUrl}/x207/circles/${encodeURIComponent(options.circleId)}${path}${qs.size > 0 ? `?${qs}` : ""}`;
+        let response;
+        try {
+            response = await fetchFn(url, { method: "GET", headers: { accept: "application/json" }, signal: AbortSignal.timeout(options.timeoutMs) });
+        }
+        catch (error) {
+            throw new BackendError(0, `read API unreachable (${path.split("?")[0]}): ${error.message}`);
+        }
+        const capped = await readCapped(response, MAX_BACKEND_BYTES);
+        if (capped.cut)
+            throw new BackendError(response.status, `read API ${path.split("?")[0]} answered more than ${MAX_BACKEND_BYTES} bytes`);
+        const text = capped.text;
+        if (!response.ok) {
+            let detail = text.replace(/\s+/g, " ").slice(0, 200);
+            try {
+                const body = JSON.parse(text);
+                const e = typeof body.error === "object" ? body.error : undefined;
+                detail = [e?.code ?? (typeof body.error === "string" ? body.error : undefined), e?.message ?? body.message].filter(Boolean).join(": ") || detail;
+            }
+            catch {
+                // not JSON: the cut text stays
+            }
+            throw new BackendError(response.status, `read API ${path.split("?")[0]} answered ${response.status}: ${detail}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new BackendError(response.status, `read API ${path.split("?")[0]} did not answer JSON`);
+        }
+    };
+}
+/** One path segment, encoded. */
+export const seg = (value) => encodeURIComponent(String(value));
+export function createBackendPost(options) {
+    const fetchFn = options.fetch ?? fetch;
+    return async (path, body) => {
+        const url = `${options.baseUrl}/x207/circles/${encodeURIComponent(options.circleId)}${path}`;
+        let response;
+        try {
+            response = await fetchFn(url, { method: "POST", headers: { accept: "application/json", "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(options.timeoutMs) });
+        }
+        catch (error) {
+            throw new BackendError(0, `read API unreachable (POST ${path}): ${error.message}`);
+        }
+        const capped = await readCapped(response, MAX_BACKEND_BYTES);
+        if (capped.cut)
+            throw new BackendError(response.status, `read API POST ${path} answered more than ${MAX_BACKEND_BYTES} bytes`);
+        const text = capped.text;
+        let parsed = null;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // not JSON
+        }
+        if (!response.ok) {
+            const e = parsed?.error;
+            throw new BackendError(response.status, `POST ${path} answered ${response.status}: ${[e?.code, e?.message].filter(Boolean).join(": ") || text.replace(/\s+/g, " ").slice(0, 200)}`);
+        }
+        return parsed;
+    };
+}
+//# sourceMappingURL=backend.js.map

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// x207-mcp: the MCP server of x207. stdio by default (for Claude Desktop and other local clients); `--http` for Streamable HTTP (read tools only).
+//   X207_CIRCLE_CONTRACT=x207-v013.testnet X207_BACKEND_URL=http://127.0.0.1:8080 x207-mcp [--http [--port 3207] [--host 127.0.0.1]]
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigError, configFromEnv } from "./config.js";
+import { startHttpServer } from "./http.js";
+import { createX207McpServer } from "./server.js";
+import { writeConfigFromEnv } from "./write-config.js";
+const USAGE = "usage: x207-mcp [--http [--port <n>] [--host <address>]]   (environment: X207_CIRCLE_CONTRACT, X207_CIRCLE_ID, X207_RPC_URL, X207_BACKEND_URL, X207_TIMEOUT_MS, X207_ALLOWED_HOSTS)";
+async function main(argv) {
+    const args = new Map();
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === "--help" || a === "-h") {
+            console.error(USAGE);
+            return;
+        }
+        if (a === "--http")
+            args.set("http", true);
+        else if (a === "--port" || a === "--host") {
+            const v = argv[(i += 1)];
+            if (v === undefined || v.startsWith("--"))
+                throw new ConfigError(`${a} needs a value\n${USAGE}`);
+            args.set(a.slice(2), v);
+        }
+        else
+            throw new ConfigError(`unknown argument ${a}\n${USAGE}`);
+    }
+    const config = configFromEnv();
+    if (args.has("http")) {
+        if (process.env.X207_MCP_WRITE === "1")
+            console.error("x207-mcp: X207_MCP_WRITE is ignored on HTTP: the HTTP server only has the read tools");
+        const port = args.has("port") ? Number(args.get("port")) : 3207;
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new ConfigError("--port must be an integer from 0 to 65535");
+        const allowedHosts = (process.env.X207_ALLOWED_HOSTS ?? "").split(",").map((h) => h.trim()).filter((h) => h !== "");
+        const { url } = await startHttpServer(config, { port, host: args.get("host") ?? "127.0.0.1", ...(allowedHosts.length > 0 ? { allowedHosts } : {}) });
+        console.error(`x207-mcp: Streamable HTTP (read tools only) on ${url}`);
+        return;
+    }
+    // stdout belongs to the protocol: every message of ours goes to stderr
+    const write = writeConfigFromEnv();
+    await createX207McpServer(config, "stdio", { write }).connect(new StdioServerTransport());
+    console.error(`x207-mcp: stdio, circle ${config.circleContract}, read API ${config.backendUrl ?? "not configured (contract views only)"}, ${write ? `WRITE tools on for ${write.account}` : "read tools only"}`);
+}
+main(process.argv.slice(2)).catch((error) => {
+    console.error(`x207-mcp: ${error instanceof ConfigError ? error.message : error}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+export interface McpConfig {
+    /** The circle contract account, e.g. `x207-v013.testnet`. */
+    circleContract: string;
+    /** The circle id in the paths of the read API, e.g. `agents-main`. */
+    circleId: string;
+    /** NEAR JSON-RPC endpoints, tried in order. */
+    rpcUrls: readonly string[];
+    /** Base URL of the x207 read API (`/x207/circles/{circle}/...`). Without it the tools that need it say so, and the tools that can use the contract views fall back to them. */
+    backendUrl: string | null;
+    /** Timeout of one RPC or read API call in ms. */
+    timeoutMs: number;
+    fetch?: typeof fetch;
+}
+/** Tried in order: a public endpoint that answers 429 hands over to the next. */
+export declare const TESTNET_RPC_URLS: readonly ["https://rpc.testnet.fastnear.com", "https://rpc.testnet.near.org"];
+export declare class ConfigError extends Error {
+}
+/** `X207_CIRCLE_CONTRACT` (required), `X207_CIRCLE_ID` (default `agents-main`), `X207_RPC_URL` (comma separated; default by network), `X207_BACKEND_URL` (optional), `X207_TIMEOUT_MS`. */
+export declare function configFromEnv(env?: Record<string, string | undefined>): McpConfig;
+//# sourceMappingURL=config.d.ts.map