@x207/mcp 0.0.0-stage → 0.0.1

package/dist/tools.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { BackendError, seg } from "./backend.js";
+/** What a tool says when it cannot do its job: shown to the model as the text of an error result. */
+export class ToolError extends Error {
+}
+const ACCOUNT = z.string().regex(/^[a-z0-9][a-z0-9._-]{1,63}$/, "a NEAR account id, e.g. alice.x207-v013.testnet");
+const HASH = z.string().regex(/^[A-Za-z0-9_-]{8,128}$/, "the hash of the object, as the read API gives it");
+const LIMIT = (max, dflt) => z.number().int().min(1).max(max).default(dflt).describe(`How many items, 1 to ${max} (default ${dflt}).`);
+const EPOCH = z.number().int().min(0).max(4_294_967_295);
+const needBackend = (ctx, what) => {
+    if (ctx.backend === null)
+        throw new ToolError(`${what} needs the x207 read API: set X207_BACKEND_URL (the server answers from the contract only without it).`);
+    return ctx.backend;
+};
+/** Runs the pieces of one answer side by side: the first failure of a piece that is not optional rejects, an optional one becomes a warning. */
+async function gather(required, optional = {}) {
+    const keys = [...Object.keys(required), ...Object.keys(optional)];
+    const settled = await Promise.allSettled([...Object.values(required), ...Object.values(optional)].map((f) => f()));
+    const data = {};
+    const warnings = [];
+    settled.forEach((r, i) => {
+        const key = keys[i];
+        if (r.status === "fulfilled")
+            data[key] = r.value;
+        else if (key in required)
+            throw r.reason;
+        else
+            warnings.push(`${key}: ${r.reason.message}`);
+    });
+    return { data, warnings };
+}
+export const READ_TOOLS = [
+    {
+        name: "x207_circle_overview",
+        title: "x207 circle overview",
+        description: "Overview of one x207 mutual-credit circle: its record and rules from the contract (get_circle, get_params) and its members (read API GET /members, or the contract view list_members when no read API is configured). Credit amounts are strings in the smallest unit (6 decimals).",
+        access: "read",
+        inputSchema: { members_limit: LIMIT(200, 20), members_status: z.string().min(1).max(32).optional().describe("Only members with this status, e.g. active (read API only).") },
+        handler: async (args, ctx) => {
+            const { data, warnings } = await gather({ circle: () => ctx.view("get_circle", {}), params: () => ctx.view("get_params", {}) }, {
+                members: () => ctx.backend !== null
+                    ? ctx.backend("/members", { limit: args.members_limit, status: args.members_status })
+                    : ctx.view("list_members", { from_index: 0, limit: args.members_limit }),
+            });
+            return { contract: ctx.circleContract, circleId: ctx.circleId, ...data, membersSource: ctx.backend !== null ? "read API" : "contract view list_members", warnings };
+        },
+    },
+    {
+        name: "x207_member_inspect",
+        title: "Inspect a circle member",
+        description: "One member of the circle: status, stake, position and credit limit. Uses the read API (GET /members/{account} and /members/{account}/limits), or the contract views member and limit when no read API is configured.",
+        access: "read",
+        inputSchema: { account: ACCOUNT },
+        handler: async (args, ctx) => {
+            const account = args.account;
+            if (ctx.backend !== null) {
+                const b = ctx.backend;
+                const { data, warnings } = await gather({ member: () => b(`/members/${seg(account)}`) }, { limits: () => b(`/members/${seg(account)}/limits`) });
+                return { account, ...data, source: "read API", warnings };
+            }
+            const { data, warnings } = await gather({ member: () => ctx.view("member", { account_id: account }) }, { limit: () => ctx.view("limit", { account_id: account }) });
+            if (data.member === null)
+                throw new ToolError(`${account} is not a member of ${ctx.circleContract}`);
+            return { account, ...data, source: "contract views member and limit", warnings };
+        },
+    },
+    {
+        name: "x207_epoch_report",
+        title: "Epoch report (report 207)",
+        description: "The state and the result of one clearing epoch: the contract record (get_epoch) and, from the read API, the epoch summary (GET /epochs/{n}), its metrics (cleared ratio, GET /epochs/{n}/metrics) and its settlements (GET /epochs/{n}/settlements). Without epoch, the current epoch.",
+        access: "read",
+        inputSchema: { epoch: EPOCH.optional().describe("Epoch number; the current epoch when left out."), settlements_limit: LIMIT(200, 20) },
+        handler: async (args, ctx) => {
+            const record = (await ctx.view("get_epoch", args.epoch === undefined ? {} : { epoch: args.epoch }));
+            if (record === null || typeof record.epoch !== "number")
+                throw new ToolError(`epoch ${args.epoch ?? "(current)"} is not on the contract`);
+            const n = record.epoch;
+            if (ctx.backend === null) {
+                const { data, warnings } = await gather({}, { positions: () => ctx.view("list_positions", { epoch: n, from_index: 0, limit: args.settlements_limit }) });
+                return { epoch: n, contract: record, ...data, source: "contract views get_epoch and list_positions", warnings };
+            }
+            const b = ctx.backend;
+            const { data, warnings } = await gather({}, { summary: () => b(`/epochs/${seg(n)}`), metrics: () => b(`/epochs/${seg(n)}/metrics`), settlements: () => b(`/epochs/${seg(n)}/settlements`, { limit: args.settlements_limit }) });
+            return { epoch: n, contract: record, ...data, source: "contract view get_epoch and read API", warnings };
+        },
+    },
+    {
+        name: "x207_simulate_clearing",
+        title: "Simulate a clearing proposal",
+        description: "Asks the contract (view simulate_clearing) whether a proposed clearing for an epoch is valid and what it would clear. Each edge nets a debt: debtor owes creditor, `cleared` is the amount to cancel (decimal string, smallest unit). Changes nothing.",
+        access: "read",
+        inputSchema: {
+            epoch: EPOCH,
+            edges: z.array(z.object({ debtor: ACCOUNT, creditor: ACCOUNT, cleared: z.string().regex(/^\d{1,38}$/, "a decimal integer string") })).min(1).max(300),
+        },
+        handler: async (args, ctx) => ({ epoch: args.epoch, edgeCount: args.edges.length, result: await ctx.view("simulate_clearing", { epoch: args.epoch, edges: args.edges }) }),
+    },
+    {
+        name: "x207_search_listings",
+        title: "Search marketplace listings",
+        description: "Listings of the circle's marketplace (read API GET /listings): what an account offers and what it wants. Filters are optional; `status` defaults to open. Use `cursor` from `nextCursor` for the next page.",
+        access: "read",
+        inputSchema: {
+            status: z.enum(["open", "expired", "cancelled", "filled", "all"]).optional().describe("Default open."),
+            account: ACCOUNT.optional().describe("Only listings of this account."),
+            offerType: z.string().min(3).max(129).optional().describe("Asset type offered, e.g. service:summary."),
+            wantType: z.string().min(3).max(129).optional(),
+            offerClass: z.enum(["A", "B", "C", "D", "X"]).optional(),
+            wantClass: z.enum(["A", "B", "C", "D", "X"]).optional(),
+            limit: LIMIT(200, 20),
+            cursor: z.string().min(1).max(512).optional(),
+        },
+        handler: async (args, ctx) => {
+            const b = needBackend(ctx, "x207_search_listings");
+            const { status, account, offerType, wantType, offerClass, wantClass, limit, cursor } = args;
+            return b("/listings", { status, account, offerType, wantType, offerClass, wantClass, limit, cursor });
+        },
+    },
+    {
+        name: "x207_order_status",
+        title: "Order status",
+        description: "A service order of the circle's marketplace: parties, budget, milestones and status (read API GET /orders/{hash}). Without a hash, lists orders; filter by `party` and `status`.",
+        access: "read",
+        inputSchema: {
+            hash: HASH.optional().describe("The order hash. Leave out to list orders."),
+            party: ACCOUNT.optional().describe("Only orders where this account is buyer or seller (listing only)."),
+            status: z.string().min(1).max(32).optional().describe("Only orders with this status (listing only)."),
+            limit: LIMIT(200, 20),
+            cursor: z.string().min(1).max(512).optional(),
+        },
+        handler: async (args, ctx) => {
+            const b = needBackend(ctx, "x207_order_status");
+            if (args.hash !== undefined) {
+                try {
+                    return await b(`/orders/${seg(args.hash)}`);
+                }
+                catch (error) {
+                    if (error instanceof BackendError && error.status === 404)
+                        throw new ToolError(`no order ${args.hash} in circle ${ctx.circleId}`);
+                    throw error;
+                }
+            }
+            return b("/orders", { party: args.party, status: args.status, limit: args.limit, cursor: args.cursor });
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map

package/dist/write-config.d.ts

@@ -0,0 +1,17 @@
+export interface WriteConfig {
+    account: string;
+    voucherKey: `ed25519:${string}` | null;
+    nearKey: `ed25519:${string}` | null;
+    maxSpendSession: bigint;
+    maxPricePerCall: bigint;
+    allowedCounterparties: readonly string[];
+    allowOutflows: boolean;
+    allowFullAccessKey: boolean;
+    /** `X207_ALLOW_PRIVATE_URLS=1`: x207_pay_request may fetch a URL on this machine or in a private network (a seller you run yourself). Default off (SSRF guard). */
+    allowPrivateUrls: boolean;
+}
+/** `null` when the write tools are off. A bad value stops the server with a message that never contains a key. */
+export declare function writeConfigFromEnv(env?: Record<string, string | undefined>): WriteConfig | null;
+/** Takes every secret of the write configuration out of a text, for the error of a tool and for the log. */
+export declare function scrub(text: string, cfg: WriteConfig | null): string;
+//# sourceMappingURL=write-config.d.ts.map

package/dist/write-config.js

@@ -0,0 +1,72 @@
+// Configuration and guards of the WRITE tools of the x207 MCP server (SD-082). Write tools exist only on stdio, only when X207_MCP_WRITE=1, and every key comes from the
+// environment: nothing here prints, logs or returns a key.
+//
+//   X207_MCP_WRITE=1                  turns the write tools on (default off: the server is read-only)
+//   X207_AGENT_ACCOUNT                the NEAR account of the agent (a member of the circle)
+//   X207_AGENT_VOUCHER_KEY            ed25519 voucher secret key of the agent: signs vouchers, listings, offers, acceptances and order notices. It is not a NEAR key.
+//   X207_AGENT_NEAR_KEY               ed25519 secret key of the NEAR account: signs the transactions of x207_join, x207_settle and x207_claim only
+//   X207_MAX_SPEND_SESSION            largest total (credit units, 6 decimals) the agent may commit in one session of the server; default 1000000 (1 credit)
+//   X207_MAX_PRICE_PER_CALL           largest amount of one payment, offer or milestone; 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             turns on the tools that move USDT or NEAR out of the agent account into the circle (x207_join, x207_settle); default off
+//   X207_ALLOW_PRIVATE_URLS=1         lets x207_pay_request fetch a URL on this machine or in a private network; default off, because the URL comes from a model (SSRF)
+//   X207_ALLOW_FULL_ACCESS_KEY=1      lets the NEAR key be a full-access key. Why this exists: a function-call key cannot attach a deposit, and join, stake, settle and claim all
+//                                     attach one (NEAR protocol rule), so the tools that send those transactions need a full-access key of the AGENT account; without this flag they are off.
+import { voucherPublicKey } from "@x207/core";
+import { ConfigError } from "./config.js";
+const ACCOUNT = /^[a-z0-9][a-z0-9._-]{1,63}$/;
+const KEY = /^ed25519:[1-9A-HJ-NP-Za-km-z]{40,100}$/;
+const AMOUNT = /^[1-9]\d{0,37}$/;
+const amount = (env, name, dflt) => {
+    const raw = env[name]?.trim() || dflt;
+    if (!AMOUNT.test(raw))
+        throw new ConfigError(`${name} must be a positive integer (credit units, 6 decimals), got ${JSON.stringify(raw.length > 40 ? "…" : raw)}`);
+    return BigInt(raw);
+};
+/** `null` when the write tools are off. A bad value stops the server with a message that never contains a key. */
+export function writeConfigFromEnv(env = process.env) {
+    if (env.X207_MCP_WRITE?.trim() !== "1")
+        return null;
+    const account = env.X207_AGENT_ACCOUNT?.trim() ?? "";
+    if (!ACCOUNT.test(account))
+        throw new ConfigError("X207_MCP_WRITE=1 needs X207_AGENT_ACCOUNT, the NEAR account of the agent");
+    const key = (name) => {
+        const v = env[name]?.trim();
+        if (v === undefined || v === "")
+            return null;
+        if (!KEY.test(v))
+            throw new ConfigError(`${name} is not an ed25519 secret key (ed25519:<base58>); the value is not shown`);
+        return v;
+    };
+    const voucherKey = key("X207_AGENT_VOUCHER_KEY");
+    if (voucherKey !== null) {
+        try {
+            voucherPublicKey(voucherKey);
+        }
+        catch {
+            throw new ConfigError("X207_AGENT_VOUCHER_KEY is not a usable ed25519 secret key; the value is not shown");
+        }
+    }
+    const allowed = (env.X207_ALLOWED_COUNTERPARTIES ?? "").split(",").map((s) => s.trim()).filter((s) => s !== "");
+    for (const a of allowed)
+        if (!ACCOUNT.test(a))
+            throw new ConfigError(`X207_ALLOWED_COUNTERPARTIES: ${JSON.stringify(a)} is not an account id`);
+    return {
+        account, voucherKey, nearKey: key("X207_AGENT_NEAR_KEY"),
+        maxSpendSession: amount(env, "X207_MAX_SPEND_SESSION", "1000000"),
+        maxPricePerCall: amount(env, "X207_MAX_PRICE_PER_CALL", "100000"),
+        allowedCounterparties: allowed,
+        allowOutflows: env.X207_ALLOW_OUTFLOWS?.trim() === "1",
+        allowFullAccessKey: env.X207_ALLOW_FULL_ACCESS_KEY?.trim() === "1",
+        allowPrivateUrls: env.X207_ALLOW_PRIVATE_URLS?.trim() === "1",
+    };
+}
+/** Takes every secret of the write configuration out of a text, for the error of a tool and for the log. */
+export function scrub(text, cfg) {
+    let out = text;
+    for (const secret of [cfg?.voucherKey, cfg?.nearKey])
+        if (secret)
+            out = out.split(secret).join("[key]");
+    return out.replace(/ed25519:[1-9A-HJ-NP-Za-km-z]{60,100}/g, "[key]");
+}
+//# sourceMappingURL=write-config.js.map

package/dist/write-tools.d.ts

@@ -0,0 +1,43 @@
+import { type CircleViewFn, type ContractCall } from "@x207/core";
+import type { BackendPost } from "./backend.js";
+import type { McpConfig } from "./config.js";
+import { Guards, type NearKeyKind } from "./guards.js";
+import { type HostResolver } from "./net-guard.js";
+import { type ToolDef } from "./tools.js";
+import type { WriteConfig } from "./write-config.js";
+export interface WriteRuntime {
+    cfg: WriteConfig;
+    guards: Guards;
+    /** Signs and sends a NEAR transaction with the NEAR key; waits for finality. */
+    send: (call: ContractCall) => Promise<unknown>;
+    /** What kind of access key the NEAR key is on the agent account. */
+    keyKind: () => Promise<NearKeyKind>;
+    /** The fetch that pays an x402 402 with an x207 voucher; created on first use and kept for the session, so the sequence numbers of the vouchers go on. */
+    payFetch: () => typeof fetch;
+    post: BackendPost | null;
+    now: () => number;
+    /** Resolves a host name for the SSRF guard of x207_pay_request. */
+    resolve: HostResolver;
+}
+/** The most that x207_pay_request reads of one answer. */
+export declare const MAX_PAID_BODY_BYTES = 1048576;
+/**
+ * After a commitment failed: the amount goes back to the budget only when it is certain that nothing was committed (a refusal of ours, a 4xx answer of the book, a contract that said no). A timeout, a 5xx
+ * or an unknown error may have committed it, so the amount stays counted and the model is told that the outcome is unknown (cross review UM-112, F3).
+ */
+export declare function keepIfUnknown(rt: {
+    guards: Guards;
+}, amount: bigint, error: unknown): unknown;
+export declare const WRITE_TOOLS: ToolDef[];
+/** Which write tools this runtime may even list: a tool whose key or switch is missing is not offered (the guard would refuse it anyway). */
+export declare function availableWriteTools(rt: WriteRuntime, hasBackend: boolean): ToolDef[];
+/** Builds the runtime of the write tools from the configuration. The NEAR sender and the payment client are created on first use. */
+export declare function createWriteRuntime(config: McpConfig, cfg: WriteConfig, view: CircleViewFn, deps?: {
+    post: BackendPost | null;
+    send?: (call: ContractCall) => Promise<unknown>;
+    now?: () => number;
+    resolve?: HostResolver;
+}): WriteRuntime;
+/** `view_access_key` of the NEAR key on the agent account. `unknown` when the key is not on the account or the RPC cannot say. */
+export declare function accessKeyKind(rpcUrls: readonly string[], account: string, publicKey: string, fetchFn: typeof fetch): Promise<NearKeyKind>;
+//# sourceMappingURL=write-tools.d.ts.map