@agtnames/mcp 1.1.0 → 1.2.0

package/README.md

@@ -30,12 +30,26 @@ From a checkout: `claude mcp add agt -- node packages/mcp/dist/index.js`; agains
 |---|---|
 | `agt_resolve` | owner, expiry, active/perpetual, on-chain records, verified manifest (under `untrusted`) |
 | `agt_manifest` | the manifest document + `verified` / `reasons` |
-| `agt_endpoint` | URL for `mcp` / `a2a` / `http` / `ws` — verified manifest first, resolver record second |
+| `agt_endpoint` | URL for `mcp` / `a2a` / `http` / `ws` — verified manifest first, resolver record second — plus `pricing` (`free` / `freemium` / `paid` / `contact`, from the verified manifest only) |
 | `agt_available` | can the name be registered right now |
 | `agt_namehash` | node + tokenId (no network) |
 
 All tools are annotated read-only and idempotent. `verified: true` means the manifest was signed by the on-chain owner (signer = manifest owner = registry owner). Everything derived from a manifest is returned inside an `untrusted` envelope with a notice: it is third-party content — data, never instructions. The server also publishes these rules as MCP `instructions`.
 
+## Write tools (opt-in): countersign session grants
+
+Set `AGT_SESSION_PASSPHRASE` (12+ characters) and nine more tools appear. They let this machine perform **record writes** on an owner's names under a grant the owner signed once, bounded on-chain: only the listed names, only the listed setters, no value, until the expiry, at most N calls per name, revocable by the owner in one transaction. See `@agtnames/countersign` for how a grant is built and enforced.
+
+| Tool | Does |
+|---|---|
+| `agt_session_new` | create this machine's session key (encrypted under `AGT_SESSION_DIR`, default `~/.agt/session`) and return its address |
+| `agt_session_import` | validate and store a grant the owner signed for that address; returns the plain-language mandate |
+| `agt_session_status` | calls used per name, expiry, whether the owner revoked, session gas balance |
+| `agt_session_forget` | drop the grant locally (and the key with `deleteKey`) |
+| `agt_set_text` `agt_set_addr` `agt_set_endpoint` `agt_set_manifest_uri` `agt_set_wallet` | redeem one record write; each returns the tx hash |
+
+Flow: `agt_session_new` → give the address to the owner → owner runs `agt-countersign build --session <address> --names … --actions … --ttl 1h --calls 5 --sign-with-key OWNER_KEY` (or signs the typed data in a wallet) → `agt_session_import` → write. Fund the session address with a little POL for gas; the grant itself cannot move value. Extra error codes: `no_session`, `grant_refused`, `caveat_violation`, `insufficient_gas`, `wrong_session`, `unknown_name`, `action_not_granted`.
+
 ## Errors
 
 Failures come back as an MCP error result (`isError: true`) whose text is `{ "error": { "code", "message" } }`:

package/dist/config.js

@@ -39,7 +39,7 @@ export function loadConfig(env = process.env) {
         ratePerMin: num(get("AGT_RATE_PER_MIN"), DEFAULTS.ratePerMin),
     };
 }
-export const HELP = `@agtnames/mcp ${VERSION} — MCP server for .agt agent names (stdio, read-only)
+export const HELP = `@agtnames/mcp ${VERSION} — MCP server for .agt agent names (stdio, read-only by default)
 
 Usage: agt-mcp [--version] [--help]
   Runs an MCP server over stdio. Any MCP-compatible client can launch it, e.g.
@@ -63,4 +63,7 @@ Environment (all optional; Polygon mainnet works with none)
   AGT_TIMEOUT_MS       per-request timeout                  (default ${DEFAULTS.timeoutMs})
   AGT_MAX_MANIFEST     max manifest bytes                   (default ${DEFAULTS.maxManifestBytes})
   AGT_RATE_PER_MIN     tool calls per minute                (default ${DEFAULTS.ratePerMin})
