web3-tools-mcp 1.4.0 → 1.6.0

package/src/chain-meta.ts

@@ -0,0 +1,102 @@
+/**
+ * On-chain metadata every layer of the preview needs: contract ABIs, token symbols and
+ * 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 { getClientManager } from './client.js'
+import type { ChainName } from './types.js'
+
+const ERC20_META_ABI = [
+  parseAbiItem('function decimals() view returns (uint8)'),
+  parseAbiItem('function symbol() view returns (string)')
+]
+
+const abiCache = new Map<string, { abi: Abi; source: 'verified' | 'guessed'; proxy?: string; name?: string }>()
+const labelCache = new Map<string, string | undefined>()
+const metaCache = new Map<string, { symbol?: string; decimals?: number }>()
+
+export async function loadAbi(chain: ChainName, address: string) {
+  const key = `${chain}:${address.toLowerCase()}`
+  const cached = abiCache.get(key)
+  if (cached) return cached
+
+  const clientManager = getClientManager()
+  const client = clientManager.getClient(chain)
+  const etherscanApiKey = clientManager.getConfig().etherscanApiKey
+
+  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) }))
+  }
+
+  const result = await whatsabi.autoload(address as Address, {
+    provider: client,
+    abiLoader: new whatsabi.loaders.MultiABILoader(loaders),
+    signatureLookup: new whatsabi.loaders.OpenChainSignatureLookup(),
+    followProxies: true
+  })
+
+  // Bytecode-guessed ABIs carry no argument names; verified ones do.
+  const source = result.abi.some((item) => item.type === 'function' && item.inputs?.some((i) => i.name)) ? 'verified' : 'guessed'
+  const loaded = {
+    abi: result.abi as Abi,
+    source: source as 'verified' | 'guessed',
+    proxy: result.address !== address ? result.address : undefined,
+    name: result.contractResult?.name ?? undefined
+  }
+  abiCache.set(key, loaded)
+  return loaded
+}
+
+export async function tokenMeta(chain: ChainName, token: string) {
+  const key = `${chain}:${token.toLowerCase()}`
+  const cached = metaCache.get(key)
+  if (cached) return cached
+
+  const client = getClientManager().getClient(chain)
+  const [decimals, symbol] = await client.multicall({
+    contracts: [
+      { address: token as Address, abi: ERC20_META_ABI, functionName: 'decimals' },
+      { address: token as Address, abi: ERC20_META_ABI, functionName: 'symbol' }
+    ],
+    ...(chain === 'localhost' && { deployless: true })
+  })
+
+  const meta = {
+    decimals: decimals.status === 'success' ? Number(decimals.result) : undefined,
+    symbol: symbol.status === 'success' ? (symbol.result as string) : undefined
+  }
+  metaCache.set(key, meta)
+  return meta
+}
+
+/**
+ * Human label for an address: token symbol first (more recognisable than the contract
+ * name — "USDC" beats "FiatTokenProxy"), then the verified contract name. EOAs get none,
+ * and the bytecode check keeps us from asking explorers about plain wallets.
+ */
+export async function addressLabel(chain: ChainName, address: string): Promise<string | undefined> {
+  const key = `${chain}:${address.toLowerCase()}`
+  if (labelCache.has(key)) return labelCache.get(key)
+
+  let label: string | undefined
+  try {
+    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
+    }
+  } catch {
+    // Unknown address — show it bare rather than failing the preview.
+  }
+
+  labelCache.set(key, label)
+  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/clear-signing.ts

