web3-tools-mcp 3.0.0 → 3.2.0

package/src/chain-meta.ts

@@ -8,15 +8,21 @@ import { whatsabi } from '@shazow/whatsabi'
 import { type Abi, type Address, parseAbiItem } from 'viem'
 import { getClientManager } from './client.js'
 import type { ChainName } from './types.js'
+import { TtlCache } from './utils.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 }>()
+// An hour covers a session's repeats while still noticing an upgraded proxy.
+const TTL_MS = 60 * 60 * 1000
+const abiCache = new TtlCache<{ abi: Abi; source: 'verified' | 'guessed'; proxy?: string; name?: string }>(200, TTL_MS)
+const labelCache = new TtlCache<{ label?: string }>(1000, TTL_MS)
+const metaCache = new TtlCache<{ symbol?: string; decimals?: number }>(1000, TTL_MS)
+
+/** A local node is reset and redeployed at will, so nothing learned from it stays true. */
+const cacheable = (chain: ChainName) => chain !== 'localhost'
 
 export async function loadAbi(chain: ChainName, address: string) {
   const key = `${chain}:${address.toLowerCase()}`
@@ -49,7 +55,7 @@ export async function loadAbi(chain: ChainName, address: string) {
     proxy: result.address !== address ? result.address : undefined,
     name: result.contractResult?.name ?? undefined
   }
-  abiCache.set(key, loaded)
+  if (cacheable(chain)) abiCache.set(key, loaded)
   return loaded
 }
 
@@ -71,7 +77,8 @@ export async function tokenMeta(chain: ChainName, token: string) {
     decimals: decimals.status === 'success' ? Number(decimals.result) : undefined,
     symbol: symbol.status === 'success' ? (symbol.result as string) : undefined
   }
-  metaCache.set(key, meta)
+  // A failed call may be a flaky RPC rather than a token without that method.
+  if (cacheable(chain) && decimals.status === 'success' && symbol.status === 'success') metaCache.set(key, meta)
   return meta
 }
 
@@ -82,7 +89,8 @@ export async function tokenMeta(chain: ChainName, token: string) {
  */
 export async function addressLabel(chain: ChainName, address: string): Promise<string | undefined> {
   const key = `${chain}:${address.toLowerCase()}`
-  if (labelCache.has(key)) return labelCache.get(key)
+  const cached = labelCache.get(key)
+  if (cached) return cached.label
 
   let label: string | undefined
   try {
@@ -95,9 +103,10 @@ export async function addressLabel(chain: ChainName, address: string): Promise<s
     }
   } catch {
     // Unknown address — show it bare rather than failing the preview.
+    return undefined
   }
 
-  labelCache.set(key, label)
+  if (cacheable(chain)) labelCache.set(key, { label })
   return label
 }
 

package/src/chains.ts

@@ -1,16 +1,23 @@
 import type { Chain } from 'viem'
 import {
   arbitrum,
+  arc,
   avalanche,
   base,
   bsc,
+  celo,
   gnosis,
+  hyperEvm,
+  ink,
   linea,
   localhost,
   mainnet,
+  mantle,
+  monad,
   optimism,
+  plasma,
   polygon,
-  sonic,
+  robinhood,
   unichain,
   zksync
 } from 'viem/chains'
@@ -25,39 +32,41 @@ 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. */
+  /** False where Alchemy serves the RPC but not its token API, which `get_portfolio` needs. */
+  alchemyTokenApi?: false
+  /** Used when no Alchemy key is configured, or Alchemy has no endpoint. */
   fallback: string
   /** Block explorer domain, for links. Absent where there is nothing to link to. */
   explorer?: string
   hypersync?: string
+  /** DefiLlama's two names for the chain: the prefix of a coin id, and the `chain` of a yield pool. */
+  llama?: { coins: string; yields: 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'
+    hypersync: 'https://eth.hypersync.xyz',
+    llama: { coins: 'ethereum', yields: 'Ethereum' }
   },
   arbitrum: {
     chain: arbitrum,
     alchemy: 'arb-mainnet',
-    infura: 'arbitrum-mainnet',
     fallback: 'https://arb1.arbitrum.io/rpc',
     explorer: 'arbiscan.io',
-    hypersync: 'https://arbitrum.hypersync.xyz'
+    hypersync: 'https://arbitrum.hypersync.xyz',
+    llama: { coins: 'arbitrum', yields: 'Arbitrum' }
   },
   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'
