clanker-wallet 0.6.0 → 0.7.0

package/README.md

@@ -176,8 +176,8 @@ Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), an
 
 | 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 |
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | `{"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` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | 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 |
 

package/SKILL.md

@@ -215,8 +215,8 @@ Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), an
 
 | 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 |
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | `{"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` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | 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 |
 

package/dist/mcp.d.ts

@@ -41,6 +41,10 @@ export declare const MCP_TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            from: {
+                type: string;
+                description: string;
+            };
             reason: {
                 type: string;
                 description: string;
@@ -75,12 +79,22 @@ export declare const MCP_TOOLS: ({
         };
         required: string[];
     };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
 } | {
     name: string;
     description: string;
     inputSchema: {
         type: string;
         properties: {
+            from: {
+                type: string;
+                description: string;
+            };
             reason: {
                 type: string;
                 description: string;
@@ -117,6 +131,12 @@ export declare const MCP_TOOLS: ({
         };
         required: string[];
     };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -136,6 +156,10 @@ export declare const MCP_TOOLS: ({
         };
         required: string[];
     };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -147,6 +171,10 @@ export declare const MCP_TOOLS: ({
         };
         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"];

package/dist/mcp.js

@@ -20,6 +20,17 @@ const CONTEXT_PROPERTIES = {
     urgency: { type: 'string', enum: URGENCIES, description: 'priority hint shown to the human' },
     expected_outcome: { type: 'string', description: 'what will happen once it is sent' },
 };
+/** the same on both request tools; the hosted connector copies these definitions verbatim */
+const FROM_PROPERTY = {
+    from: { type: 'string', description: 'the paired wallet address to send from, as list_pairings shows it; needed only when several wallets of the same family (evm or bitcoin) are paired' },
+};
+/**
+ * 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',
@@ -35,9 +46,11 @@ export const MCP_TOOLS = [
                 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,
+                ...FROM_PROPERTY,
             },
             required: ['chain_id', 'to', 'value', 'reason'],
         },
+        annotations: REQUEST_HINTS,
     },
     {
         name: 'request_transfer',
@@ -53,9 +66,11 @@ export const MCP_TOOLS = [
                 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,
+                ...FROM_PROPERTY,
             },
             required: ['family', 'network', 'to', 'amount', 'reason'],
         },
+        annotations: REQUEST_HINTS,
     },
     {
         name: 'get_request',
@@ -72,12 +87,14 @@ export const MCP_TOOLS = [
             },
             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; ' +
@@ -123,6 +140,23 @@ function contextFrom(args) {
     }
     return context;
 }
+/** the optional wallet address to send from; undefined means the saved pairing */
+function fromArg(args) {
+    const { from } = args;
+    if (from !== undefined && typeof from !== 'string')
+        throw new ToolInputError('invalid from: must be the wallet address as list_pairings shows it');
+    return from;
+}
+/** a tool error when `from` names a wallet other than the saved pairing's (case-insensitive: evm hex and bech32 both are) */
+function fromMismatch(family, from, pairing) {
+    if (from === undefined || from.toLowerCase() === pairing.wallet?.toLowerCase())
+        return null;
+    // == null: a cli-written pairing stores null, a hand-written file may leave the key out
+    const paired = pairing.wallet == null
+        ? `the ${family} pairing records no wallet address to check it against`
+        : `the paired ${family} wallet is ${pairing.wallet}, the only one this server sends from`;
+    return toolError(`from ${JSON.stringify(from)} is not the paired wallet: ${paired}; nothing was sent`);
+}
 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>\'',
@@ -135,12 +169,16 @@ export function createMcpServer(options) {
     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)
+     * the wallet sends it, or a tool error when it fails first (bad input, `from` not the paired wallet, unreachable relay,
+     * join timeout, cancelled)
      */
-    function submit(family, cancelled, send) {
+    function submit(family, from, cancelled, send) {
         const pairing = options.loadPairing(family);
         if (!pairing)
             return Promise.resolve(toolError(NOT_PAIRED[family]));
+        const mismatch = fromMismatch(family, from, pairing);
+        if (mismatch)
+            return Promise.resolve(mismatch);
         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
@@ -183,13 +221,15 @@ export function createMcpServer(options) {
     }
     async function requestEvmTx(args, cancelled) {
         const context = contextFrom(args);
+        const from = fromArg(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 }));
+        return submit('evm', from, 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);
+        const from = fromArg(args);
         let request;
         try {
             request = validateTransfer('bitcoin', args.network, { asset: 'btc', to: args.to, amount: args.amount });
@@ -201,7 +241,7 @@ export function createMcpServer(options) {
             throw err;
         }
         const { chain_network, transfer } = request;
-        return submit('bitcoin', cancelled, async (wallet, limits) => {
+        return submit('bitcoin', from, cancelled, async (wallet, limits) => {
             try {
                 return await wallet.requestTransfer({ chain_network, transfer, context, ...limits });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",