@@ -0,0 +1,206 @@
+import { createRequire } from 'node:module'
+import { gunzipSync } from 'node:zlib'
+import { formatUnits, getAddress, isAddress } from 'viem'
+import { addressLabel, tokenMeta, UNLIMITED_THRESHOLD } from './chain-meta.js'
+import { getClientManager } from './client.js'
+import type { ChainName } from './types.js'
+
+/**
+ * Clear signing from the Ledger ERC-7730 registry: for a known contract and selector it
+ * says what the transaction *means* ("Swap", "Approve spending") and labels each field the
+ * way the protocol intends, instead of showing raw ABI argument names.
+ *
+ * The index is built from the registry by scripts/build-erc7730-index.mjs.
+ */
+
+interface IndexField {
+  // A handful of registry descriptors omit these, so nothing here is guaranteed.
+  label?: string
+  path?: string
+  format?: string
+  /** tokenAmount: `tokenPath` points at the field holding the token address. */
+  params?: { tokenPath?: string; tokenAddress?: string; [k: string]: unknown }
+}
+
+interface IndexSelector {
+  name: string
+  intent: string
+  /** Full signature, needed to ABI-decode the calldata these paths address. */
+  signature?: string
+  fields: IndexField[]
+}
+
+interface IndexEntry {
+  protocol: string
+  chainIds: number[]
+  selectors: Record<string, IndexSelector>
+}
+
+export interface ClearSigningField {
+  label: string
+  format: string
+  value: string
+  address?: string
+  name?: string
+}
+
+export interface ClearSigningInfo {
+  protocol: string
+  intent: string
+  functionName: string
+  fields: ClearSigningField[]
+}
+
+// Prettier names for registry directory slugs; unknown ones read fine as-is.
+const PROTOCOL_LABELS: Record<string, string> = {
+  lifi: 'LI.FI',
+  '1inch': '1inch',
+  uniswap: 'Uniswap',
+  paraswap: 'ParaSwap',
+  cowswap: 'CoW Swap',
+  '0x': '0x Protocol',
+  aave: 'Aave',
+  morpho: 'Morpho',
+  safe: 'Safe',
+  lido: 'Lido',
+  eigenlayer: 'EigenLayer',
+  ens: 'ENS'
+}
+
+const require = createRequire(import.meta.url)
+let index: Record<string, IndexEntry> | undefined
+
+/** Loaded on first use: ~1.5MB of JSON, shipped gzipped at ~60KB. */
+function registry(): Record<string, IndexEntry> {
+  if (!index) {
+    try {
+      const path = require.resolve('./erc7730-index.json.gz')
+      index = JSON.parse(gunzipSync(require('node:fs').readFileSync(path)).toString())
+    } catch {
+      index = {}
+    }
+  }
+  return index as Record<string, IndexEntry>
+}
+
+export function protocolLabel(slug: string): string {
+  return PROTOCOL_LABELS[slug] ?? slug
+}
+
+/** Resolve a registry path ("params.amountIn", "#.to", "[0].value") against decoded args. */
+function getByPath(root: unknown, path: string): unknown {
+  let current: unknown = root
+  for (const part of path.replace(/^[#@]\./, '').split('.')) {
+    if (current == null) return undefined
+    const arrayIndex = part.match(/^\[(\d*)\]$/)
+    if (arrayIndex) {
+      current = Array.isArray(current) ? current[arrayIndex[1] === '' ? 0 : Number(arrayIndex[1])] : undefined
+    } else {
+      current = (current as Record<string, unknown>)[part]
+    }
+  }
+  return current
+}
+
+interface TxContext {
+  to: string
+  value?: string
+  from?: string
+}
+
+function resolvePath(root: unknown, tx: TxContext, path: string): unknown {
+  if (path.startsWith('@.')) {
+    if (path.slice(2) === 'to') return tx.to
+    if (path.slice(2) === 'value') return tx.value
+    if (path.slice(2) === 'from') return tx.from
+    return undefined
+  }
+  return getByPath(root, path)
+}
+
+async function formatField(chain: ChainName, field: IndexField, root: unknown, tx: TxContext): Promise<ClearSigningField> {
+  // A missing format with a token reference still means an amount.
+  const format = field.format ?? (field.params?.tokenPath || field.params?.tokenAddress ? 'tokenAmount' : 'raw')
+  const label = field.label ?? field.path ?? format
+  const raw = field.path ? resolvePath(root, tx, field.path) : undefined
+  const out: ClearSigningField = { label, format, value: '' }
+
+  // Unresolved: show the descriptor's path rather than an empty row.
+  if (raw == null) {
+    out.value = field.path ?? ''
+    return out
+  }
+
+  switch (format) {
+    case 'tokenAmount':
+    case 'amount': {
+      const amount = typeof raw === 'bigint' ? raw : BigInt(raw as string | number)
+      const token =
+        field.params?.tokenAddress ?? (field.params?.tokenPath ? resolvePath(root, tx, field.params.tokenPath) : undefined)
+
+      const meta =
+        typeof token === 'string' && isAddress(token)
+          ? await tokenMeta(chain, token).catch(() => ({ symbol: undefined, decimals: undefined }))
+          : { symbol: undefined, decimals: undefined }
+
+      const symbol = meta.symbol ? ` ${meta.symbol}` : ''
+      out.value = amount > UNLIMITED_THRESHOLD ? `Unlimited${symbol}` : `${formatUnits(amount, meta.decimals ?? 18)}${symbol}`
+      return out
+    }
+
+    case 'addressName':
+    case 'address':
+    case 'tokenName': {
+      if (!isAddress(raw as string)) {
+        out.value = String(raw)
+        return out
+      }
+      const address = getAddress(raw as string)
+      const name = registry()[address.toLowerCase()]?.protocol
+      out.address = address
+      out.name = name ? protocolLabel(name) : await addressLabel(chain, address).catch(() => undefined)
+      out.value = out.name ?? address
+      return out
+    }
+
+    default:
+      out.value = typeof raw === 'bigint' ? raw.toString() : String(raw)
+      return out
+  }
+}
+
+/** Registry entry for a contract, if it is listed for this chain. */
+export function lookupContract(chain: ChainName, address: string): IndexEntry | undefined {
+  const entry = registry()[address.toLowerCase()]
+  if (!entry) return undefined
+  const chainId = getClientManager().getChainId(chain)
+  return entry.chainIds.includes(chainId) ? entry : undefined
+}
+
+/**
+ * Clear-signing info for a transaction, or null when the contract/selector is unlisted.
+ * `decodedArgs` is supplied by the caller, which has already decoded the calldata against
+ * the contract's real ABI — the registry's own signature is only a fallback for naming.
+ */
+export async function resolveClearSigning(
+  chain: ChainName,
+  tx: TxContext & { data?: string },
+  decodedArgs: Record<string, unknown>
+): Promise<ClearSigningInfo | null> {
+  if (!tx.data || tx.data.length < 10) return null
+
+  const entry = lookupContract(chain, tx.to)
+  const format = entry?.selectors[tx.data.slice(0, 10).toLowerCase()]
+  if (!entry || !format) return null
+
+  // Fields with neither a path nor a label carry nothing a signer could read.
+  const usable = format.fields.filter((field) => field.path || field.label)
+  const fields = await Promise.all(usable.map((field) => formatField(chain, field, decodedArgs, tx)))
+
+  return {
+    protocol: protocolLabel(entry.protocol),
+    intent: format.intent,
+    functionName: format.name,
+    fields
+  }
+}

package/src/client.ts

@@ -33,7 +33,8 @@ function getRpcUrl(chainName: string, config: Config): string {
 
     base: config.alchemyApiKey
       ? `https://base-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : 'https://base-rpc.publicnode.com',
+      // publicnode refuses receipts and anything else it calls an archive request
+      : 'https://mainnet.base.org',
 
     arbitrum: config.alchemyApiKey
       ? `https://arb-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
@@ -45,7 +46,8 @@ function getRpcUrl(chainName: string, config: Config): string {
       ? `https://polygon-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
       : config.infuraApiKey
         ? `https://polygon-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://polygon-rpc.com',
+        // polygon-rpc.com now answers 401 "API key disabled" to anonymous callers
+        : 'https://polygon-bor-rpc.publicnode.com',
 
     optimism: config.alchemyApiKey
       ? `https://opt-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`

package/src/http-server.ts

@@ -0,0 +1,94 @@
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { timingSafeEqual } from 'node:crypto'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+/**
+ * Serve the MCP over HTTP instead of stdio, so the server can live somewhere other than the
+ * machine running the agent. Only worth doing alongside WalletConnect: a hosted server has
+ * no browser to open, so a phone wallet is the only way it can have anything signed.
+ *
+ * Stateless — a server per request — because every tool here is a one-shot call and the
+ * signing state lives in the WalletConnect session, not in the transport.
+ */
+
+const DEFAULT_PORT = 3457
+
+function unauthorized(res: ServerResponse) {
+  res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' })
+  res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'Unauthorized' } }))
+}
+
+/** Constant-time compare, so the token cannot be guessed a character at a time. */
+function tokenMatches(presented: string, expected: string): boolean {
+  const a = Buffer.from(presented)
+  const b = Buffer.from(expected)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+export interface HttpServerOptions {
+  port?: number
+  host?: string
+  token?: string
+  createMcpServer: () => McpServer
+}
+
+export async function startHttpServer(options: HttpServerOptions): Promise<{ url: string; port: number }> {
+  const port = options.port ?? Number(process.env.MCP_HTTP_PORT) ?? DEFAULT_PORT
+  const host = options.host ?? process.env.HOST ?? (process.env.MCP_HTTP_HOST ? process.env.MCP_HTTP_HOST : '0.0.0.0')
+  const token = options.token ?? process.env.MCP_TOKEN
+
+  // A reachable MCP server with a paired phone can push signing prompts at that phone. It
+  // never runs without a token.
+  if (!token) {
+    throw new Error('MCP_TOKEN is required to serve MCP over HTTP — anyone reaching the URL could request signatures')
+  }
+
+  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ status: 'ok' }))
+      return
+    }
+
+    if (!req.url?.startsWith('/mcp')) {
+      res.writeHead(404).end()
+      return
+    }
+
+    const presented = req.headers.authorization?.replace(/^Bearer /i, '') ?? ''
+    if (!tokenMatches(presented, token)) {
+      unauthorized(res)
+      return
+    }
+
+    const mcp = options.createMcpServer()
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
+
+    res.on('close', () => {
+      transport.close().catch(() => {})
+      mcp.close().catch(() => {})
+    })
+
+    try {
+      await mcp.connect(transport)
+      await transport.handleRequest(req, res)
+    } catch (error) {
+      console.error('[MCP] Request failed:', error)
+      if (!res.headersSent) {
+        res.writeHead(500, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' } }))
+      }
+    }
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.removeListener('error', reject)
+      resolve()
+    })
+  })
+
+  return { url: `http://${host}:${port}/mcp`, port }
+}

