@x207/mcp 0.0.0-stage → 0.0.1

package/dist/config.js

@@ -0,0 +1,31 @@
+// Configuration of the x207 MCP server (SD-081). Everything comes from the environment; nothing here is a secret, and the read tools never need a key.
+import { RPC_URLS } from "@x207/core";
+/** Tried in order: a public endpoint that answers 429 hands over to the next. */
+export const TESTNET_RPC_URLS = ["https://rpc.testnet.fastnear.com", "https://rpc.testnet.near.org"];
+const ACCOUNT = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const CIRCLE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+export 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 function configFromEnv(env = process.env) {
+    const circleContract = env.X207_CIRCLE_CONTRACT?.trim() ?? "";
+    if (!ACCOUNT.test(circleContract))
+        throw new ConfigError("X207_CIRCLE_CONTRACT must be the circle contract account, e.g. x207-v013.testnet");
+    const circleId = env.X207_CIRCLE_ID?.trim() || "agents-main";
+    if (!CIRCLE_ID.test(circleId))
+        throw new ConfigError("X207_CIRCLE_ID must be a circle id such as agents-main");
+    const explicit = (env.X207_RPC_URL ?? "").split(",").map((s) => s.trim()).filter((s) => s !== "");
+    for (const url of explicit)
+        if (!/^https?:\/\/[^\s]+$/.test(url))
+            throw new ConfigError(`X207_RPC_URL: ${JSON.stringify(url)} is not an http(s) URL`);
+    // a testnet circle must not read from mainnet endpoints by default
+    const rpcUrls = explicit.length > 0 ? explicit : circleContract.endsWith(".testnet") ? [...TESTNET_RPC_URLS] : [...RPC_URLS];
+    const backend = env.X207_BACKEND_URL?.trim().replace(/\/+$/, "") ?? "";
+    if (backend !== "" && !/^https?:\/\/[^\s]+$/.test(backend))
+        throw new ConfigError("X207_BACKEND_URL must be an http(s) URL");
+    const timeoutMs = env.X207_TIMEOUT_MS === undefined ? 10_000 : Number(env.X207_TIMEOUT_MS);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 120_000)
+        throw new ConfigError("X207_TIMEOUT_MS must be an integer from 100 to 120000");
+    return { circleContract, circleId, rpcUrls, backendUrl: backend === "" ? null : backend, timeoutMs };
+}
+//# sourceMappingURL=config.js.map

package/dist/guards.d.ts

@@ -0,0 +1,25 @@
+import type { CircleViewFn } from "@x207/core";
+import type { WriteConfig } from "./write-config.js";
+export type NearKeyKind = "none" | "function-call" | "full-access" | "unknown";
+export declare class Guards {
+    #private;
+    readonly cfg: WriteConfig;
+    private readonly view;
+    constructor(cfg: WriteConfig, view: CircleViewFn);
+    /** Total committed in this session (credit units). */
+    get spent(): bigint;
+    get remaining(): bigint;
+    /** Guard 2: the price of ONE payment, offer or milestone. */
+    price(amount: bigint, what: string): void;
+    /** Guard 1: the budget of the session. Adds `amount` when it fits; call it right before the commitment is signed. */
+    spend(amount: bigint, what: string): void;
+    /** Gives back what `spend` took when the commitment was not made after all. */
+    release(amount: bigint): void;
+    /** Guard 4: only an ACTIVE member of the circle, and, when the operator wrote a list, only a member of that list. Never the agent itself. */
+    counterparty(account: string): Promise<void>;
+    /** Guard 3: tools that move USDT or NEAR out of the agent into the circle stay off unless the operator turns them on. */
+    outflows(tool: string): void;
+    /** Guard 5: what the NEAR key may do. A function-call key cannot attach a deposit, so no tool that sends one can run with it. */
+    nearKey(kind: NearKeyKind, tool: string): void;
+}
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.js