+    hypersync: 'https://avalanche.hypersync.xyz',
+    llama: { coins: 'avax', yields: 'Avalanche' }
   },
   base: {
     chain: base,
@@ -65,70 +74,131 @@ const TABLE = {
     // publicnode refuses receipts and anything else it calls an archive request
     fallback: 'https://mainnet.base.org',
     explorer: 'basescan.org',
-    hypersync: 'https://base.hypersync.xyz'
+    hypersync: 'https://base.hypersync.xyz',
+    llama: { coins: 'base', yields: 'Base' }
   },
   bnb: {
     chain: bsc,
     alchemy: 'bnb-mainnet',
-    infura: 'bsc-mainnet',
     fallback: 'https://bsc-dataseed.bnbchain.org',
     explorer: 'bscscan.com',
-    hypersync: 'https://bsc.hypersync.xyz'
+    hypersync: 'https://bsc.hypersync.xyz',
+    llama: { coins: 'bsc', yields: 'BSC' }
   },
   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'
+    hypersync: 'https://gnosis.hypersync.xyz',
+    llama: { coins: 'xdai', yields: 'Gnosis' }
   },
   optimism: {
     chain: optimism,
     alchemy: 'opt-mainnet',
-    infura: 'optimism-mainnet',
     fallback: 'https://mainnet.optimism.io',
     explorer: 'optimistic.etherscan.io',
-    hypersync: 'https://optimism.hypersync.xyz'
+    hypersync: 'https://optimism.hypersync.xyz',
+    llama: { coins: 'optimism', yields: 'OP Mainnet' }
   },
   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'