package/src/index.ts

@@ -7,6 +7,7 @@ import { initializeClientManager } from "./client.js";
 import { registerAllTools } from "./tools/index.js";
 import { parseCommandLineArgs } from "./utils.js";
 import { getWalletClient } from "./wallet-client.js";
+import { startHttpServer } from "./http-server.js";
 
 // Parse configuration
 const config = parseCommandLineArgs();
@@ -26,6 +27,8 @@ OPTIONS:
   --alchemy-api-key <key>       Alchemy API key (for enhanced RPC)
   --infura-api-key <key>        Infura API key (for alternative RPC)
   --hypersync-api-key <key>     Hypersync API key (for fast event queries)
+  --walletconnect-project-id <id>
+                                WalletConnect project id, to sign from a phone
   --custom-rpc <json>           Custom RPC URLs as JSON object
                                 Example: '{"mainnet":"https://...", "base":"https://..."}'
 
@@ -34,6 +37,11 @@ ENVIRONMENT VARIABLES:
   ALCHEMY_API_KEY               Alternative to --alchemy-api-key
   INFURA_API_KEY                Alternative to --infura-api-key
   HYPERSYNC_API_KEY             Alternative to --hypersync-api-key
+  WALLETCONNECT_PROJECT_ID      Alternative to --walletconnect-project-id
+  MCP_HTTP_PORT                 Serve MCP over HTTP on this port instead of stdio
+  MCP_TOKEN                     Bearer token required by the HTTP transport
+  UPSTASH_REDIS_REST_URL        Keep WalletConnect sessions in Redis, not on disk
+  UPSTASH_REDIS_REST_TOKEN
   WALLET_SERVER_URL             URL of a hosted wallet relay (omit to run one locally)
   WALLET_TOKEN                  Shared pairing token for the wallet relay
 