@@ -0,0 +1,67 @@
+import { ToolError } from "./tools.js";
+export class Guards {
+    cfg;
+    view;
+    #spent = 0n;
+    constructor(cfg, view) {
+        this.cfg = cfg;
+        this.view = view;
+    }
+    /** Total committed in this session (credit units). */
+    get spent() {
+        return this.#spent;
+    }
+    get remaining() {
+        return this.cfg.maxSpendSession - this.#spent;
+    }
+    /** Guard 2: the price of ONE payment, offer or milestone. */
+    price(amount, what) {
+        if (amount < 0n)
+            throw new ToolError(`refused: ${what} is negative`); // cross review UM-112, F4
+        if (amount > this.cfg.maxPricePerCall)
+            throw new ToolError(`refused: ${what} of ${amount} is above X207_MAX_PRICE_PER_CALL (${this.cfg.maxPricePerCall}); the price the seller names is not trusted`);
+    }
+    /** Guard 1: the budget of the session. Adds `amount` when it fits; call it right before the commitment is signed. */
+    spend(amount, what) {
+        if (amount < 0n)
+            throw new ToolError(`refused: ${what} is negative`);
+        if (this.#spent + amount > this.cfg.maxSpendSession) {
+            throw new ToolError(`refused: ${what} of ${amount} would take this session to ${this.#spent + amount}, above X207_MAX_SPEND_SESSION (${this.cfg.maxSpendSession}); ${this.remaining} left`);
+        }
+        this.#spent += amount;
+    }
+    /** Gives back what `spend` took when the commitment was not made after all. */
+    release(amount) {
+        if (amount < 0n)
+            return;
+        this.#spent = this.#spent >= amount ? this.#spent - amount : 0n;
+    }
+    /** Guard 4: only an ACTIVE member of the circle, and, when the operator wrote a list, only a member of that list. Never the agent itself. */
+    async counterparty(account) {
+        if (account === this.cfg.account)
+            throw new ToolError("refused: the agent cannot deal with itself");
+        const list = this.cfg.allowedCounterparties;
+        if (list.length > 0 && !list.includes(account))
+            throw new ToolError(`refused: ${account} is not in X207_ALLOWED_COUNTERPARTIES`);
+        const member = (await this.view("member", { account_id: account }));
+        if (member === null || member.status !== "active")
+            throw new ToolError(`refused: ${account} is not an active member of the circle`);
+    }
+    /** Guard 3: tools that move USDT or NEAR out of the agent into the circle stay off unless the operator turns them on. */
+    outflows(tool) {
+        if (!this.cfg.allowOutflows)
+            throw new ToolError(`refused: ${tool} moves funds out of the agent account; set X207_ALLOW_OUTFLOWS=1 to allow it`);
+    }
+    /** Guard 5: what the NEAR key may do. A function-call key cannot attach a deposit, so no tool that sends one can run with it. */
+    nearKey(kind, tool) {
+        if (this.cfg.nearKey === null)
+            throw new ToolError(`refused: ${tool} sends a transaction and needs X207_AGENT_NEAR_KEY`);
+        if (kind === "function-call")
+            throw new ToolError(`refused: the NEAR key is a function-call key, which cannot attach the deposit that ${tool} needs; no transaction was sent`);
+        if (kind === "full-access" && !this.cfg.allowFullAccessKey)
+            throw new ToolError(`refused: the NEAR key has full access to the account; set X207_ALLOW_FULL_ACCESS_KEY=1 to use it for ${tool}`);
+        if (kind !== "full-access")
+            throw new ToolError(`refused: the NEAR key is not a key of ${this.cfg.account}; no transaction was sent`);
+    }
+}
+//# sourceMappingURL=guards.js.map

package/dist/http.d.ts