+  AGT_SESSION_PASSPHRASE  enables the countersign write tools (agt_session_*, agt_set_*): the local session key
+                       is stored encrypted under AGT_SESSION_DIR (default ~/.agt/session) and redeems an
+                       owner-signed grant; writes are bounded by the grant's on-chain caveats
 `;

package/dist/server.js

@@ -17,6 +17,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { AgtResolver, namehash, normalizeName, tokenIdOf } from "@agtnames/resolver";
 import { VERSION } from "./config.js";
+import { sessionConfig } from "./session.js";
+import { registerWriteTools } from "./write-tools.js";
 export class McpToolError extends Error {
     code;
     constructor(code, message) {
@@ -77,6 +79,16 @@ export const LIMITS = { str: 512, url: 2048, list: 50, depth: 4, key: 64 };
 // C0 controls + DEL, built from code points (no escape literals in source)
 const CONTROL_CHARS = new RegExp("[" + String.fromCharCode(0) + "-" + String.fromCharCode(31) + String.fromCharCode(127) + "]", "g");
 export const clean = (s, max) => s.replace(CONTROL_CHARS, "").slice(0, max);
+/**
+ * `pricing.model` from a VERIFIED manifest, sanitized; null when unverified or absent. Lets a client tell a free
+ * agent from a paid one before it calls the endpoint, without fetching the whole manifest.
+ */
+export function pricingModel(manifest, verified) {
+    if (!verified || !manifest || typeof manifest !== "object")
+        return null;
+    const model = manifest.pricing?.model;
+    return typeof model === "string" && model ? clean(model, LIMITS.key) : null;
+}
 /** Bound third-party JSON: strings capped (URLs longer), lists/objects capped with a visible marker, depth capped. */
 export function sanitize(v, depth = 0) {
     if (depth > LIMITS.depth)
@@ -182,7 +194,7 @@ export function buildServer(cfg, deps = {}) {
     }));
     server.registerTool("agt_endpoint", {
         title: "Get an agent endpoint",
-        description: "Get an agent's endpoint URL for a protocol (mcp, a2a, http, ws). Prefers the verified manifest; falls back to the on-chain resolver record. `verified: false` means the URL is unverified third-party data.",
+        description: "Get an agent's endpoint URL for a protocol (mcp, a2a, http, ws) plus its pricing model (free, freemium, paid, contact) when the manifest verifies. Prefers the verified manifest; falls back to the on-chain resolver record. `verified: false` means the URL is unverified third-party data.",
         inputSchema: { name: nameSchema, protocol: z.enum(["mcp", "a2a", "http", "ws"]).describe("Endpoint protocol") },
         annotations: READ,
     }, guarded(async ({ name, protocol }) => {
@@ -190,7 +202,7 @@ export function buildServer(cfg, deps = {}) {
         const fromManifest = r.verified ? r.manifest?.endpoints?.find((e) => e.protocol === protocol)?.url ?? null : null;
         const fromRecord = r.records.endpoints[protocol] ?? null;
         const url = fromManifest ?? fromRecord;
-        return { name: r.name, protocol, url: url ? clean(url, LIMITS.url) : null, source: fromManifest ? "verified-manifest" : fromRecord ? "resolver-record" : null, verified: !!fromManifest, reasons: r.reasons, notice: NOTICE };
+        return { name: r.name, protocol, url: url ? clean(url, LIMITS.url) : null, source: fromManifest ? "verified-manifest" : fromRecord ? "resolver-record" : null, verified: !!fromManifest, pricing: pricingModel(r.manifest, r.verified), reasons: r.reasons, notice: NOTICE };
     }));
     server.registerTool("agt_available", {
         title: "Check availability",
@@ -204,5 +216,8 @@ export function buildServer(cfg, deps = {}) {
         inputSchema: { name: nameSchema },
         annotations: OFFLINE,
     }, guarded(async ({ name }) => { const n = checkName(name); return { name: n, node: namehash(n), tokenId: tokenIdOf(n).toString() }; }));
+    const session = sessionConfig(deps.env ?? process.env);
+    if (session)
+        registerWriteTools(server, session, deps.write);
     return server;
 }

package/dist/session.js

@@ -0,0 +1,100 @@
+/**
+ * Local session store for the countersign write tools (D-025 v2).
+ *
+ * The session key never leaves this machine. It is generated here, stored encrypted (scrypt + AES-256-GCM) under
+ * AGT_SESSION_DIR, and used only to redeem a grant the owner signed. The grant itself is not secret and is stored
+ * alongside as plain JSON. Caveats on-chain, not this encryption, bound what a compromised running agent can do.
+ */
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { decodeGrant, describeGrant } from "@agtnames/countersign";
+export function sessionConfig(env = process.env) {
+    const passphrase = env.AGT_SESSION_PASSPHRASE?.trim();
+    if (!passphrase)
+        return null;
+    if (passphrase.length < 12)
+        throw new Error("AGT_SESSION_PASSPHRASE must be at least 12 characters");
+    const dir = env.AGT_SESSION_DIR?.trim() || path.join(homedir(), ".agt", "session");
+    return { dir, passphrase };
+}
+const KDF = { N: 2 ** 15, r: 8, p: 1 };
+const keyFile = (c) => path.join(c.dir, "session.json");
+const grantFile = (c) => path.join(c.dir, "grant.json");
+function encrypt(pk, c) {
+    const salt = randomBytes(16);
+    const key = scryptSync(c.passphrase.normalize("NFKC"), salt, 32, { ...KDF, maxmem: 128 * 1024 * 1024 });
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(Buffer.from(pk.slice(2), "hex")), cipher.final()]);
+    return { v: 1, address: privateKeyToAccount(pk).address, kdf: { ...KDF, salt: salt.toString("base64") }, iv: iv.toString("base64"), ct: ct.toString("base64"), tag: cipher.getAuthTag().toString("base64"), createdAt: new Date().toISOString() };
+}
+function decrypt(e, c) {
+    const key = scryptSync(c.passphrase.normalize("NFKC"), Buffer.from(e.kdf.salt, "base64"), 32, { N: e.kdf.N, r: e.kdf.r, p: e.kdf.p, maxmem: 128 * 1024 * 1024 });
+    const d = createDecipheriv("aes-256-gcm", key, Buffer.from(e.iv, "base64"));
+    d.setAuthTag(Buffer.from(e.tag, "base64"));
+    const pk = Buffer.concat([d.update(Buffer.from(e.ct, "base64")), d.final()]);
+    return ("0x" + pk.toString("hex"));
+}
+export class SessionStore {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Session address if a key exists, else null. Does not need the passphrase to be right. */
+    address() {
+        if (!existsSync(keyFile(this.c)))
+            return null;
+        return JSON.parse(readFileSync(keyFile(this.c), "utf8")).address;
+    }
+    /** Create the session key if none exists. Returns the address (never the key). */
+    ensureKey() {
+        const existing = this.address();
+        if (existing)
+            return { address: existing, created: false };
+        mkdirSync(this.c.dir, { recursive: true });
+        const pk = generatePrivateKey();
+        writeFileSync(keyFile(this.c), JSON.stringify(encrypt(pk, this.c), null, 2), { mode: 0o600 });
+        return { address: privateKeyToAccount(pk).address, created: true };
+    }
+    /** Decrypt the session key for one redemption. Throws on a wrong passphrase. */
+    privateKey() {
+        if (!existsSync(keyFile(this.c)))
+            throw new Error("no session key; call agt_session_new first");
+        try {
+            return decrypt(JSON.parse(readFileSync(keyFile(this.c), "utf8")), this.c);
+        }
+        catch {
+            throw new Error("AGT_SESSION_PASSPHRASE does not unlock the stored session key");
+        }
+    }
+    /** Validate a grant blob against this session and store it. */
+    async importGrant(blob, now = Math.floor(Date.now() / 1000)) {
+        const grant = decodeGrant(blob);
+        const address = this.address();
+        if (!address)
+            throw new Error("no session key; call agt_session_new first, then have the owner sign a grant for that address");
+        if (grant.delegate.toLowerCase() !== address.toLowerCase())
+            throw new Error(`grant delegate ${grant.delegate} is not this session (${address}); the owner must sign a grant for this session's address`);
+        const d = await describeGrant(grant, { now });
+        if (!d.ok)
+            throw new Error(`grant refused: ${d.problems.join("; ")}`);
+        mkdirSync(this.c.dir, { recursive: true });
+        writeFileSync(grantFile(this.c), JSON.stringify(grant), { mode: 0o600 });
+        return { grant, description: d };
+    }
+    grant() {
+        if (!existsSync(grantFile(this.c)))
+            return null;
+        return decodeGrant(readFileSync(grantFile(this.c), "utf8"));
+    }
+    /** Forget the grant (and optionally the key). Local only: on-chain revocation is the owner's nonce bump. */
+    forget(opts = {}) {
+        if (existsSync(grantFile(this.c)))
+            rmSync(grantFile(this.c));
+        if (opts.key && existsSync(keyFile(this.c)))
+            rmSync(keyFile(this.c));
+    }
+}