+    hypersync: 'https://polygon.hypersync.xyz',
+    llama: { coins: 'polygon', yields: 'Polygon' }
   },
   zksync: {
     chain: zksync,
     alchemy: 'zksync-mainnet',
-    infura: 'zksync-mainnet',
     fallback: 'https://mainnet.era.zksync.io',
     explorer: 'era.zksync.network',
-    hypersync: 'https://zksync.hypersync.xyz'
+    hypersync: 'https://zksync.hypersync.xyz',
+    llama: { coins: 'era', yields: 'ZKsync Era' }
   },
   linea: {
     chain: linea,
     alchemy: 'linea-mainnet',
-    infura: 'linea-mainnet',
     fallback: 'https://rpc.linea.build',
     explorer: 'lineascan.build',
-    hypersync: 'https://linea.hypersync.xyz'
+    hypersync: 'https://linea.hypersync.xyz',
+    llama: { coins: 'linea', yields: 'Linea' }
   },
   unichain: {
     chain: unichain,
     alchemy: 'unichain-mainnet',
-    infura: 'unichain-mainnet',
     fallback: 'https://mainnet.unichain.org',
     explorer: 'uniscan.xyz',
-    hypersync: 'https://unichain.hypersync.xyz'
+    hypersync: 'https://unichain.hypersync.xyz',
+    llama: { coins: 'unichain', yields: 'Unichain' }
+  },
+  monad: {
+    chain: monad,
+    alchemy: 'monad-mainnet',
+    fallback: 'https://rpc.monad.xyz',
+    explorer: 'monadscan.com',
+    hypersync: 'https://monad.hypersync.xyz',
+    llama: { coins: 'monad', yields: 'Monad' }
+  },
+  robinhood: {
+    chain: robinhood,
+    alchemy: 'robinhood-mainnet',
+    fallback: 'https://rpc.mainnet.chain.robinhood.com',
+    explorer: 'robinhoodchain.blockscout.com',
+    hypersync: 'https://robinhood.hypersync.xyz',
+    llama: { coins: 'robinhood', yields: 'Robinhood Chain' }
+  },
+  arc: {
+    chain: arc,
+    alchemy: 'arc-mainnet',
+    fallback: 'https://rpc.mainnet.arc.io',
+    explorer: 'explorer.arc.io',
+    hypersync: 'https://arc.hypersync.xyz',
+    llama: { coins: 'arc', yields: 'Arc' }
+  },
+  plasma: {
+    chain: plasma,
+    alchemy: 'plasma-mainnet',
+    alchemyTokenApi: false,
+    fallback: 'https://rpc.plasma.to',
+    explorer: 'plasmascan.to',
+    hypersync: 'https://plasma.hypersync.xyz',
+    llama: { coins: 'plasma', yields: 'Plasma' }
+  },
+  ink: {
+    chain: ink,
+    alchemy: 'ink-mainnet',
+    fallback: 'https://rpc-gel.inkonchain.com',
+    explorer: 'explorer.inkonchain.com',
+    hypersync: 'https://ink.hypersync.xyz',
+    llama: { coins: 'ink', yields: 'Ink' }
+  },
+  mantle: {
+    chain: mantle,
+    alchemy: 'mantle-mainnet',
+    alchemyTokenApi: false,
+    fallback: 'https://rpc.mantle.xyz',
+    explorer: 'mantlescan.xyz',
+    hypersync: 'https://mantle.hypersync.xyz',
+    llama: { coins: 'mantle', yields: 'Mantle' }
+  },
+  celo: {
+    chain: celo,
+    alchemy: 'celo-mainnet',
+    fallback: 'https://forno.celo.org',
+    explorer: 'celoscan.io',
+    hypersync: 'https://celo.hypersync.xyz',
+    llama: { coins: 'celo', yields: 'Celo' }
+  },
+  hyperevm: {
+    chain: hyperEvm,
+    alchemy: 'hyperliquid-mainnet',
+    fallback: 'https://rpc.hyperliquid.xyz/evm',
+    explorer: 'hyperevmscan.io',
+    hypersync: 'https://hyperliquid.hypersync.xyz',
+    llama: { coins: 'hyperliquid', yields: 'Hyperliquid L1' }
   },
   localhost: {
     chain: localhost,

package/src/clear-signing.ts

@@ -138,13 +138,19 @@ async function formatField(chain: ChainName, field: IndexField, root: unknown, t
       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}`
+      const tokenAddress = typeof token === 'string' && isAddress(token) ? getAddress(token) : undefined
+      const meta = tokenAddress
+        ? await tokenMeta(chain, tokenAddress).catch(() => ({ symbol: undefined, decimals: undefined }))
+        : { symbol: undefined, decimals: undefined }
+      // `amount` is the native currency, which always has 18 decimals.
+      const decimals = meta.decimals ?? (format === 'amount' && !tokenAddress ? 18 : undefined)
+
+      // symbol() is whatever the token contract says it is, so the address always goes with it.
+      const symbol = `${meta.symbol ? ` ${meta.symbol}` : ''}${tokenAddress ? ` (${tokenAddress})` : ''}`
+      if (tokenAddress) out.address = tokenAddress
+      if (amount > UNLIMITED_THRESHOLD) out.value = `Unlimited${symbol}`
+      else if (decimals === undefined) out.value = `${amount}${symbol} (decimals unknown)`
+      else out.value = `${formatUnits(amount, decimals)}${symbol}`
       return out
     }
 
@@ -156,10 +162,10 @@ async function formatField(chain: ChainName, field: IndexField, root: unknown, t
         return out
       }
       const address = getAddress(raw as string)
-      const name = registry()[address.toLowerCase()]?.protocol
+      const name = lookupContract(chain, address)?.protocol
       out.address = address
       out.name = name ? protocolLabel(name) : await addressLabel(chain, address).catch(() => undefined)
-      out.value = out.name ?? address
+      out.value = out.name ? `${out.name} (${address})` : address
       return out
     }
 

package/src/client.ts

@@ -4,14 +4,13 @@ import type { Config } from './types.js'
 
 export { SUPPORTED_CHAINS } from './chains.js'
 
-/** Custom URL first, then whichever provider key is configured, then the public endpoint. */
+/** Custom URL first, then Alchemy when a key is configured, then the public endpoint. */
 function getRpcUrl(chainName: ChainName, config: Config): string {
   const custom = config.customRpcUrls?.[chainName]
   if (custom) return custom
 
-  const { alchemy, infura, fallback } = CHAINS[chainName]
+  const { alchemy, fallback } = CHAINS[chainName]
   if (alchemy && config.alchemyApiKey) return `https://${alchemy}.g.alchemy.com/v2/${config.alchemyApiKey}`
-  if (infura && config.infuraApiKey) return `https://${infura}.infura.io/v3/${config.infuraApiKey}`
   return fallback
 }
 

package/src/http-server.ts

@@ -4,7 +4,7 @@ import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from '@modelconte
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import express, { type Express } from 'express'
-import type { WalletRelay } from 'web3-wallet-relay'
+import { SIGN_PATH, type WalletRelay } from 'web3-wallet-relay'
 import { HOSTED } from './hosted.js'
 import { SingleUserOAuthProvider } from './oauth.js'
 
@@ -56,7 +56,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
     )
   }
 
-  const port = options.port ?? Number(process.env.MCP_HTTP_PORT) ?? DEFAULT_PORT
+  const port = options.port ?? (Number(process.env.MCP_HTTP_PORT) || DEFAULT_PORT)
   const host = options.host ?? process.env.MCP_HTTP_HOST ?? '0.0.0.0'
   const token = options.token ?? process.env.MCP_TOKEN
 
@@ -72,6 +72,11 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
   const provider = options.provider ?? new SingleUserOAuthProvider(token as string)
 
   const app = express()