@@ -70,6 +78,9 @@ if (config.alchemyApiKey) {
 if (config.infuraApiKey) {
   console.error("[MCP] Infura API key configured");
 }
+if (config.walletConnectProjectId) {
+  console.error("[MCP] WalletConnect project id configured — phone signing available");
+}
 if (config.customRpcUrls) {
   console.error("[MCP] Custom RPC URLs:", Object.keys(config.customRpcUrls));
 }
@@ -77,21 +88,26 @@ if (config.customRpcUrls) {
 // Initialize client manager
 initializeClientManager(config);
 
-// Create MCP server instance
-const server = new McpServer({
-  name: "web3-tools-mcp",
-  version: packageJson.version,
-});
+function createMcpServer() {
+  const server = new McpServer({
+    name: "web3-tools-mcp",
+    version: packageJson.version,
+  });
+  registerAllTools(server);
+  return server;
+}
 
-// Register all tools
-registerAllTools(server);
+// Serving over HTTP means there is no browser on this machine to open, so the wallet relay
+// is skipped and signing goes to a paired phone over WalletConnect.
+const httpMode = Boolean(process.env.MCP_HTTP_PORT);
 
-// Connect to the wallet relay (hosted when WALLET_SERVER_URL is set, embedded otherwise)
 const wallet = getWalletClient();
-const walletReady = wallet.connect().catch((error) => {
-  console.error("[MCP] Wallet relay unavailable:", error.message);
-  console.error("[MCP] Transaction signing features will not be available");
-});
+const walletReady = httpMode
+  ? Promise.resolve()
+  : wallet.connect().catch((error) => {
+      console.error("[MCP] Wallet relay unavailable:", error.message);
+      console.error("[MCP] Transaction signing features will not be available");
+    });
 
 // The wallet relay's listening socket keeps the event loop alive, so this process would
 // outlive the client that spawned it and go on holding its port. Leave when the client does.
@@ -111,8 +127,17 @@ process.on("SIGINT", () => shutdown("SIGINT"));
 
 // Start server
 async function main() {
+  if (httpMode) {
+    const { url } = await startHttpServer({ createMcpServer });
+    console.error(`Web3 Tools MCP Server listening on ${url}`);
+    if (!config.walletConnectProjectId) {
+      console.error("[MCP] No WalletConnect project id — a hosted server has no way to sign transactions");
+    }
+    return;
+  }
+
   const transport = new StdioServerTransport();
-  await server.connect(transport);
+  await createMcpServer().connect(transport);
   console.error("Web3 Tools MCP Server running on stdio");
   // The relay may still be picking a free port, and its URL carries the pairing token.
   await walletReady;

package/src/kv-storage.ts

@@ -0,0 +1,83 @@
+/**
+ * WalletConnect session storage backed by Upstash Redis.
+ *
+ * The default store is a file, which is fine on a laptop and useless on a free-tier host:
+ * the filesystem is ephemeral, so every sleep/wake would lose the pairing and ask for the
+ * QR again. Everything lives in one Redis hash, which is exactly the shape WalletConnect's
+ * key-value interface expects.
+ *
+ * Uses the REST API over plain fetch — no Redis client, no TCP, works anywhere.
+ */
+
+const HASH_KEY = 'web3-tools-mcp:walletconnect'
+
+export interface KeyValueStorage {
+  getKeys(): Promise<string[]>
+  getEntries<T = unknown>(): Promise<[string, T][]>
+  getItem<T = unknown>(key: string): Promise<T | undefined>
+  setItem<T = unknown>(key: string, value: T): Promise<void>
+  removeItem(key: string): Promise<void>
+}
+
+class RedisKeyValueStorage implements KeyValueStorage {
+  constructor(
+    private url: string,
+    private token: string
+  ) {}
+
+  /** Upstash takes a command as a JSON array and answers `{ result }`. */
+  private async command<T>(...parts: (string | number)[]): Promise<T> {
+    const response = await fetch(this.url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
+      body: JSON.stringify(parts)
+    })
+
+    if (!response.ok) {
+      throw new Error(`Upstash request failed (${response.status}): ${await response.text()}`)
+    }
+
+    return ((await response.json()) as { result: T }).result
+  }
+
+  async getKeys(): Promise<string[]> {
+    return (await this.command<string[]>('HKEYS', HASH_KEY)) ?? []
+  }
+
+  async getEntries<T = unknown>(): Promise<[string, T][]> {
+    // HGETALL comes back as a flat [field, value, field, value, …] array.
+    const flat = (await this.command<string[]>('HGETALL', HASH_KEY)) ?? []
+    const entries: [string, T][] = []
+    for (let i = 0; i < flat.length; i += 2) {
+      const key = flat[i]
+      const value = flat[i + 1]
+      if (key === undefined || value === undefined) continue
+      entries.push([key, JSON.parse(value) as T])
+    }
+    return entries
+  }
+
+  async getItem<T = unknown>(key: string): Promise<T | undefined> {
+    const value = await this.command<string | null>('HGET', HASH_KEY, key)
+    return value == null ? undefined : (JSON.parse(value) as T)
+  }
+
+  async setItem<T = unknown>(key: string, value: T): Promise<void> {
+    await this.command('HSET', HASH_KEY, key, JSON.stringify(value))
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await this.command('HDEL', HASH_KEY, key)
+  }
+}
+
+/**
+ * Redis-backed storage when Upstash is configured, otherwise nothing — the caller falls
+ * back to WalletConnect's own file store.
+ */
+export function getKeyValueStorage(): KeyValueStorage | undefined {
+  const url = process.env.UPSTASH_REDIS_REST_URL
+  const token = process.env.UPSTASH_REDIS_REST_TOKEN
+  if (!url || !token) return undefined
+  return new RedisKeyValueStorage(url, token)
+}