web3-tools-mcp 1.5.0 → 2.0.0

package/dist/walletconnect.js

@@ -0,0 +1,221 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getClientManager } from './client.js';
+import { getKeyValueStorage } from './kv-storage.js';
+async function importSignClient() {
+    // Imported lazily: several MB of SDK that is pointless to load without a project ID.
+    const { SignClient } = await import('@walletconnect/sign-client');
+    return SignClient;
+}
+const METHODS = ['eth_sendTransaction', 'personal_sign', 'eth_signTypedData_v4'];
+const EVENTS = ['chainChanged', 'accountsChanged'];
+const APPROVAL_TIMEOUT = 300_000;
+/**
+ * Where this server lives, as shown to the wallet. A hosted server knows its public URL;
+ * a local one is only reachable from the machine it runs on, and says so.
+ */
+function serverUrl() {
+    if (process.env.MCP_PUBLIC_URL)
+        return process.env.MCP_PUBLIC_URL.replace(/\/$/, '');
+    if (process.env.MCP_HTTP_PORT)
+        return `http://localhost:${process.env.MCP_HTTP_PORT}`;
+    return 'http://localhost';
+}
+function storePath() {
+    const dir = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'web3-tools-mcp');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return join(dir, 'walletconnect.db');
+}
+export class PhoneSigner {
+    projectId;
+    client;
+    starting;
+    pairing;
+    /** Label shown in the wallet; whoever is driving this server says who they are. */
+    agent;
+    constructor(projectId) {
+        this.projectId = projectId;
+    }
+    async start() {
+        if (this.client)
+            return;
+        if (this.starting)
+            return this.starting;
+        this.starting = (async () => {
+            const SignClient = await importSignClient();
+            // Redis when hosted (a free-tier filesystem is ephemeral, and losing the store means
+            // re-pairing by QR after every sleep); a file next to the other config locally.
+            const storage = getKeyValueStorage();
+            this.client = (await SignClient.init({
+                projectId: this.projectId,
+                ...(storage ? { storage } : { storageOptions: { database: storePath() } }),
+                // What the wallet shows when asking you to approve. Approving does not connect a
+                // website — it lets an agent request signatures for as long as the session lives,
+                // so the dialog says that. The name is self-reported and proves nothing; the URL
+                // is what distinguishes this server from any other.
+                metadata: {
+                    name: this.agent ? `${this.agent} via web3-tools-mcp` : 'web3-tools-mcp (AI agent)',
+                    description: 'An AI agent uses this server to request transactions. You approve each one here.',
+                    url: serverUrl(),
+                    icons: []
+                }
+            }));
+        })().finally(() => {
+            this.starting = undefined;
+        });
+        return this.starting;
+    }
+    /** The most recent still-valid session, if the phone is already paired. */
+    async session() {
+        await this.start();
+        const sessions = this.client?.session.getAll() ?? [];
+        const live = sessions.filter((s) => s.expiry * 1000 > Date.now());
+        const session = live[live.length - 1];
+        if (!session)
+            return undefined;
+        const accounts = session.namespaces.eip155?.accounts ?? [];
+        return {
+            topic: session.topic,
+            // "eip155:8453:0xabc…" → address / chain id
+            accounts: [...new Set(accounts.map((a) => a.split(':')[2]))],
+            chains: [...new Set(accounts.map((a) => Number(a.split(':')[1])))],
+            peer: session.peer?.metadata?.name
+        };
+    }
+    async isPaired() {
+        return Boolean(await this.session());
+    }
+    /**
+     * Start a pairing and return its URI immediately, resolving the wallet's approval in the
+     * background — a tool result only reaches the user once it returns, so blocking here
+     * would hide the QR they are supposed to scan.
+     */
+    async pair(chains, agent) {
+        // Metadata is fixed when the client starts, so a new label needs a new client. Only
+        // safe while nothing is connected — an existing session owns the old client.
+        if (agent && agent !== this.agent && this.client && this.client.session.getAll().length === 0) {
+            this.client = undefined;
+        }
+        if (agent)
+            this.agent = agent;
+        await this.start();
+        if (!this.client)
+            throw new Error('WalletConnect failed to start');
+        const clientManager = getClientManager();
+        const eip155 = chains.map((chain) => `eip155:${clientManager.getChainId(chain)}`);
+        const { uri, approval } = await this.client.connect({
+            // Optional rather than required: wallets reject a session outright when they cannot
+            // serve every required chain, and few support all thirteen.
+            optionalNamespaces: { eip155: { chains: eip155, methods: METHODS, events: EVENTS } }
+        });
+        if (!uri)
+            throw new Error('WalletConnect did not return a pairing URI');
+        this.pairing = { uri, expiresAt: Date.now() + APPROVAL_TIMEOUT };
+        approval()
+            .then((session) => console.error(`[WalletConnect] Paired with ${session.peer?.metadata?.name ?? 'a wallet'}`))
+            .catch((error) => console.error('[WalletConnect] Pairing was not completed:', error.message));
+        return uri;
+    }
+    /** Send a request to the paired wallet. Throws if the chain is outside the session. */
+    async request(chain, method, params) {
+        const session = await this.session();
+        if (!session || !this.client)
+            throw new Error('No phone wallet paired');
+        const chainId = getClientManager().getChainId(chain);
+        if (!session.chains.includes(chainId)) {
+            throw new Error(`The paired wallet did not approve ${chain} (chain ${chainId}). It approved: ${session.chains.join(', ')}. Re-pair to add it.`);
+        }
+        return this.client.request({
+            topic: session.topic,
+            chainId: `eip155:${chainId}`,
+            request: { method, params }
+        });
+    }
+    /** Every live session, not just the one that would be used for signing. */
+    async sessions() {
+        await this.start();
+        return (this.client?.session.getAll() ?? []).map((session) => ({
+            topic: session.topic,
+            accounts: [...new Set((session.namespaces.eip155?.accounts ?? []).map((a) => a.split(':')[2]))],
+            chains: [...new Set((session.namespaces.eip155?.accounts ?? []).map((a) => Number(a.split(':')[1])))],
+            peer: session.peer?.metadata?.name
+        }));
+    }
+    /**
+     * Disconnect everything: sessions, and the pairings underneath them. Each pairing
+     * attempt leaves one behind whether or not a wallet ever approved it, so they
+     * accumulate quietly in the store.
+     */
+    async disconnectAll() {
+        await this.start();
+        if (!this.client)
+            return { sessions: 0, pairings: 0 };
+        const sessions = this.client.session.getAll();
+        for (const session of sessions) {
+            await this.client
+                .disconnect({ topic: session.topic, reason: { code: 6000, message: 'User disconnected' } })
+                .catch((error) => console.error('[WalletConnect] Could not disconnect a session:', error.message));
+        }
+        const pairings = this.client.core.pairing.getPairings();
+        for (const pairing of pairings) {
+            await this.client.core.pairing
+                .disconnect({ topic: pairing.topic })
+                .catch((error) => console.error('[WalletConnect] Could not drop a pairing:', error.message));
+        }
+        return { sessions: sessions.length, pairings: pairings.length };
+    }
+    async unpair() {
+        await this.disconnectAll();
+    }
+}
+let wallets;
+/**
+ * Wallets from WalletConnect's registry, so the links we hand out are the schemes each
+ * wallet actually registered rather than ones we invented. Fetched once per process; a
+ * failure is not fatal, it just means no ready-made links.
+ */
+async function walletRegistry(projectId) {
+    if (wallets)
+        return wallets;
+    try {
+        const response = await fetch(`https://explorer-api.walletconnect.com/v3/wallets?projectId=${projectId}&entries=100&page=1`);
+        const listings = (await response.json()).listings ?? {};
+        wallets = Object.values(listings)
+            .map(({ name, mobile }) => ({ name, native: mobile?.native || undefined, universal: mobile?.universal || undefined }))
+            .filter((wallet) => wallet.native || wallet.universal);
+    }
+    catch {
+        wallets = [];
+    }
+    return wallets;
+}
+/**
+ * Links that open a wallet straight onto this pairing, for when the agent is running on
+ * the phone itself and there is no second screen to scan from.
+ *
+ * Native schemes are preferred over universal links: chat apps are documented to mishandle
+ * the latter, opening the wallet with no prompt or diverting to an app store.
+ */
+export async function pairingLinks(projectId, uri, search) {
+    const registry = await walletRegistry(projectId);
+    const encoded = encodeURIComponent(uri);
+    const matches = search
+        ? registry.filter((wallet) => wallet.name.toLowerCase().includes(search.toLowerCase()))
+        : registry.slice(0, 12);
+    return Object.fromEntries(matches.map((wallet) => {
+        const base = wallet.native ?? `${wallet.universal?.replace(/\/$/, '')}/`;
+        return [wallet.name, `${base}wc?uri=${encoded}`];
+    }));
+}
+let signer = null;
+/** Configured only when a WalletConnect project id is present. */
+export function getPhoneSigner() {
+    const projectId = getClientManager().getConfig().walletConnectProjectId;
+    if (!projectId)
+        return null;
+    if (!signer)
+        signer = new PhoneSigner(projectId);
+    return signer;
+}
+//# sourceMappingURL=walletconnect.js.map