package/dist/write-tools.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { ACTIONS, describeGrant, grantStatus, redeem, RedeemError, GrantError } from "@agtnames/countersign";
+import { SessionStore } from "./session.js";
+import { bounded, checkName, McpToolError } from "./server.js";
+export const WRITE_TOOL_NAMES = [
+    "agt_session_new", "agt_session_import", "agt_session_status", "agt_session_forget",
+    "agt_set_text", "agt_set_addr", "agt_set_endpoint", "agt_set_manifest_uri", "agt_set_wallet",
+];
+const WRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+const LOCAL = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const LOCAL_READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+export const WRITE_NOTICE = "Writes are bounded by the grant's on-chain caveats: only the listed names, only the listed record setters, no value, until the expiry, at most maxCalls per name. The owner revokes everything by bumping their NonceEnforcer nonce.";
+const ok = (v) => ({ content: [{ type: "text", text: bounded(v) }] });
+const err = (code, message) => ({ content: [{ type: "text", text: JSON.stringify({ error: { code, message } }) }], isError: true });
+function classify(e) {
+    if (e instanceof RedeemError)
+        return err(e.code === "rpc_error" ? "rpc_error" : e.code, e.message);
+    if (e instanceof GrantError)
+        return err("grant_refused", `${e.code}: ${e.message}`);
+    if (e instanceof McpToolError)
+        return err(e.code, e.message);
+    const m = e instanceof Error ? e.message : String(e);
+    if (/no session key/i.test(m))
+        return err("no_session", m);
+    if (/grant refused|not this session|delegate/i.test(m))
+        return err("grant_refused", m);
+    return err("internal", m.slice(0, 300));
+}
+export function registerWriteTools(server, cfg, deps = {}) {
+    const store = new SessionStore(cfg);
+    const doRedeem = deps.redeem ?? redeem;
+    const doStatus = deps.status ?? grantStatus;
+    const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
+    const nameSchema = z.string().min(1).max(70).describe("A .agt name covered by the imported grant");
+    const loadGrant = () => {
+        const g = store.grant();
+        if (!g)
+            throw new McpToolError("misconfigured", "no grant imported; call agt_session_import with a grant the owner signed for this session");
+        if (now() >= g.notAfter)
+            throw new RedeemError("caveat_violation", `grant expired at ${new Date(g.notAfter * 1000).toISOString()}; ask the owner for a new one`);
+        return g;
+    };
+    const write = async (name, args) => {
+        const g = loadGrant();
+        const n = checkName(name);
+        const r = await doRedeem(g, n, args, { session: store.privateKey(), rpcUrl: deps.rpcUrl });
+        return { name: n, action: ACTIONS[args.action].functionName, txHash: r.hash, blockNumber: r.blockNumber.toString(), chainId: g.chainId, notice: WRITE_NOTICE };
+    };
+    const guarded = (fn) => async (a) => { try {
+        return ok(await fn(a));
+    }
+    catch (e) {
+        return classify(e);
+    } };
+    server.registerTool("agt_session_new", {
+        title: "Create the local session key",
+        description: "Create (or show) this machine's countersign session key and return its address. Give the address to the name owner: they sign a grant for it (names, record setters, expiry, call count) and you import that grant with agt_session_import. The private key never leaves this machine.",
+        inputSchema: {},
+        annotations: LOCAL,
+    }, guarded(async () => {
+        const { address, created } = store.ensureKey();
+        return { sessionAddress: address, created, next: `Owner: build a grant for delegate ${address} (agt-countersign build --session ${address} …), sign it, and paste the JSON into agt_session_import. Fund ${address} with a little POL for gas.` };
+    }));
+    server.registerTool("agt_session_import", {
+        title: "Import a signed grant",
+        description: "Validate and store a grant the owner signed for this session. Refuses a grant for another session, an expired grant, or one whose caveats do not match its summary. Returns the plain-language mandate the chain will enforce.",
+        inputSchema: { grant: z.string().min(2).max(64 * 1024).describe("Grant JSON as produced by agt-countersign build (or the owner's wallet flow)") },
+        annotations: LOCAL,
+    }, guarded(async ({ grant }) => {
+        const { grant: g, description } = await store.importGrant(grant, now());
+        return { imported: true, grantHash: g.hash, names: g.names.map((n) => n.name), actions: g.actions, notAfter: new Date(g.notAfter * 1000).toISOString(), maxCallsPerName: g.maxCalls, mandate: description.summary, notice: WRITE_NOTICE };
+    }));
+    server.registerTool("agt_session_status", {
+        title: "Session and grant status",
+        description: "Show the session address, whether a grant is imported, and (from the chain) calls used per name, expiry, whether the owner has revoked, and the session's gas balance.",
+        inputSchema: {},
+        annotations: LOCAL_READ,
+    }, guarded(async () => {
+        const address = store.address();
+        const g = store.grant();
+        if (!g)
+            return { sessionAddress: address, grant: null, hint: address ? "no grant imported yet" : "no session key yet; call agt_session_new" };
+        const d = await describeGrant(g, { now: now(), verifySignatures: false });
+        const s = await doStatus(g, { rpcUrl: deps.rpcUrl, now: now() });
+        return { sessionAddress: address, grantHash: g.hash, mandate: d.summary, onchain: s };
+    }));
+    server.registerTool("agt_session_forget", {
+        title: "Forget the local grant",
+        description: "Delete the imported grant from this machine (and the session key too if deleteKey is true). This is local housekeeping only: to revoke on-chain, the owner bumps their NonceEnforcer nonce or disables the delegation.",
+        inputSchema: { deleteKey: z.boolean().default(false).describe("Also delete the session private key") },
+        annotations: LOCAL,
+    }, guarded(async ({ deleteKey }) => { store.forget({ key: deleteKey }); return { forgotten: true, keyDeleted: deleteKey, reminder: "On-chain revocation is the owner's: bump the NonceEnforcer nonce (revoke all) or DelegationManager.disableDelegation (one grant)." }; }));
+    server.registerTool("agt_set_text", {
+        title: "Set a text record (under the grant)",
+        description: `Write a text record (url, description, avatar, com.twitter, …) on a granted name. ${ACTIONS.text.describe}. Redeemed through the owner's delegation; reverts if the name, key type or call budget is outside the grant.`,
+        inputSchema: { name: nameSchema, key: z.string().min(1).max(64), value: z.string().max(2048) },
+        annotations: WRITE,
+    }, guarded(({ name, key, value }) => write(name, { action: "text", key, value })));
+    server.registerTool("agt_set_addr", {
+        title: "Set the address record (under the grant)",
+        description: `Write the primary address record on a granted name. ${ACTIONS.addr.describe}.`,
+        inputSchema: { name: nameSchema, address: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
+        annotations: WRITE,
+    }, guarded(({ name, address }) => write(name, { action: "addr", address: address })));
+    server.registerTool("agt_set_endpoint", {
+        title: "Set an agent endpoint (under the grant)",
+        description: `Write the endpoint URL for a protocol on a granted name. ${ACTIONS.endpoint.describe}.`,
+        inputSchema: { name: nameSchema, protocol: z.enum(["mcp", "a2a", "http", "ws"]), url: z.string().url().max(2048) },
+        annotations: WRITE,
+    }, guarded(({ name, protocol, url }) => write(name, { action: "endpoint", protocol, url })));
+    server.registerTool("agt_set_manifest_uri", {
+        title: "Point the name at a manifest URI (under the grant)",
+        description: `Write the on-chain manifest pointer on a granted name. ${ACTIONS.manifest.describe}. The manifest document itself must still be signed by the owner's key; this tool only moves the pointer.`,
+        inputSchema: { name: nameSchema, uri: z.string().min(1).max(2048) },
+        annotations: WRITE,
+    }, guarded(({ name, uri }) => write(name, { action: "manifest", uri })));
+    server.registerTool("agt_set_wallet", {
+        title: "Set the agent wallet record (under the grant)",
+        description: `Write the agent wallet record on a granted name. ${ACTIONS.wallet.describe}.`,
+        inputSchema: { name: nameSchema, wallet: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
+        annotations: WRITE,
+    }, guarded(({ name, wallet }) => write(name, { action: "wallet", wallet: wallet })));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agtnames/mcp",
-  "version": "1.1.0",
-  "description": "MCP server for .agt agent names: resolve, verify and discover agents by name against AGT Registry v2. Works with any MCP-compatible client (Claude Code, Cursor, custom agents).",
+  "version": "1.2.0",
+  "description": "MCP server for .agt agent names: resolve, verify and discover agents by name against AGT Registry v2, and (opt-in) write records under an owner-signed session grant. Works with any MCP-compatible client (Claude Code, Cursor, custom agents).",
   "type": "module",
   "bin": {
     "agt-mcp": "dist/index.js"
@@ -21,7 +21,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ds1/agt-site.git",
+    "url": "git+https://github.com/ds1/agt-site.git",
     "directory": "packages/mcp"
   },
   "homepage": "https://agtnames.com/docs/claude-code",
@@ -32,9 +32,11 @@
     "prepublishOnly": "node scripts/check-publish-deps.mjs && npm run build && npm test"
   },
   "dependencies": {
-    "@agtnames/resolver": "^1.0.2",
+    "@agtnames/resolver": "^1.0.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.25.0"
+    "zod": "^3.25.0",
+    "@agtnames/countersign": "^0.1.0",
+    "viem": "^2.56.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",