+  // The auth routes rate-limit per req.ip, which behind a platform proxy is the proxy's own
+  // address — every caller would share one bucket. Only trust as many hops as are really
+  // in front, or anyone could pick their own bucket with a forged X-Forwarded-For.
+  const proxyHops = Number(process.env.MCP_TRUST_PROXY)
+  if (proxyHops) app.set('trust proxy', proxyHops)
   app.use(express.json())
   // The login form posts a token, so the authorize route needs form bodies too.
   app.use(express.urlencoded({ extended: false }))
@@ -124,18 +129,18 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
   })
 
   const server = await new Promise<ReturnType<typeof app.listen>>((resolve, reject) => {
-    const listening = app.listen(port, host, () => resolve(listening))
-    listening.once('error', reject)
+    // Express 5 hands a listen error to this callback rather than leaving it to 'error'.
+    const listening = app.listen(port, host, (error?: Error) => (error ? reject(error) : resolve(listening)))
   })
 
   // The signing page rides on this same server, so a hosted deployment can offer browser
   // signing without a second service: one platform port serves both /mcp and the page.
   // Mounted last, so the routes above keep their paths — the relay only claims what is
-  // left, which is the static page at the root.
+  // left, which is the static page at /sign/.
   let walletUrl: string | undefined
   if (options.walletRelay) {
     options.walletRelay.attach(server, (relayApp) => app.use(relayApp))
-    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.signerToken}`
+    walletUrl = `${publicUrl.replace(/\/$/, '')}${SIGN_PATH}#t=${options.walletRelay.signerToken}`
   }
 
   return { url: `${publicUrl.replace(/\/$/, '')}/mcp`, port: (server.address() as { port: number }).port, walletUrl }

package/src/index.ts

@@ -27,7 +27,6 @@ OPTIONS:
   --help, -h                    Show this help message
   --etherscan-api-key <key>     Etherscan API key (for contract ABI retrieval)
   --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
@@ -37,11 +36,12 @@ OPTIONS:
 ENVIRONMENT VARIABLES:
   ETHERSCAN_API_KEY             Alternative to --etherscan-api-key
   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
   CUSTOM_RPC                    Alternative to --custom-rpc
   MCP_HTTP_PORT                 Serve MCP over HTTP on this port instead of stdio
+  MCP_HTTP_HOST                 Interface the HTTP server binds to (default: 0.0.0.0)
+  MCP_TRUST_PROXY               Proxy hops in front of the server, e.g. 1 on Fly/Render
   MCP_HOSTED                    Apply the hosted guards without the CLI (library use)
   MCP_TOKEN                     Bearer token required by the HTTP transport
   MCP_PUBLIC_URL                Public URL of this server, advertised in OAuth metadata
@@ -82,9 +82,6 @@ if (config.etherscanApiKey) {
 if (config.alchemyApiKey) {
   console.error('[MCP] Alchemy API key configured')
 }
-if (config.infuraApiKey) {
-  console.error('[MCP] Infura API key configured')
-}
 if (config.walletConnectProjectId) {
   console.error('[MCP] WalletConnect project id configured — phone signing available')
 }
@@ -153,7 +150,9 @@ async function main() {
     await wallet.connect().catch((error) => {
       console.error('[MCP] Could not join the wallet relay:', error.message)
     })
-    if (walletUrl) console.error(`Wallet interface available at ${walletUrl}`)
+    // Without its #t= token: platform logs are read by more people than may sign. The full
+    // link comes from wallet_status, which already requires MCP_TOKEN.
+    if (walletUrl) console.error(`Wallet interface available at ${walletUrl.split('#')[0]} (link with token via wallet_status)`)
 
     if (!config.walletConnectProjectId) {
       console.error('[MCP] No WalletConnect project id — phone signing is unavailable on this server')

package/src/kv-storage.ts

@@ -15,7 +15,8 @@ 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>
+  /** `ttl` (seconds) expires just this field, where the backend can. */
+  setItem<T = unknown>(key: string, value: T, ttl?: number): Promise<void>
   removeItem(key: string): Promise<void>
 }
 
@@ -30,7 +31,8 @@ class RedisKeyValueStorage implements KeyValueStorage {
     const response = await fetch(this.url, {
       method: 'POST',
       headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
-      body: JSON.stringify(parts)
+      body: JSON.stringify(parts),
+      signal: AbortSignal.timeout(5000)
     })
 
     if (!response.ok) {
@@ -62,8 +64,9 @@ class RedisKeyValueStorage implements KeyValueStorage {
     return value == null ? undefined : (JSON.parse(value) as T)
   }
 
-  async setItem<T = unknown>(key: string, value: T): Promise<void> {
+  async setItem<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
     await this.command('HSET', HASH_KEY, key, JSON.stringify(value))
+    if (ttl) await this.command('HEXPIRE', HASH_KEY, Math.ceil(ttl), 'FIELDS', 1, key)
   }
 
   async removeItem(key: string): Promise<void> {