package/dist/walletconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletconnect.js","sourceRoot":"","sources":["../src/walletconnect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAYpD,KAAK,UAAU,gBAAgB;IAC7B,qFAAqF;IACrF,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAA;IACjE,OAAO,UAAU,CAAA;AACnB,CAAC;AASD,MAAM,OAAO,GAAG,CAAC,qBAAqB,EAAE,eAAe,EAAE,sBAAsB,CAAC,CAAA;AAChF,MAAM,MAAM,GAAG,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAA;AAClD,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEhC;;;GAGG;AACH,SAAS,SAAS;IAChB,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACpF,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa;QAAE,OAAO,oBAAoB,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAA;IACrF,OAAO,kBAAkB,CAAA;AAC3B,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,gBAAgB,CAAC,CAAA;IAC7F,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAChD,OAAO,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,OAAO,WAAW;IAOF;IANZ,MAAM,CAA4B;IAClC,QAAQ,CAA2B;IACnC,OAAO,CAAgD;IAC/D,mFAAmF;IAC3E,KAAK,CAAoB;IAEjC,YAAoB,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;IAEjC,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAA;QAEvC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,UAAU,GAAG,MAAM,gBAAgB,EAAE,CAAA;YAC3C,qFAAqF;YACrF,gFAAgF;YAChF,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAA;YACpC,IAAI,CAAC,MAAM,GAAG,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC;gBACnC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;gBAC1E,iFAAiF;gBACjF,kFAAkF;gBAClF,iFAAiF;gBACjF,oDAAoD;gBACpD,QAAQ,EAAE;oBACR,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,qBAAqB,CAAC,CAAC,CAAC,2BAA2B;oBACnF,WAAW,EAAE,kFAAkF;oBAC/F,GAAG,EAAE,SAAS,EAAE;oBAChB,KAAK,EAAE,EAAE;iBACV;aACF,CAAC,CAAmB,CAAA;QACvB,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAChB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;QAC3B,CAAC,CAAC,CAAA;QAEF,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAA;QACpD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAA;QAE9B,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAA;QAC1D,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,4CAA4C;YAC5C,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAW,CAAC,CAAC,CAAC;YACtE,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI;SACnC,CAAA;IACH,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,OAAO,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IACtC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,MAAmB,EAAE,KAAc;QAC5C,oFAAoF;QACpF,6EAA6E;QAC7E,IAAI,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9F,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QACzB,CAAC;QACD,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAE7B,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;QAElE,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAA;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,aAAa,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAEjF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAClD,oFAAoF;YACpF,4DAA4D;YAC5D,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;SACrF,CAAC,CAAA;QAEF,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;QACvE,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,gBAAgB,EAAE,CAAA;QAEhE,QAAQ,EAAE;aACP,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,+BAA+B,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,UAAU,EAAE,CAAC,CAAC;aAC7G,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;QAE/F,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,KAAgB,EAAE,MAAc,EAAE,MAAiB;QAC/D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACpC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;QAEvE,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;QACpD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,qCAAqC,KAAK,WAAW,OAAO,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAC/H,CAAA;QACH,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,UAAU,OAAO,EAAE;YAC5B,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;SAC5B,CAAC,CAAA;IACJ,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QAClB,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7D,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAW,CAAC,CAAC,CAAC;YACzG,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrG,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI;SACnC,CAAC,CAAC,CAAA;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAA;QAErD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAA;QAC7C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,CAAC,MAAM;iBACd,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,mBAAmB,EAAE,EAAE,CAAC;iBAC1F,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;QACtG,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;QACvD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO;iBAC3B,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;iBACpC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;QAChG,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAA;IACjE,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,aAAa,EAAE,CAAA;IAC5B,CAAC;CACF;AAQD,IAAI,OAAkC,CAAA;AAEtC;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAAC,SAAiB;IAC7C,IAAI,OAAO;QAAE,OAAO,OAAO,CAAA;IAE3B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,+DAA+D,SAAS,qBAAqB,CAAC,CAAA;QAC3H,MAAM,QAAQ,GACX,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2E,CAAC,QAAQ,IAAI,EAAE,CAAA;QAEnH,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;aAC9B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,SAAS,EAAE,CAAC,CAAC;aACrH,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS,CAAC,CAAA;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,EAAE,CAAA;IACd,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAiB,EAAE,GAAW,EAAE,MAAe;IAChF,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAA;IAChD,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAEvC,MAAM,OAAO,GAAG,MAAM;QACpB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QACvF,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAEzB,OAAO,MAAM,CAAC,WAAW,CACvB,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAA;QACxE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,UAAU,OAAO,EAAE,CAAC,CAAA;IAClD,CAAC,CAAC,CACH,CAAA;AACH,CAAC;AAED,IAAI,MAAM,GAAuB,IAAI,CAAA;AAErC,kEAAkE;AAClE,MAAM,UAAU,cAAc;IAC5B,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC,SAAS,EAAE,CAAC,sBAAsB,CAAA;IACvE,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAA;IAC3B,IAAI,CAAC,MAAM;QAAE,MAAM,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAA;IAChD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "web3-tools-mcp",
-  "version": "1.5.0",
-  "description": "Model Context Protocol server for blockchain interactions using viem, Etherscan, and Hypersync",
+  "version": "2.0.0",
+  "description": "Model Context Protocol server for blockchain data and transaction signing — sign in a browser wallet or on your phone, with simulation and ERC-7730 clear signing before you approve",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "src"
   ],
