clanker-wallet 0.5.0 → 0.6.1

package/README.md

@@ -154,6 +154,35 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 | Sepolia (testnet) | 11155111 |
 | Base Sepolia (testnet) | 84532 |
 
+## MCP (assistants)
+
+`clanker-wallet mcp` runs an MCP server over stdio, so an assistant (Claude Desktop, Claude Code, Cursor, or another MCP host that runs local commands) can ask for transactions as tool calls. The human approves every request on their own device; the server holds no wallet keys. It uses the CLI's identity and pairings in `~/.clanker-wallet/`, so pair first (`clanker-wallet pair '<JSON>'`, once per chain family). In a sandbox the server needs the same relay access and `~/.clanker-wallet/` writes as the CLI.
+
+Claude Code:
+
+```bash
+claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and any other MCP host that runs local stdio servers (command `npx`, args `-y clanker-wallet mcp`):
+
+```json
+{
+  "mcpServers": {
+    "clanker-wallet": { "command": "npx", "args": ["-y", "clanker-wallet", "mcp"] }
+  }
+}
+```
+
+| Tool | Arguments | Returns |
+|------|-----------|---------|
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
+| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+
+Requests are asynchronous: a request tool returns once the relay has the request, then the assistant calls `get_request` (with `wait_seconds` to wait for an answer) until the status is no longer `pending`. Invalid input or a missing pairing is a tool error, and nothing is sent. Pending requests live in the server process: after 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows them (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+
 ---
 
 ## Library Usage (Advanced)

package/SKILL.md

@@ -191,6 +191,37 @@ clanker-wallet whoami
 # → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
+## MCP (assistants)
+
+`clanker-wallet mcp` runs an MCP server over stdio, so an assistant (Claude Desktop, Claude Code, Cursor, or another MCP host that runs local commands) can ask for transactions as tool calls. The human approves every request on their own device; the server holds no wallet keys. It uses the CLI's identity and pairings in `~/.clanker-wallet/`, so pair first (`clanker-wallet pair '<JSON>'`, once per chain family). In a sandbox the server needs the same relay access and `~/.clanker-wallet/` writes as the CLI.
+
+If your host supports MCP, the human can add the server instead of you running `tx` / `send`:
+
+Claude Code:
+
+```bash
+claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and any other MCP host that runs local stdio servers (command `npx`, args `-y clanker-wallet mcp`):
+
+```json
+{
+  "mcpServers": {
+    "clanker-wallet": { "command": "npx", "args": ["-y", "clanker-wallet", "mcp"] }
+  }
+}
+```
+
+| Tool | Arguments | Returns |
+|------|-----------|---------|
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
+| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+
+Flow: call `list_pairings` to see which chains you can use, call `request_evm_tx` or `request_transfer` (same rules as `tx` / `send`: wei and sats as integer strings, real addresses), tell the human a request is waiting (see "Transaction notifications"), then call `get_request` with `wait_seconds` until the status is no longer `pending`. Invalid input or a missing pairing comes back as a tool error and nothing is sent. After 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows its earlier requests (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+
 ## Troubleshooting
 
 - **exit code 5 / "invalid --flag: ..."** — fix the named flag; nothing was sent. Usually a placeholder `--to`, a `--value` in ETH instead of wei, or `--data` that isn't even-length hex

package/bin/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { ClankerWallet, InvalidTxError, validateTransfer, validateTx } from '../dist/index.js'
+import { createMcpServer, MAX_WAIT_SECONDS, REQUEST_STATUSES } from '../dist/mcp.js'
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
+import { createInterface } from 'readline'
 
 // ── constants ────────────────────────────────────────────────────────
 const STATE_DIR = join(homedir(), '.clanker-wallet')
@@ -167,9 +169,8 @@ function contextFrom(flags) {
   return Object.keys(context).length > 0 ? context : undefined
 }
 
-/** a ClankerWallet paired from a saved pairing */
-function pairedWallet(pairing) {
-  const wallet = getWallet()
+/** a ClankerWallet (the saved identity by default) paired from a saved pairing */
+function pairedWallet(pairing, wallet = getWallet()) {
   wallet.pair(JSON.stringify({
     version: 1,
     pubkey: pairing.pubkey,
@@ -308,9 +309,55 @@ function cmdWhoami() {
   })
 }
 
+function packageVersion() {
+  return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+}
+
 function cmdVersion() {
-  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-  process.stdout.write(version + '\n')
+  process.stdout.write(packageVersion() + '\n')
+}
+
+function showMcpHelp() {
+  process.stderr.write(`clanker-wallet mcp — MCP server over stdio for assistants (Claude Desktop, Claude Code, Cursor, ...)
+
+uses this agent's identity and pairings (~/.clanker-wallet/); pair first with: clanker-wallet pair '<JSON>'
+every request waits for the human to approve it on their own device.
+
+tools:
+  request_evm_tx    ask for an evm transaction (value in wei, integer string) -> { request_id }
+  request_transfer  ask for a bitcoin send (amount in sats, integer string) -> { request_id }
+  get_request       ${REQUEST_STATUSES.join(' | ')}; wait_seconds up to ${MAX_WAIT_SECONDS}
+  list_pairings     paired chain families, networks, wallets, and the agent fingerprint
+
+claude code:     claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+other hosts:     {"mcpServers":{"clanker-wallet":{"command":"npx","args":["-y","clanker-wallet","mcp"]}}}
+
+requests are kept in memory: after 1 h the server stops waiting (expired), and a restart forgets pending ones.
+expired, unknown (relay lost after delivery) or forgotten: the human may still approve it, so ask before sending it again.
+docs: https://clanker-wallet.xyz/SKILL.md
+`)
+}
+
+/** serve MCP on stdin/stdout until stdin ends; stdout carries only protocol messages */
+async function cmdMcp(flags) {
+  if (flags.help) return showMcpHelp()
+
+  const identity = getWallet()
+  const server = createMcpServer({
+    version: packageVersion(),
+    identity: { agent_id: identity.agentId, fingerprint: fingerprint(hex(identity.publicKey)) },
+    loadPairing,
+    // the identity loaded at startup, which list_pairings shows: re-reading identity.json per request could switch agents mid-run
+    wallet: (pairing) => pairedWallet(pairing, new ClankerWallet({ secretKey: identity.secretKey })),
+  })
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  // each line is answered when it settles, so a get_request that waits never holds up the others
+  lines.on('line', (line) => {
+    server.handleLine(line).then((reply) => { if (reply) process.stdout.write(reply + '\n') })
+  })
+  await new Promise((resolve) => lines.on('close', resolve))
+  // the host is gone: drop pending requests (their relay sockets would keep the process alive)
+  process.exit(EXIT.OK)
 }
 
 function showHelp() {
@@ -322,6 +369,7 @@ commands:
   send            send btc or xch; the human's wallet builds it (blocks until approved/rejected)
   status          check pairing status (one pairing per chain family: evm, bitcoin, chia)
   whoami          show agent identity
+  mcp             run an MCP server over stdio for assistants (Claude Desktop/Code, Cursor, ...); mcp --help
 
 tx flags:
   --chain <id>                 chain ID (required) — 1, 8453, 84532 (base sepolia), etc.
@@ -383,6 +431,9 @@ switch (cmd) {
   case 'whoami':
     cmdWhoami()
     break
+  case 'mcp':
+    await cmdMcp(flags)
+    break
   case '--version':
   case '-v':
     cmdVersion()

package/dist/client.d.ts

@@ -1,5 +1,9 @@
 import { TypedEmitter } from './events.js';
 import type { PairingData, RequestTransferOptions, RequestTxOptions } from './types.js';
+/** the relay answered with an error frame (rate limited, message too large, ...): it refused the request instead of passing it on */
+export declare class RelayError extends Error {
+    constructor(message: string);
+}
 export interface ClankerWalletOptions {
     /** agent display name (informational) */
     agentName?: string;

package/dist/client.js

@@ -12,6 +12,13 @@ function proxyHint() {
         ? '; HTTPS_PROXY is set but node ignores it, rerun with NODE_USE_ENV_PROXY=1 (node 24+)'
         : '';
 }
+/** the relay answered with an error frame (rate limited, message too large, ...): it refused the request instead of passing it on */
+export class RelayError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RelayError';
+    }
+}
 export class ClankerWallet extends TypedEmitter {
     publicKey;
     secretKey;
@@ -92,7 +99,7 @@ export class ClankerWallet extends TypedEmitter {
         const simulate = mode === 'managed'
             ? { from: humanWallet || '', to: transaction.to, value: transaction.value, data: transaction.data, chainId: chain_id }
             : undefined;
-        return this.send(txRequest, options.timeout_ms ?? DEFAULT_TIMEOUT_MS, simulate);
+        return this.send(txRequest, options, simulate);
     }
     /**
      * send a bitcoin / chia transfer to the paired human and wait for their response.
@@ -122,34 +129,56 @@ export class ClankerWallet extends TypedEmitter {
         };
         request.signature = signMessage(JSON.stringify(request), this.signingSecretKey);
         // the relay simulator is evm-only: no simulate object for transfers, even on a managed pairing
-        return this.send(request, options.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+        return this.send(request, options);
     }
     /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
-    send(request, timeoutMs, simulate) {
+    send(request, options, simulate) {
         const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
         const requestId = request.request_id;
+        const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+        const { join_timeout_ms: joinTimeoutMs, signal } = options;
         return new Promise((resolve, reject) => {
             let ws;
             let timer;
+            let joinTimer;
             let settled = false;
+            const onAbort = () => {
+                if (!settled)
+                    fail(`request ${requestId} cancelled`);
+            };
             const cleanup = () => {
                 settled = true;
                 clearTimeout(timer);
+                clearTimeout(joinTimer);
+                signal?.removeEventListener('abort', onAbort);
                 if (ws && ws.readyState <= WebSocket.OPEN) {
                     ws.close();
                 }
             };
-            const fail = (message) => {
+            const fail = (error) => {
+                const err = typeof error === 'string' ? new Error(error) : error;
                 cleanup();
-                this.emit('error', { message });
-                reject(new Error(message));
+                this.emit('error', { message: err.message });
+                reject(err);
             };
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort);
             timer = setTimeout(() => {
                 if (!settled) {
                     fail(`request ${requestId} timed out after ${timeoutMs}ms`);
                 }
             }, timeoutMs);
             this.emit('connecting', { relay: relayUrl });
+            // the request goes out only once joined, so failing before then guarantees nothing was sent
+            if (joinTimeoutMs !== undefined) {
+                joinTimer = setTimeout(() => {
+                    if (!settled)
+                        fail(`relay ${relayUrl} did not answer join within ${joinTimeoutMs}ms; request ${requestId} was not sent`);
+                }, joinTimeoutMs);
+            }
             try {
                 ws = new WebSocket(relayUrl);
             }
@@ -183,6 +212,7 @@ export class ClankerWallet extends TypedEmitter {
                     return;
                 }
                 if (msg.type === 'joined') {
+                    clearTimeout(joinTimer);
                     this.emit('connected', { room: humanPubkeyHex });
                     const ciphertext = encryptMessage(JSON.stringify(request), humanPubkey, this.secretKey);
                     const envelope = {
@@ -238,7 +268,7 @@ export class ClankerWallet extends TypedEmitter {
                     return;
                 }
                 if (msg.type === 'error') {
-                    fail(`relay error: ${msg.message}`);
+                    fail(new RelayError(`relay error: ${msg.message}`));
                 }
             });
         });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ClankerWallet } from './client.js';
+export { ClankerWallet, RelayError } from './client.js';
 export type { ClankerWalletOptions } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ClankerWallet } from './client.js';
+export { ClankerWallet, RelayError } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';
 export { InvalidTxError, isChecksumAddress, validateTransfer, validateTx } from './validate.js';

package/dist/mcp.d.ts

@@ -0,0 +1,176 @@
+import { type ClankerWallet } from './client.js';
+/**
+ * MCP server for `clanker-wallet mcp`: newline-delimited JSON-RPC 2.0 over stdio, hand-written so
+ * tweetnacl stays the only runtime dependency. the cli owns stdin/stdout and the identity and pairing
+ * files; this module answers one line at a time and keeps each request's state in memory.
+ */
+/** newest first; a client asking for another version gets the newest. not 2025-03-26: it requires receiving batches, which we refuse */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
+/** get_request waits at most this long per call; assistants time tool calls out after about a minute */
+export declare const MAX_WAIT_SECONDS = 50;
+/** a pairing as the cli saves it in ~/.clanker-wallet/pairings/<family>.json */
+export interface SavedPairing {
+    pubkey: string;
+    relay: string;
+    wallet: string | null;
+    mode: 'encrypted' | 'managed' | null;
+    chain_family?: string;
+    chain_network?: string;
+}
+/** the families the tools request on; chia waits until the web app shows it again */
+type RequestFamily = 'evm' | 'bitcoin';
+export interface McpServerOptions {
+    /** the package version, reported in initialize */
+    version: string;
+    identity: {
+        agent_id: string;
+        fingerprint: string;
+    };
+    /** the saved pairing for a family, or null when that family isn't paired */
+    loadPairing: (family: RequestFamily) => SavedPairing | null;
+    /** a new ClankerWallet with the agent identity, paired from `pairing` */
+    wallet: (pairing: SavedPairing) => ClankerWallet;
+    /** how long a request waits for the human (default 1 h, the relay's buffer) */
+    requestTtlMs?: number;
+    /** how long a request waits for the relay to confirm the join before failing unsent (default 20 s) */
+    joinTimeoutMs?: number;
+}
+export declare const MCP_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            reason: {
+                type: string;
+                description: string;
+            };
+            urgency: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            expected_outcome: {
+                type: string;
+                description: string;
+            };
+            chain_id: {
+                type: string;
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            value: {
+                type: string;
+                description: string;
+            };
+            data: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            reason: {
+                type: string;
+                description: string;
+            };
+            urgency: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            expected_outcome: {
+                type: string;
+                description: string;
+            };
+            family: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            network: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            request_id: {
+                type: string;
+                description: string;
+            };
+            wait_seconds: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required?: undefined;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+    };
+})[];
+/** what get_request reports, in the order the docs list them */
+export declare const REQUEST_STATUSES: readonly ["pending", "approved", "rejected", "failed", "unknown", "expired"];
+export declare function createMcpServer(options: McpServerOptions): {
+    handleLine: (line: string) => Promise<string | null>;
+};
+export {};

package/dist/mcp.js

@@ -0,0 +1,381 @@
+import { RelayError } from './client.js';
+import { InvalidTxError, validateTransfer, validateTx } from './validate.js';
+/**
+ * MCP server for `clanker-wallet mcp`: newline-delimited JSON-RPC 2.0 over stdio, hand-written so
+ * tweetnacl stays the only runtime dependency. the cli owns stdin/stdout and the identity and pairing
+ * files; this module answers one line at a time and keeps each request's state in memory.
+ */
+/** newest first; a client asking for another version gets the newest. not 2025-03-26: it requires receiving batches, which we refuse */
+export const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2024-11-05'];
+/** get_request waits at most this long per call; assistants time tool calls out after about a minute */
+export const MAX_WAIT_SECONDS = 50;
+/** the relay buffers room messages for 1 h, so a later answer can't reach this process */
+const DEFAULT_REQUEST_TTL_MS = 3_600_000;
+/** a relay that hasn't confirmed the join by then fails the request with nothing sent, inside the hosts' 60 s tool-call timeout */
+const DEFAULT_JOIN_TIMEOUT_MS = 20_000;
+const REQUEST_FAMILIES = ['evm', 'bitcoin'];
+const URGENCIES = ['low', 'medium', 'high'];
+const CONTEXT_PROPERTIES = {
+    reason: { type: 'string', description: 'why you want this, in plain words; shown to the human on the review card' },
+    urgency: { type: 'string', enum: URGENCIES, description: 'priority hint shown to the human' },
+    expected_outcome: { type: 'string', description: 'what will happen once it is sent' },
+};
+/**
+ * MCP tool annotations: assistants (ChatGPT, dots, Claude) may skip their confirmation prompt for read-only tools.
+ * a request moves nothing until the human approves it on their device, so it is not destructive, but each call
+ * sends a new request to the human's wallet.
+ */
+const REQUEST_HINTS = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+const READ_HINTS = { readOnlyHint: true, openWorldHint: false };
+export const MCP_TOOLS = [
+    {
+        name: 'request_evm_tx',
+        description: 'Ask the human to send an EVM transaction (ETH or a contract call) from their own wallet. ' +
+            'Nothing is signed here: the human approves every request on their own device, or rejects it. ' +
+            'Returns { request_id } once the request is delivered; then call get_request for the outcome. ' +
+            'value is an integer string in wei (1 ETH = "1000000000000000000"), no decimals.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                chain_id: { type: 'integer', description: 'EVM chain id: 1 Ethereum, 8453 Base, 84532 Base Sepolia, 10 Optimism, 42161 Arbitrum, 137 Polygon' },
+                to: { type: 'string', description: 'recipient or contract: 0x followed by 40 hex characters (mixed case must be EIP-55 checksummed)' },
+                value: { type: 'string', description: 'integer string in wei; "0" for a contract call that sends no ETH' },
+                data: { type: 'string', description: 'hex calldata, default "0x" (a plain transfer)' },
+                ...CONTEXT_PROPERTIES,
+            },
+            required: ['chain_id', 'to', 'value', 'reason'],
+        },
+        annotations: REQUEST_HINTS,
+    },
+    {
+        name: 'request_transfer',
+        description: 'Ask the human to send bitcoin from their own wallet, which builds, signs and broadcasts it. ' +
+            'Nothing is signed here: the human approves every request on their own device, or rejects it. ' +
+            'Returns { request_id } once the request is delivered; then call get_request for the outcome. ' +
+            'amount is an integer string in sats (1 BTC = "100000000"), no decimals; the wallet sets the fee.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                family: { type: 'string', enum: ['bitcoin'], description: 'chain family' },
+                network: { type: 'string', enum: ['mainnet', 'testnet', 'signet'], description: 'must match the paired wallet (see list_pairings)' },
+                to: { type: 'string', description: 'segwit address on that network: bc1... on mainnet, tb1... on testnet and signet' },
+                amount: { type: 'string', description: 'integer string in sats' },
+                ...CONTEXT_PROPERTIES,
+            },
+            required: ['family', 'network', 'to', 'amount', 'reason'],
+        },
+        annotations: REQUEST_HINTS,
+    },
+    {
+        name: 'get_request',
+        description: 'Get the outcome of a request: pending, approved (with tx_hash), rejected, failed (with error), unknown (with error) or expired. ' +
+            `The human may take minutes to answer: pass wait_seconds (at most ${MAX_WAIT_SECONDS}) to wait for it, and call again while it is pending. ` +
+            'unknown means the request was delivered but this server lost its relay connection: the human may still approve it, so ask them before sending it again. ' +
+            'expired means this server stopped waiting, 1 hour after sending; after a restart it no longer knows earlier request ids. ' +
+            'In both cases the human may still approve it in their wallet, so ask them before sending it again.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: { type: 'string', description: 'from request_evm_tx or request_transfer' },
+                wait_seconds: { type: 'number', minimum: 0, maximum: MAX_WAIT_SECONDS, description: 'wait up to this long for an answer (default 0)' },
+            },
+            required: ['request_id'],
+        },
+        annotations: READ_HINTS,
+    },
+    {
+        name: 'list_pairings',
+        description: 'List the wallets you can request on (chain family, network, wallet address, mode) and your agent fingerprint, ' +
+            'which the human compares in the web app before trusting you.',
+        inputSchema: { type: 'object', properties: {} },
+        annotations: READ_HINTS,
+    },
+];
+const INSTRUCTIONS = 'clanker-wallet sends transaction requests to a human, who approves or rejects each one in their own wallet; ' +
+    'you never hold keys. Call list_pairings to see which chains you can use, request_evm_tx or request_transfer to ask, ' +
+    'and get_request (with wait_seconds) until the request is no longer pending.';
+/** what get_request reports, in the order the docs list them */
+export const REQUEST_STATUSES = ['pending', 'approved', 'rejected', 'failed', 'unknown', 'expired'];
+const STILL_APPROVABLE = 'the request was delivered, so the human may still approve it in their wallet: ask them before sending it again';
+/** a JSON-RPC error answered to the client */
+class RpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+/** a tool's input was refused; reported as a tool result with isError, nothing sent */
+class ToolInputError extends Error {
+}
+const toolResult = (body) => ({ content: [{ type: 'text', text: JSON.stringify(body) }] });
+const toolError = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** reason (required, non-blank), urgency and expected_outcome from tool arguments */
+function contextFrom(args) {
+    const { reason, urgency, expected_outcome } = args;
+    if (typeof reason !== 'string' || !reason.trim())
+        throw new ToolInputError('invalid reason: say why, in plain words; the human sees it');
+    const context = { reason };
+    if (urgency !== undefined) {
+        if (typeof urgency !== 'string' || !URGENCIES.includes(urgency))
+            throw new ToolInputError(`invalid urgency: must be ${URGENCIES.join(', ')}`);
+        context.urgency = urgency;
+    }
+    if (expected_outcome !== undefined) {
+        if (typeof expected_outcome !== 'string')
+            throw new ToolInputError('invalid expected_outcome: must be a string');
+        context.expected_outcome = expected_outcome;
+    }
+    return context;
+}
+const NOT_PAIRED = {
+    evm: 'not paired with an evm wallet: ask the human to open https://clanker-wallet.xyz, copy the pairing JSON, and run: clanker-wallet pair \'<JSON>\'',
+    bitcoin: 'not paired with a bitcoin wallet: ask the human to open the bitcoin tab at https://clanker-wallet.xyz, copy its pairing JSON, and run: clanker-wallet pair \'<JSON>\'',
+};
+export function createMcpServer(options) {
+    const ttl = options.requestTtlMs ?? DEFAULT_REQUEST_TTL_MS;
+    const joinTimeout = options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
+    const records = new Map();
+    /** tools/call requests still being answered, by JSON-RPC id, for notifications/cancelled */
+    const inFlight = new Map();
+    /**
+     * start a request on the family's pairing and answer once the relay has it: { request_id } after
+     * the wallet sends it, or a tool error when it fails first (bad input, unreachable relay, join timeout, cancelled)
+     */
+    function submit(family, cancelled, send) {
+        const pairing = options.loadPairing(family);
+        if (!pairing)
+            return Promise.resolve(toolError(NOT_PAIRED[family]));
+        const wallet = options.wallet(pairing);
+        const expiresAt = Date.now() + ttl;
+        // a cancel stops the wallet only before it sends: once delivered, the human can still approve, so keep waiting
+        const unsent = new AbortController();
+        return new Promise((resolve) => {
+            let record;
+            let answered;
+            // this timer decides expiry, not a Date.now() check: timers can fire a millisecond before the clock reaches their
+            // target. it is set before the wallet's own timer of the same ttl, and node runs equal delays in the order they
+            // were set, so the request is expired before the wallet's timeout rejection arrives
+            const expiry = setTimeout(() => record?.settle('expired'), ttl);
+            cancelled.addEventListener('abort', () => { if (!record)
+                unsent.abort(); });
+            wallet.on('request_sent', ({ request_id }) => {
+                record = newRecord(request_id, expiresAt);
+                records.set(request_id, record);
+                record.settled.then(() => clearTimeout(expiry));
+                resolve(toolResult({ request_id, status: 'pending', expires_at: new Date(expiresAt).toISOString() }));
+            });
+            wallet.on('response', (response) => { answered = response; });
+            send(wallet, { timeout_ms: ttl, join_timeout_ms: joinTimeout, signal: unsent.signal }).then((txHash) => record.settle('approved', { tx_hash: txHash }), (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                if (!record) {
+                    clearTimeout(expiry);
+                    return resolve(toolError(message));
+                }
+                if (answered?.status === 'rejected')
+                    record.settle('rejected');
+                else if (answered)
+                    record.settle('failed', { error: message });
+                // the relay refused the request (rate limit, size) and dropped it: nothing reached the human
+                else if (err instanceof RelayError)
+                    record.settle('failed', { error: message });
+                // delivered, then the relay connection dropped: the relay still holds the request for the human
+                // (after expiry the record is already settled and this changes nothing)
+                else
+                    record.settle('unknown', { error: `${message}; ${STILL_APPROVABLE}` });
+            });
+        });
+    }
+    async function requestEvmTx(args, cancelled) {
+        const context = contextFrom(args);
+        const { chain_id, transaction } = validateTx(args.chain_id, { to: args.to, value: args.value, data: args.data ?? '0x' });
+        return submit('evm', cancelled, (wallet, limits) => wallet.requestTx({ chain_id, transaction, context, ...limits }));
+    }
+    async function requestTransfer(args, cancelled) {
+        if (args.family !== 'bitcoin')
+            throw new ToolInputError(`invalid family: must be "bitcoin", got ${JSON.stringify(args.family)}`);
+        const context = contextFrom(args);
+        let request;
+        try {
+            request = validateTransfer('bitcoin', args.network, { asset: 'btc', to: args.to, amount: args.amount });
+        }
+        catch (err) {
+            // the tool calls the network field `network`
+            if (err instanceof InvalidTxError && err.field === 'chain_network')
+                throw new ToolInputError(`invalid network: ${err.reason}`);
+            throw err;
+        }
+        const { chain_network, transfer } = request;
+        return submit('bitcoin', cancelled, async (wallet, limits) => {
+            try {
+                return await wallet.requestTransfer({ chain_network, transfer, context, ...limits });
+            }
+            catch (err) {
+                // the pairing is for another network
+                if (err instanceof InvalidTxError && err.field === 'chain_network')
+                    throw new Error(`invalid network: ${err.reason}`);
+                throw err;
+            }
+        });
+    }
+    async function getRequest(args, cancelled) {
+        const { request_id, wait_seconds = 0 } = args;
+        if (typeof request_id !== 'string')
+            throw new ToolInputError('invalid request_id: must be the string request_evm_tx or request_transfer returned');
+        if (typeof wait_seconds !== 'number' || !(wait_seconds >= 0)) {
+            throw new ToolInputError(`invalid wait_seconds: must be a number from 0 to ${MAX_WAIT_SECONDS}`);
+        }
+        const record = records.get(request_id);
+        if (!record) {
+            throw new ToolInputError(`unknown request_id ${JSON.stringify(request_id)}: this server did not send it, or sent it before it restarted and stopped waiting. ` +
+                'if it was sent before a restart, the human may still approve it in their wallet: ask them before sending it again');
+        }
+        const waitMs = Math.min(wait_seconds, MAX_WAIT_SECONDS) * 1000;
+        if (record.status === 'pending' && waitMs > 0) {
+            let timer;
+            const waits = [record.settled, new Promise((r) => cancelled.addEventListener('abort', r, { once: true }))];
+            // a wait that reaches past expiry ends when the request's expiry timer settles it
+            if (waitMs < record.expiresAt - Date.now())
+                waits.push(new Promise((r) => { timer = setTimeout(r, waitMs); }));
+            await Promise.race(waits);
+            clearTimeout(timer);
+        }
+        // a fallback for an expiry timer that runs late (a busy process): it only marks expired once the clock has passed expires_at
+        if (record.status === 'pending' && Date.now() >= record.expiresAt)
+            record.settle('expired');
+        const { status, tx_hash, error } = record;
+        if (status === 'pending')
+            return toolResult({ request_id, status, expires_at: new Date(record.expiresAt).toISOString() });
+        return toolResult({ request_id, status, ...(tx_hash !== undefined && { tx_hash }), ...(error !== undefined && { error }) });
+    }
+    function listPairings() {
+        const pairings = REQUEST_FAMILIES.flatMap((family) => {
+            const pairing = options.loadPairing(family);
+            return pairing ? [{ family, network: pairing.chain_network ?? null, wallet: pairing.wallet ?? null, mode: pairing.mode ?? null }] : [];
+        });
+        return toolResult({ ...options.identity, pairings });
+    }
+    const TOOL_HANDLERS = {
+        request_evm_tx: requestEvmTx,
+        request_transfer: requestTransfer,
+        get_request: getRequest,
+        list_pairings: listPairings,
+    };
+    async function callTool(params, cancelled) {
+        if (!isObject(params) || typeof params.name !== 'string')
+            throw new RpcError(INVALID_PARAMS, 'tools/call needs a tool name');
+        const handler = TOOL_HANDLERS[params.name];
+        if (!handler)
+            throw new RpcError(INVALID_PARAMS, `unknown tool: ${params.name}`);
+        const args = params.arguments ?? {};
+        if (!isObject(args))
+            throw new RpcError(INVALID_PARAMS, 'tool arguments must be an object');
+        try {
+            return await handler(args, cancelled);
+        }
+        catch (err) {
+            if (err instanceof ToolInputError || err instanceof InvalidTxError)
+                return toolError(err.message);
+            throw err;
+        }
+    }
+    function initialize(params) {
+        const requested = isObject(params) ? params.protocolVersion : undefined;
+        const protocolVersion = typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0];
+        return {
+            protocolVersion,
+            capabilities: { tools: {} },
+            serverInfo: { name: 'clanker-wallet', version: options.version },
+            instructions: INSTRUCTIONS,
+        };
+    }
+    async function dispatch(method, params, cancelled) {
+        switch (method) {
+            case 'initialize': return initialize(params);
+            case 'ping': return {};
+            case 'tools/list': return { tools: MCP_TOOLS };
+            case 'tools/call': return callTool(params, cancelled);
+            default: throw new RpcError(METHOD_NOT_FOUND, `method not found: ${method}`);
+        }
+    }
+    /** the reply to one input line, or null when none is due (blank line, notification, a response from the client) */
+    async function handleLine(line) {
+        if (!line.trim())
+            return null;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return reply(null, { error: { code: PARSE_ERROR, message: 'parse error: each line must be one JSON-RPC message' } });
+        }
+        if (Array.isArray(msg))
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'batches are not supported' } });
+        if (!isObject(msg))
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'invalid request' } });
+        const hasId = 'id' in msg;
+        const id = typeof msg.id === 'string' || typeof msg.id === 'number' ? msg.id : null;
+        if (hasId && id === null)
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'invalid request: id must be a string or number' } });
+        if (typeof msg.method !== 'string') {
+            // a response to us: we send no requests, so there is nothing to match it with
+            if ('result' in msg || 'error' in msg)
+                return null;
+            return reply(id, { error: { code: INVALID_REQUEST, message: 'invalid request: no method' } });
+        }
+        if (msg.jsonrpc !== '2.0')
+            return reply(id, { error: { code: INVALID_REQUEST, message: 'invalid request: jsonrpc must be "2.0"' } });
+        // notifications need no answer; only cancelled changes anything here
+        if (!hasId) {
+            if (msg.method === 'notifications/cancelled' && isObject(msg.params))
+                inFlight.get(msg.params.requestId)?.abort();
+            return null;
+        }
+        const controller = new AbortController();
+        inFlight.set(id, controller);
+        let answer;
+        try {
+            answer = reply(id, { result: await dispatch(msg.method, msg.params, controller.signal) });
+        }
+        catch (err) {
+            if (err instanceof RpcError)
+                answer = reply(id, { error: { code: err.code, message: err.message } });
+            else
+                answer = reply(id, { error: { code: INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err) } });
+        }
+        finally {
+            if (inFlight.get(id) === controller)
+                inFlight.delete(id);
+        }
+        // the client gave up on this call: it expects no response
+        return controller.signal.aborted ? null : answer;
+    }
+    return { handleLine };
+}
+function reply(id, body) {
+    return JSON.stringify({ jsonrpc: '2.0', id, ...body });
+}
+function newRecord(request_id, expiresAt) {
+    let resolveSettled;
+    const record = {
+        request_id,
+        status: 'pending',
+        expiresAt,
+        settled: new Promise((r) => { resolveSettled = r; }),
+        settle: (status, detail = {}) => {
+            if (record.status !== 'pending')
+                return;
+            record.status = status;
+            record.tx_hash = detail.tx_hash;
+            record.error = detail.error;
+            resolveSettled();
+        },
+    };
+    return record;
+}

package/dist/types.d.ts

@@ -61,6 +61,10 @@ export interface RequestTxOptions {
     context?: TxContext;
     /** timeout in ms (default: 3_600_000 = 1hr) */
     timeout_ms?: number;
+    /** fail when the relay hasn't confirmed joining the room this long after connecting (default: only timeout_ms applies); nothing was sent then */
+    join_timeout_ms?: number;
+    /** aborting before the relay confirms the join fails the request with nothing sent; after that it only stops waiting */
+    signal?: AbortSignal;
 }
 /** wallet families a transfer can go to */
 export type TransferFamily = 'bitcoin' | 'chia';
@@ -101,4 +105,8 @@ export interface RequestTransferOptions {
     context?: TxContext;
     /** timeout in ms (default: 3_600_000 = 1hr) */
     timeout_ms?: number;
+    /** fail when the relay hasn't confirmed joining the room this long after connecting (default: only timeout_ms applies); nothing was sent then */
+    join_timeout_ms?: number;
+    /** aborting before the relay confirms the join fails the request with nothing sent; after that it only stops waiting */
+    signal?: AbortSignal;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,6 +59,7 @@
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/bun": "^1.3.8",
     "typescript": "^5.4.0",
     "vitest": "^2.1.0"