@@ -0,0 +1,19 @@
+import { type Server } from "node:http";
+import type { McpConfig } from "./config.js";
+export interface HttpOptions {
+    host?: string;
+    port?: number;
+    /** Largest request body in bytes; default 1 MiB. */
+    maxBodyBytes?: number;
+    /** Values of the `Host` header that are served, e.g. `["mcp.example.org"]`. On a loopback address the default is `127.0.0.1`, `localhost` and `[::1]` (with the port). */
+    allowedHosts?: readonly string[];
+}
+/** Starts the server; resolves when it listens. `GET /healthz` answers 200, `POST /mcp` is the MCP endpoint, everything else is refused. */
+/** A loopback bind: `localhost`, any 127.x.x.x, `::1` or the mapped form of a 127.x address (cross review UM-112, F7: `127.0.0.2` is loopback too, and must not serve every Host). */
+export declare function isLoopbackBind(bind: string): boolean;
+export declare function startHttpServer(config: McpConfig, options?: HttpOptions): Promise<{
+    server: Server;
+    url: string;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,94 @@
+// Streamable HTTP transport (SD-081): stateless, one server per request, read tools only. Binds to 127.0.0.1 unless told otherwise; the server has no key and signs nothing, so what it
+// shows is what the contract and the read API already show to anybody.
+import { isIP } from "node:net";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { ipv6Bytes } from "./net-guard.js";
+import { createX207McpServer } from "./server.js";
+const json = (res, status, body, extra = {}) => {
+    res.writeHead(status, { "content-type": "application/json", ...extra });
+    res.end(JSON.stringify(body));
+};
+async function readBody(req, max) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > max)
+            throw Object.assign(new Error("body too large"), { status: 413 });
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw Object.assign(new Error("body is not JSON"), { status: 400 });
+    }
+}
+/** Starts the server; resolves when it listens. `GET /healthz` answers 200, `POST /mcp` is the MCP endpoint, everything else is refused. */
+/** A loopback bind: `localhost`, any 127.x.x.x, `::1` or the mapped form of a 127.x address (cross review UM-112, F7: `127.0.0.2` is loopback too, and must not serve every Host). */
+export function isLoopbackBind(bind) {
+    const host = bind.replace(/^\[|\]$/g, "").toLowerCase();
+    if (host === "localhost" || host === "::1")
+        return true;
+    if (isIP(host) === 4)
+        return host.startsWith("127.");
+    const bytes = ipv6Bytes(host);
+    return bytes !== null && bytes.slice(0, 10).every((x) => x === 0) && bytes[10] === 0xff && bytes[11] === 0xff && bytes[12] === 127;
+}
+export function startHttpServer(config, options = {}) {
+    const maxBody = options.maxBodyBytes ?? 1_048_576;
+    const bind = options.host ?? "127.0.0.1";
+    const loopback = isLoopbackBind(bind);
+    // DNS rebinding (security review batch 8, SD-081 fix): a web page can make a browser send a request to 127.0.0.1 under the name of an attacker's site. The browser puts that name in `Host`,
+    // so on a loopback address only the names of the loopback are served. A server that the operator binds to another address serves what `allowedHosts` says, or every host when there is no list.
+    const hostAllowed = (header, port) => {
+        if (header === undefined)
+            return !loopback && options.allowedHosts === undefined;
+        const name = header.toLowerCase();
+        if (options.allowedHosts !== undefined)
+            return options.allowedHosts.map((h) => h.toLowerCase()).includes(name);
+        if (!loopback)
+            return true;
+        return [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`, "127.0.0.1", "localhost", "[::1]", bind.toLowerCase(), `${bind.toLowerCase()}:${port}`, `[${bind.toLowerCase()}]:${port}`].includes(name);
+    };
+    const server = createServer(async (req, res) => {
+        try {
+            const port = (req.socket.localPort ?? options.port ?? 0);
+            if (!hostAllowed(req.headers.host, port))
+                return json(res, 403, { error: "host_not_allowed", message: "the Host header is not one that this server serves" });
+            const path = (req.url ?? "").split("?")[0];
+            if (path === "/healthz" && req.method === "GET")
+                return json(res, 200, { ok: true, name: "x207-mcp" });
+            if (path !== "/mcp")
+                return json(res, 404, { error: "not_found" });
+            if (req.method !== "POST")
+                return json(res, 405, { jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed: this server is stateless, use POST /mcp" }, id: null }, { allow: "POST" });
+            const body = await readBody(req, maxBody);
+            const mcp = createX207McpServer(config, "http");
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+            res.on("close", () => {
+                void transport.close();
+                void mcp.close();
+            });
+            await mcp.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (error) {
+            const status = error.status ?? 500;
+            if (!res.headersSent)
+                json(res, status, { jsonrpc: "2.0", error: { code: status === 500 ? -32603 : -32600, message: status === 500 ? "internal error" : error.message }, id: null });
+            else
+                res.end();
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 3207, options.host ?? "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : options.port;
+            resolve({ server, url: `http://${options.host ?? "127.0.0.1"}:${port}/mcp`, close: () => new Promise((r) => (server.closeAllConnections?.(), server.close(() => r()))) });
+        });
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./config.js";
+export * from "./backend.js";
+export * from "./tools.js";
+export * from "./server.js";
+export * from "./http.js";
+export * from "./write-config.js";
+export * from "./guards.js";
+export * from "./write-tools.js";
+export * from "./net-guard.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+// @x207/mcp: the MCP server of x207 (SD-081, read tools).
+export * from "./config.js";
+export * from "./backend.js";
+export * from "./tools.js";
+export * from "./server.js";
+export * from "./http.js";
+export * from "./write-config.js";
+export * from "./guards.js";
+export * from "./write-tools.js";
+export * from "./net-guard.js";
+//# sourceMappingURL=index.js.map

package/dist/net-guard.d.ts

@@ -0,0 +1,20 @@
+export type HostResolver = (host: string) => Promise<string[]>;
+export declare const defaultResolver: HostResolver;
+/** The 16 bytes of a literal IPv6 address (`::` forms, an IPv4 tail); `null` when it is not one. */
+export declare function ipv6Bytes(address: string): number[] | null;
+/** `true` when `address` (a literal IPv4 or IPv6) is not a public unicast address. */
+export declare function isPrivateAddress(address: string): boolean;
+/** Throws a message for the model when the URL points at a place that a paid request should not reach. */
+export declare function assertPublicUrl(url: URL, resolve?: HostResolver): Promise<void>;
+/** Reads a response body up to `limit` bytes and stops there: a seller that streams for ever cannot fill the memory of the server. */
+export declare function readCapped(response: Response, limit: number): Promise<{
+    text: string;
+    cut: boolean;
+}>;
+/**
+ * M-2 (cross review UM-112): DNS rebinding. `assertPublicUrl` resolves the name to check it, and `fetch` resolves it again to connect, so a name that answers a public address to the first
+ * question and 169.254.169.254 to the second walks around the check. This fetch connects through its own `lookup`: the name is resolved ONCE, every address is checked, and the connection
+ * goes to one of the addresses that were checked (the TLS name stays the host of the URL). No redirect is followed (the caller sees the 3xx), and the body is read as a stream.
+ */
+export declare function createPinnedFetch(resolve?: HostResolver): typeof fetch;
+//# sourceMappingURL=net-guard.d.ts.map

package/dist/net-guard.js

@@ -0,0 +1,182 @@
+// The network guard of x207_pay_request (security review batch 8, SD-082 fix). The URL comes from a model, so it can come from a prompt injection: without a guard the tool would fetch
+// http://169.254.169.254/ (the credentials of a cloud machine), http://127.0.0.1:<port>/ (a service on this machine) or an address of the office network, and hand the answer back to the model.
+// A URL is refused when its host is, or resolves to, a loopback, private, link-local, carrier-grade NAT, multicast or unspecified address, or when it is a name like `localhost` or `*.internal`.
+// X207_ALLOW_PRIVATE_URLS=1 turns the guard off, for a seller on this machine (the demos and the sandbox tests do that).
+import { lookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import { Readable } from "node:stream";
+export const defaultResolver = async (host) => (await lookup(host, { all: true, verbatim: true })).map((a) => a.address);
+const NAMES = /(^|\.)(localhost|local|internal|localdomain|home\.arpa)$/i;
+/** The 16 bytes of a literal IPv6 address (`::` forms, an IPv4 tail); `null` when it is not one. */
+export function ipv6Bytes(address) {
+    let text = address.toLowerCase();
+    const tail = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(text);
+    if (tail) {
+        const q = tail.slice(1).map(Number);
+        if (q.some((x) => x > 255))
+            return null;
+        text = text.slice(0, tail.index) + ((q[0] << 8) | q[1]).toString(16) + ":" + ((q[2] << 8) | q[3]).toString(16);
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const groups = (part) => (part === "" ? [] : part.split(":"));
+    const head = groups(halves[0]);
+    const rest = halves.length === 2 ? groups(halves[1]) : [];
+    const missing = 8 - head.length - rest.length;
+    if (halves.length === 1 ? head.length !== 8 : missing < 1)
+        return null;
+    const all = [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...rest];
+    const out = [];
+    for (const g of all) {
+        if (!/^[0-9a-f]{1,4}$/.test(g))
+            return null;
+        const v = parseInt(g, 16);
+        out.push(v >> 8, v & 255);
+    }
+    return out.length === 16 ? out : null;
+}
+/** `true` when `address` (a literal IPv4 or IPv6) is not a public unicast address. */
+export function isPrivateAddress(address) {
+    const a = address.replace(/^\[|\]$/g, "").toLowerCase();
+    const family = isIP(a);
+    if (family === 4) {
+        const [p, q] = a.split(".").map(Number);
+        return p === 0 || p === 10 || p === 127 || (p === 100 && q >= 64 && q <= 127) || (p === 169 && q === 254) || (p === 172 && q >= 16 && q <= 31) || (p === 192 && q === 168) || (p === 192 && q === 0) || (p === 198 && (q === 18 || q === 19)) || p >= 224;
+    }
+    if (family === 6) {
+        const bytes = ipv6Bytes(a);
+        if (bytes === null)
+            return true;
+        const v4 = (i) => `${bytes[i]}.${bytes[i + 1]}.${bytes[i + 2]}.${bytes[i + 3]}`;
+        const zeros = (from, to) => bytes.slice(from, to).every((x) => x === 0);
+        // forms that CARRY an IPv4 address: the carried address decides (cross review UM-112, F1; `new URL` writes them in hex, `::ffff:7f00:1`, `64:ff9b::a9fe:a9fe`)
+        if (zeros(0, 10) && bytes[10] === 0xff && bytes[11] === 0xff)
+            return isPrivateAddress(v4(12)); // ::ffff:0:0/96 IPv4-mapped
+        if (zeros(0, 12))
+            return bytes[12] === 0 && bytes[13] === 0 && bytes[14] === 0 && bytes[15] <= 1 ? true : isPrivateAddress(v4(12)); // ::/96 IPv4-compatible, :: and ::1
+        if (bytes[0] === 0x00 && bytes[1] === 0x64 && bytes[2] === 0xff && bytes[3] === 0x9b) { // 64:ff9b::/96 NAT64, and 64:ff9b:1::/48 (local use, refused whole)
+            if (zeros(4, 12))
+                return isPrivateAddress(v4(12));
+            if (bytes[4] === 0 && bytes[5] === 1)
+                return true;
+        }
+        if (zeros(0, 8) && bytes[8] === 0xff && bytes[9] === 0xff && bytes[10] === 0 && bytes[11] === 0)
+            return isPrivateAddress(v4(12)); // ::ffff:0:0:0/96 IPv4-translated (SIIT)
+        if (bytes[0] === 0x20 && bytes[1] === 0x02)
+            return isPrivateAddress(v4(2)); // 2002::/16 6to4
+        if (bytes[0] === 0x20 && bytes[1] === 0x01 && bytes[2] === 0 && bytes[3] === 0)
+            return true; // 2001::/32 Teredo: the server and the client are inside the address
+        const b0 = bytes[0];
+        const b1 = bytes[1];
+        if ((b0 & 0xfe) === 0xfc)
+            return true; // fc00::/7 unique local
+        if (b0 === 0xfe && (b1 & 0xc0) === 0x80)
+            return true; // fe80::/10 link-local
+        if (b0 === 0xfe && (b1 & 0xc0) === 0xc0)
+            return true; // fec0::/10 site-local (deprecated)
+        if (bytes[0] === 0xff)
+            return true; // ff00::/8 multicast
+        if (bytes[0] === 0x20 && bytes[1] === 0x01 && bytes[2] === 0x0d && bytes[3] === 0xb8)
+            return true; // 2001:db8::/32 documentation
+        return false;
+    }
+    return true; // not an address at all
+}
+/** Throws a message for the model when the URL points at a place that a paid request should not reach. */
+export async function assertPublicUrl(url, resolve = defaultResolver) {
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase().replace(/\.+$/, ""); // `localhost.` is `localhost` (cross review UM-112, F6)
+    if (host === "")
+        throw new Error("the URL has no host");
+    if (NAMES.test(host))
+        throw new Error(`refused: ${host} is a name of this machine or of a private network; set X207_ALLOW_PRIVATE_URLS=1 only for a seller you run yourself`);
+    if (isIP(host) !== 0) {
+        if (isPrivateAddress(host))
+            throw new Error(`refused: ${host} is a private, loopback or link-local address; set X207_ALLOW_PRIVATE_URLS=1 only for a seller you run yourself`);
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await resolve(host);
+    }
+    catch (error) {
+        throw new Error(`refused: ${host} could not be resolved (${error.message})`);
+    }
+    if (addresses.length === 0)
+        throw new Error(`refused: ${host} has no address`);
+    for (const address of addresses) {
+        if (isPrivateAddress(address))
+            throw new Error(`refused: ${host} resolves to ${address}, a private, loopback or link-local address; set X207_ALLOW_PRIVATE_URLS=1 only for a seller you run yourself`);
+    }
+}
+/** Reads a response body up to `limit` bytes and stops there: a seller that streams for ever cannot fill the memory of the server. */
+export async function readCapped(response, limit) {
+    if (response.body === null)
+        return { text: "", cut: false };
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    let cut = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (size + value.length > limit) {
+            chunks.push(value.subarray(0, limit - size));
+            size = limit;
+            cut = true;
+            await reader.cancel().catch(() => undefined);
+            break;
+        }
+        chunks.push(value);
+        size += value.length;
+    }
+    return { text: Buffer.concat(chunks).toString("utf8"), cut };
+}
+/**
+ * M-2 (cross review UM-112): DNS rebinding. `assertPublicUrl` resolves the name to check it, and `fetch` resolves it again to connect, so a name that answers a public address to the first
+ * question and 169.254.169.254 to the second walks around the check. This fetch connects through its own `lookup`: the name is resolved ONCE, every address is checked, and the connection
+ * goes to one of the addresses that were checked (the TLS name stays the host of the URL). No redirect is followed (the caller sees the 3xx), and the body is read as a stream.
+ */
+export function createPinnedFetch(resolve = defaultResolver) {
+    const lookupChecked = (hostname, options, callback) => {
+        resolve(hostname.replace(/\.+$/, "")).then((addresses) => {
+            const bad = addresses.find((a) => isPrivateAddress(a));
+            if (addresses.length === 0 || bad !== undefined)
+                return callback(new Error(`refused: ${hostname} resolves to ${bad ?? "no address"}, a private, loopback or link-local address`));
+            const list = addresses.map((address) => ({ address, family: isIP(address) }));
+            return options.all === true ? callback(null, list) : callback(null, list[0].address, list[0].family);
+        }, (error) => callback(error));
+    };
+    return (async (input, init) => {
+        const req = input instanceof Request ? input : new Request(input, init);
+        const url = new URL(req.url);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error("only http and https");
+        if (init?.redirect !== undefined && init.redirect !== "manual" && req.redirect !== "manual")
+            throw new Error("a redirect is not followed by this fetch");
+        const body = req.body === null ? null : Buffer.from(await req.arrayBuffer());
+        const headers = {};
+        req.headers.forEach((value, name) => {
+            headers[name] = value;
+        });
+        if (body !== null)
+            headers["content-length"] = String(body.length);
+        return new Promise((resolveResponse, reject) => {
+            const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+            const out = send(url, { method: req.method, headers, lookup: lookupChecked, signal: req.signal }, (res) => {
+                const responseHeaders = new Headers();
+                for (const [name, value] of Object.entries(res.headers))
+                    for (const v of Array.isArray(value) ? value : value === undefined ? [] : [value])
+                        responseHeaders.append(name, v);
+                const status = res.statusCode ?? 502;
+                resolveResponse(new Response(status === 204 || status === 304 ? null : Readable.toWeb(res), { status, statusText: res.statusMessage ?? "", headers: responseHeaders }));
+            });
+            out.on("error", reject);
+            out.end(body ?? undefined);
+        });
+    });
+}
+//# sourceMappingURL=net-guard.js.map

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpConfig } from "./config.js";
+import { type ToolContext, type ToolDef } from "./tools.js";
+import { type WriteConfig } from "./write-config.js";
+import type { ContractCall } from "@x207/core";
+export type Transport = "stdio" | "http";
+/** Longest text of one tool result. A longer answer is cut and says so, so one call cannot fill the context of a model. */
+export declare const MAX_RESULT_CHARS = 100000;
+/** The tools that run on a transport: HTTP only ever gets the read tools. */
+export declare const toolsFor: (transport: Transport) => ToolDef[];
+export declare function contextFrom(config: McpConfig): ToolContext;
+export interface ServerOptions {
+    version?: string;
+    /** The write configuration (SD-082). Honoured on stdio only: on HTTP it is ignored and the server stays read-only. */
+    write?: WriteConfig | null;
+    /** Replaces the NEAR sender of the write tools (tests). */
+    send?: (call: ContractCall) => Promise<unknown>;
+    now?: () => number;
+    /** Replaces the DNS lookup of the SSRF guard (tests). */
+    resolve?: (host: string) => Promise<string[]>;
+}
+/** One MCP server with the tools of `transport`. The read tools read views of the contract and the read API and send nothing. The write tools exist only on stdio with a write configuration. */
+export declare function createX207McpServer(config: McpConfig, transport: Transport, options?: ServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,47 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createCircleViewFn } from "@x207/core";
+import { createBackendGet, createBackendPost } from "./backend.js";
+import { READ_TOOLS, ToolError } from "./tools.js";
+import { availableWriteTools, createWriteRuntime } from "./write-tools.js";
+import { scrub } from "./write-config.js";
+/** Longest text of one tool result. A longer answer is cut and says so, so one call cannot fill the context of a model. */
+export const MAX_RESULT_CHARS = 100_000;
+const text = (value) => {
+    const out = JSON.stringify(value, null, 2) ?? "null";
+    return out.length <= MAX_RESULT_CHARS ? out : `${out.slice(0, MAX_RESULT_CHARS)}\n… cut at ${MAX_RESULT_CHARS} characters; ask for fewer items or use the cursor`;
+};
+/** The tools that run on a transport: HTTP only ever gets the read tools. */
+export const toolsFor = (transport) => READ_TOOLS.filter((t) => transport === "stdio" || t.access === "read");
+export function contextFrom(config) {
+    const view = createCircleViewFn({ circleContract: config.circleContract, rpcUrls: config.rpcUrls, timeoutMs: config.timeoutMs, ...(config.fetch ? { fetch: config.fetch } : {}) });
+    const backend = config.backendUrl === null ? null : createBackendGet({ baseUrl: config.backendUrl, circleId: config.circleId, timeoutMs: config.timeoutMs, ...(config.fetch ? { fetch: config.fetch } : {}) });
+    return { view, backend, circleContract: config.circleContract, circleId: config.circleId };
+}
+/** One MCP server with the tools of `transport`. The read tools read views of the contract and the read API and send nothing. The write tools exist only on stdio with a write configuration. */
+export function createX207McpServer(config, transport, options = {}) {
+    const server = new McpServer({ name: "x207", version: options.version ?? "0.0.1" });
+    const ctx = contextFrom(config);
+    const writeCfg = transport === "stdio" ? (options.write ?? null) : null;
+    let tools = toolsFor(transport);
+    if (writeCfg !== null) {
+        const post = config.backendUrl === null ? null : createBackendPost({ baseUrl: config.backendUrl, circleId: config.circleId, timeoutMs: config.timeoutMs, ...(config.fetch ? { fetch: config.fetch } : {}) });
+        ctx.write = createWriteRuntime(config, writeCfg, ctx.view, { post, ...(options.send ? { send: options.send } : {}), ...(options.now ? { now: options.now } : {}), ...(options.resolve ? { resolve: options.resolve } : {}) });
+        tools = [...tools, ...availableWriteTools(ctx.write, ctx.backend !== null)];
+    }
+    for (const tool of tools) {
+        // `as never` on inputSchema: this package builds its schemas with zod 4, and which copy of zod the MCP SDK resolves depends on the install (the sdk repo alone hoists zod 4, the umbrella
+        // workspace hoists zod 3.25 to the root and the SDK resolves that one), so the two declarations of the schema type differ for tsc while the SDK reads either at run time (SD-084).
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: { readOnlyHint: tool.access === "read", destructiveHint: tool.access === "write", idempotentHint: tool.access === "read", openWorldHint: true } }, (async (args) => {
+            try {
+                return { content: [{ type: "text", text: scrub(text(await tool.handler(args, ctx)), writeCfg) }] };
+            }
+            catch (error) {
+                // a tool error is an answer for the model, not a crash of the server; no key can be in it
+                const message = error instanceof ToolError ? error.message : `${tool.name} failed: ${error.message}`;
+                return { isError: true, content: [{ type: "text", text: scrub(message, writeCfg) }] };
+            }
+        }));
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools.d.ts

@@ -0,0 +1,27 @@
+import type { CircleViewFn } from "@x207/core";
+import { z } from "zod";
+import { type BackendGet } from "./backend.js";
+import type { WriteRuntime } from "./write-tools.js";
+export interface ToolContext {
+    view: CircleViewFn;
+    /** `null` when no read API is configured. */
+    backend: BackendGet | null;
+    circleContract: string;
+    circleId: string;
+    /** Present only on stdio with X207_MCP_WRITE=1 (SD-082). */
+    write?: WriteRuntime;
+}
+export interface ToolDef<Shape extends z.ZodRawShape = z.ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    /** `read` tools run on every transport; a `write` tool would run on stdio only (SD-082). */
+    access: "read" | "write";
+    inputSchema: Shape;
+    handler: (args: z.infer<z.ZodObject<Shape>>, ctx: ToolContext) => Promise<unknown>;
+}
+/** What a tool says when it cannot do its job: shown to the model as the text of an error result. */
+export declare class ToolError extends Error {
+}
+export declare const READ_TOOLS: ToolDef[];
+//# sourceMappingURL=tools.d.ts.map