@@ -19,14 +20,15 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && npm run build -w web3-wallet-relay && tsc && cp src/erc7730-index.json.gz dist/",
+    "build": "npm run clean && tsc && cp src/erc7730-index.json.gz dist/",
     "watch": "tsc --watch",
-    "start:wallet": "npm start -w web3-wallet-relay",
-    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
-    "sync:registry": "node scripts/build-erc7730-index.mjs /tmp/erc7730/registry src/erc7730-index.json.gz"
+    "sync:registry": "node scripts/build-erc7730-index.mjs /tmp/erc7730/registry src/erc7730-index.json.gz",
+    "start": "node dist/index.js",
+    "prepack": "npm run build && cp ../README.md ../CHANGELOG.md ../LICENSE ."
   },
   "keywords": [
     "mcp",
@@ -37,13 +39,18 @@
     "ens",
     "ethereum-name-service",
     "model-context-protocol",
-    "ai"
+    "ai",
+    "walletconnect",
+    "clear-signing",
+    "erc-7730",
+    "transaction-signing"
   ],
   "author": "Benjamin Hajnal <hajnalbenjamin@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hajnalben/web3-tools-mcp.git"
+    "url": "git+https://github.com/hajnalben/web3-tools-mcp.git",
+    "directory": "mcp"
   },
   "bugs": {
     "url": "https://github.com/hajnalben/web3-tools-mcp/issues"
@@ -53,13 +60,18 @@
     "@envio-dev/hypersync-client": "^0.6.5",
     "@modelcontextprotocol/sdk": "^1.20.1",
     "@shazow/whatsabi": "^0.29.0",
+    "@walletconnect/sign-client": "^2.25.0",
+    "express": "^5.2.1",
+    "qrcode-terminal": "^0.12.0",
     "viem": "^2.31.4",
-    "web3-wallet-relay": "^1.0.0",
+    "web3-wallet-relay": "^1.2.0",
     "ws": "^8.18.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^20.19.23",
+    "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.5.13",
     "@vitest/ui": "^3.2.4",
     "dotenv": "^17.2.3",

package/src/anvil.ts

@@ -1,4 +1,4 @@
-import { spawn, ChildProcess } from 'child_process'
+import { type ChildProcess, spawn } from 'node:child_process'
 import { createPublicClient, http } from 'viem'
 import { mainnet } from 'viem/chains'
 
@@ -18,16 +18,16 @@ export interface AnvilConfig {
 
 // Check if anvil is installed
 export async function isAnvilInstalled(): Promise<boolean> {
-  return new Promise(resolve => {
+  return new Promise((resolve) => {
     const proc = spawn('anvil', ['--version'], { shell: true })
-    proc.on('close', code => resolve(code === 0))
+    proc.on('close', (code) => resolve(code === 0))
     proc.on('error', () => resolve(false))
   })
 }
 
 // Find an available port
 async function findAvailablePort(startPort: number = 8545): Promise<number> {
-  const net = await import('net')
+  const net = await import('node:net')
   return new Promise((resolve, reject) => {
     const server = net.createServer()
     server.listen(startPort, () => {
@@ -40,7 +40,9 @@ async function findAvailablePort(startPort: number = 8545): Promise<number> {
     })
     server.on('error', () => {
       // Port in use, try next one
-      findAvailablePort(startPort + 1).then(resolve).catch(reject)
+      findAvailablePort(startPort + 1)
+        .then(resolve)
+        .catch(reject)
     })
   })
 }
@@ -49,9 +51,7 @@ async function findAvailablePort(startPort: number = 8545): Promise<number> {
 export async function startAnvil(config: AnvilConfig): Promise<AnvilInstance> {
   const installed = await isAnvilInstalled()
   if (!installed) {
-    throw new Error(
-      'Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation'
-    )
+    throw new Error('Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation')
   }
 
   const port = config.port ?? (await findAvailablePort())
@@ -74,15 +74,15 @@ export async function startAnvil(config: AnvilConfig): Promise<AnvilInstance> {
     })
 
     let stderr = ''
-    proc.stderr?.on('data', data => {
+    proc.stderr?.on('data', (data) => {
       stderr += data.toString()
     })
 
-    proc.on('error', err => {
+    proc.on('error', (err) => {
       reject(new Error(`Failed to start Anvil: ${err.message}`))
     })
 
-    proc.on('close', code => {
+    proc.on('close', (code) => {
       if (code !== 0 && code !== null) {
         reject(new Error(`Anvil exited with code ${code}: ${stderr}`))
       }
@@ -107,7 +107,7 @@ export async function startAnvil(config: AnvilConfig): Promise<AnvilInstance> {
         })
         if (response.ok) {
           // Add small delay to ensure all RPC methods are ready (including debug_*)
-          await new Promise(r => setTimeout(r, 100))
+          await new Promise((r) => setTimeout(r, 100))
           const client = createPublicClient({
             chain: mainnet, // Chain is overridden by fork anyway
             transport: http(rpcUrl)
@@ -142,10 +142,7 @@ export function stopAnvil(instance: AnvilInstance): void {
 }
 
 // Helper to run a function with a temporary Anvil instance
-export async function withAnvil<T>(
-  config: AnvilConfig,
-  fn: (instance: AnvilInstance) => Promise<T>
-): Promise<T> {
+export async function withAnvil<T>(config: AnvilConfig, fn: (instance: AnvilInstance) => Promise<T>): Promise<T> {
   const instance = await startAnvil(config)
   try {
     return await fn(instance)
@@ -193,7 +190,7 @@ export async function traceTransactionWithAnvil(
       forkUrl: archiveUrl,
       forkBlockNumber: forkBlock
     },
-    async instance => {
+    async (instance) => {
       // Use debug_traceCall to simulate and trace the transaction
       // Note: This replays the tx against the post-block state, which may differ slightly
       // from the original execution if state changed within the block
@@ -243,7 +240,7 @@ export async function simulateCallWithTrace(
       forkUrl,
       forkBlockNumber: blockNumber
     },
-    async instance => {
+    async (instance) => {
       // First, try a regular call to get the result
       let result = '0x'
       let success = true

package/src/chain-meta.ts

@@ -3,8 +3,9 @@
  * human labels for addresses. Kept apart from the preview and the clear-signing registry
  * so both can use it without importing each other.
  */
-import { type Abi, type Address, parseAbiItem } from 'viem'
+
 import { whatsabi } from '@shazow/whatsabi'
+import { type Abi, type Address, parseAbiItem } from 'viem'
 import { getClientManager } from './client.js'
 import type { ChainName } from './types.js'
 
@@ -26,7 +27,9 @@ export async function loadAbi(chain: ChainName, address: string) {
   const client = clientManager.getClient(chain)
   const etherscanApiKey = clientManager.getConfig().etherscanApiKey
 
-  const loaders: whatsabi.loaders.ABILoader[] = [new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })]
+  const loaders: whatsabi.loaders.ABILoader[] = [
+    new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })
+  ]
   if (etherscanApiKey) {
     loaders.push(new whatsabi.loaders.EtherscanV2ABILoader({ apiKey: etherscanApiKey, chainId: clientManager.getChainId(chain) }))
   }
@@ -83,7 +86,9 @@ export async function addressLabel(chain: ChainName, address: string): Promise<s
 
   let label: string | undefined
   try {
-    const code = await getClientManager().getClient(chain).getBytecode({ address: address as Address })
+    const code = await getClientManager()
+      .getClient(chain)
+      .getBytecode({ address: address as Address })
     if (code && code !== '0x') {
       label = (await tokenMeta(chain, address).catch(() => ({ symbol: undefined }))).symbol
       if (!label) label = (await loadAbi(chain, address)).name
@@ -96,7 +101,6 @@ export async function addressLabel(chain: ChainName, address: string): Promise<s
   return label
 }
 
-
 /** uint256 max and anything near it means "infinite" in an approval. */
 export const MAX_UINT256 = (1n << 256n) - 1n
 export const UNLIMITED_THRESHOLD = MAX_UINT256 / 2n

package/src/chains.ts

@@ -0,0 +1,145 @@
+import type { Chain } from 'viem'
+import {
+  arbitrum,
+  avalanche,
+  base,
+  bsc,
+  gnosis,
+  linea,
+  localhost,
+  mainnet,
+  optimism,
+  polygon,
+  sonic,
+  unichain,
+  zksync
+} from 'viem/chains'
+
+/**
+ * Every chain this server knows, in one table. Adding one here is the whole change: the
+ * `ChainName` union, the tool schemas, RPC selection, explorer links, Hypersync routing and
+ * the `--help` listing are all derived from it.
+ */
+interface ChainInfo {
+  chain: Chain
+  /** Subdomain under g.alchemy.com; absent where Alchemy has no endpoint. */
+  alchemy?: string
+  /** Subdomain under infura.io; absent where Infura has no endpoint. */
+  infura?: string
+  /** Used when no provider key is configured. */
+  fallback: string
+  /** Block explorer domain, for links. Absent where there is nothing to link to. */
+  explorer?: string
+  hypersync?: string
+}
+
+const TABLE = {
+  mainnet: {
+    chain: mainnet,
+    alchemy: 'eth-mainnet',
+    infura: 'mainnet',
+    fallback: 'https://ethereum-rpc.publicnode.com',
+    explorer: 'etherscan.io',
+    hypersync: 'https://eth.hypersync.xyz'
+  },
+  arbitrum: {
+    chain: arbitrum,
+    alchemy: 'arb-mainnet',
+    infura: 'arbitrum-mainnet',
+    fallback: 'https://arb1.arbitrum.io/rpc',
+    explorer: 'arbiscan.io',
+    hypersync: 'https://arbitrum.hypersync.xyz'
+  },
+  avalanche: {
+    chain: avalanche,
+    alchemy: 'avax-mainnet',
+    infura: 'avalanche-mainnet',
+    fallback: 'https://api.avax.network/ext/bc/C/rpc',
+    explorer: 'snowtrace.io',
+    hypersync: 'https://avalanche.hypersync.xyz'
+  },
+  base: {
+    chain: base,
+    alchemy: 'base-mainnet',
+    // publicnode refuses receipts and anything else it calls an archive request
+    fallback: 'https://mainnet.base.org',
+    explorer: 'basescan.org',
+    hypersync: 'https://base.hypersync.xyz'
+  },
+  bnb: {
+    chain: bsc,
+    alchemy: 'bnb-mainnet',
+    infura: 'bsc-mainnet',
+    fallback: 'https://bsc-dataseed.bnbchain.org',
+    explorer: 'bscscan.com',
+    hypersync: 'https://bsc.hypersync.xyz'
+  },
+  gnosis: {
+    chain: gnosis,
+    alchemy: 'gnosis-mainnet',
+    fallback: 'https://rpc.gnosischain.com',
+    explorer: 'gnosisscan.io',
+    hypersync: 'https://gnosis.hypersync.xyz'
+  },
+  sonic: {
+    chain: sonic,
+    alchemy: 'sonic-mainnet',
+    fallback: 'https://rpc.soniclabs.com',
+    explorer: 'sonicscan.org',
+    hypersync: 'https://sonic.hypersync.xyz'
+  },
+  optimism: {
+    chain: optimism,
+    alchemy: 'opt-mainnet',
+    infura: 'optimism-mainnet',
+    fallback: 'https://mainnet.optimism.io',
+    explorer: 'optimistic.etherscan.io',
+    hypersync: 'https://optimism.hypersync.xyz'
+  },
+  polygon: {
+    chain: polygon,
+    alchemy: 'polygon-mainnet',
+    infura: 'polygon-mainnet',
+    // polygon-rpc.com now answers 401 "API key disabled" to anonymous callers
+    fallback: 'https://polygon-bor-rpc.publicnode.com',
+    explorer: 'polygonscan.com',
+    hypersync: 'https://polygon.hypersync.xyz'
+  },
+  zksync: {
+    chain: zksync,
+    alchemy: 'zksync-mainnet',
+    infura: 'zksync-mainnet',
+    fallback: 'https://mainnet.era.zksync.io',
+    explorer: 'era.zksync.network',
+    hypersync: 'https://zksync.hypersync.xyz'
+  },
+  linea: {
+    chain: linea,
+    alchemy: 'linea-mainnet',
+    infura: 'linea-mainnet',
+    fallback: 'https://rpc.linea.build',
+    explorer: 'lineascan.build',
+    hypersync: 'https://linea.hypersync.xyz'
+  },
+  unichain: {
+    chain: unichain,
+    alchemy: 'unichain-mainnet',
+    infura: 'unichain-mainnet',
+    fallback: 'https://mainnet.unichain.org',
+    explorer: 'uniscan.xyz',
+    hypersync: 'https://unichain.hypersync.xyz'
+  },
+  localhost: {
+    chain: localhost,
+    fallback: 'http://localhost:8545'
+  }
+} as const satisfies Record<string, ChainInfo>
+
+export type ChainName = keyof typeof TABLE
+
+// Widened: `as const` above is only there to infer ChainName from the keys, and reading a
+// literal entry would otherwise lose the fields that not every chain sets.
+export const CHAINS: Record<ChainName, ChainInfo> = TABLE
+
+/** Tuple rather than array, because `z.enum` needs a non-empty literal list. */
+export const SUPPORTED_CHAINS = Object.keys(CHAINS) as [ChainName, ...ChainName[]]