web3-tools-mcp 1.5.0 → 2.0.0

package/src/utils.ts

@@ -1,6 +1,6 @@
 import type { AbiParameter } from 'viem'
-import type { ToolResult } from './types.js'
-import { z } from 'zod'
+import type { z } from 'zod'
+import type { Config, ToolResult } from './types.js'
 
 // Create tool helper
 export function createTool<T extends z.ZodType>(
@@ -23,7 +23,7 @@ export function convertBigIntToString(obj: unknown): unknown {
     return obj.toString()
   }
   if (Array.isArray(obj)) {
-    return obj.map(item => convertBigIntToString(item))
+    return obj.map((item) => convertBigIntToString(item))
   }
   if (obj && typeof obj === 'object') {
     const converted: Record<string, unknown> = {}
@@ -35,7 +35,6 @@ export function convertBigIntToString(obj: unknown): unknown {
   return obj
 }
 
-
 // Summarize a call trace for compact output
 export interface SummarizedCall {
   type: string
@@ -73,17 +72,20 @@ export function summarizeTrace(trace: unknown): { hasError: boolean; errorPath:
     summary = `SUCCESS - ${topCalls.length} top-level calls: ${topCalls.slice(0, 5).join(', ')}${topCalls.length > 5 ? '...' : ''}`
   }
 
-  return { 
-    hasError: result !== null, 
-    errorPath: result?.errorPath ?? null, 
-    summary 
+  return {
+    hasError: result !== null,
+    errorPath: result?.errorPath ?? null,
+    summary
   }
 }
 
 function findErrorInTrace(trace: unknown): { errorPath: SummarizedCall[]; errorMessage: string } | null {
   if (!trace || typeof trace !== 'object') return null
 
-  function findError(call: Record<string, unknown>, path: SummarizedCall[]): { errorPath: SummarizedCall[]; errorMessage: string } | null {
+  function findError(
+    call: Record<string, unknown>,
+    path: SummarizedCall[]
+  ): { errorPath: SummarizedCall[]; errorMessage: string } | null {
     const type = (call.type as string) || 'CALL'
     const error = (call.error as string) || (call.revertReason as string)
     const subcalls = call.calls as Record<string, unknown>[] | undefined
@@ -130,124 +132,64 @@ function findErrorInTrace(trace: unknown): { errorPath: SummarizedCall[]; errorM
   return findError(trace as Record<string, unknown>, [])
 }
 
-// Convert arguments to appropriate types based on ABI
+/**
+ * Coerce a JSON value into what viem expects for an ABI type. Tuples, arrays and anything
+ * else pass through: viem validates them, and guessing here would only mangle them.
+ */
+function coerce(value: unknown, type: string): unknown {
+  if (value === null || value === undefined) return null
+
+  if (type === 'address' || type === 'string' || type.startsWith('bytes')) {
+    return String(value)
+  }
+
+  if (type === 'bool') {
+    if (typeof value === 'boolean') return value
+    if (typeof value === 'string') return value.toLowerCase() === 'true'
+    return Boolean(value)
+  }
+
+  if (type.startsWith('uint') || type.startsWith('int')) {
+    if (typeof value === 'number' || typeof value === 'string') return BigInt(value)
+    throw new Error(`Invalid type for ${type}: ${typeof value}`)
+  }
+
+  return value
+}
+
 export function convertArgumentsToTypes(
   args: (string | number | boolean | null)[],
   abiInputs: readonly AbiParameter[]
 ): unknown[] {
-  return args.map((arg, index) => {
-    if (index >= abiInputs.length) {
-      throw new Error(`Too many arguments provided. Expected ${abiInputs.length}, got ${args.length}`)
-    }
+  if (args.length > abiInputs.length) {
+    throw new Error(`Too many arguments provided. Expected ${abiInputs.length}, got ${args.length}`)
+  }
 
+  return args.map((arg, index) => {
     const param = abiInputs[index]
     if (!param?.type) {
       throw new Error(`Missing type information for parameter at index ${index}`)
     }
-
-    const paramType = param.type
-
-    // Handle null values
-    if (arg === null) {
-      return null
-    }
-
-    // Handle different parameter types
-    if (paramType === 'address') {
-      return String(arg)
-    }
-
-    if (paramType === 'bool') {
-      if (typeof arg === 'boolean') return arg
-      if (typeof arg === 'string') return arg.toLowerCase() === 'true'
-      return Boolean(arg)
-    }
-
-    if (paramType.startsWith('uint') || paramType.startsWith('int')) {
-      if (typeof arg === 'number') return BigInt(arg)
-      if (typeof arg === 'string') return BigInt(arg)
-      throw new Error(`Invalid type for ${paramType}: ${typeof arg}`)
-    }
-
-    if (paramType === 'string') {
-      return String(arg)
-    }
-
-    if (paramType === 'bytes' || paramType.startsWith('bytes')) {
-      return String(arg)
-    }
-
-    // For other types, try to convert appropriately
-    if (typeof arg === 'string' && arg.startsWith('0x')) {
-      return arg // Assume it's already properly formatted
-    }
-    return arg
+    return coerce(arg, param.type)
   })
 }
 
-// Convert event arguments to appropriate types
 export function convertEventArgsToTypes(
   eventArgs: Record<string, unknown>,
   abiInputs: readonly AbiParameter[]
 ): Record<string, unknown> {
-  const converted: Record<string, unknown> = {}
-
-  for (const [argName, argValue] of Object.entries(eventArgs)) {
-    // Find the parameter definition for this argument name
-    const param = abiInputs.find(input => input.name === argName)
-
-    if (!param) {
-      throw new Error(`Parameter '${argName}' not found in event ABI`)
-    }
-
-    if (!param.type) {
-      throw new Error(`Missing type information for parameter '${argName}'`)
-    }
-
-    const paramType = param.type
-
-    // Handle null/undefined values
-    if (argValue === null || argValue === undefined) {
-      converted[argName] = null
-      continue
-    }
-
-    // Handle different parameter types
-    if (paramType === 'address') {
-      converted[argName] = String(argValue)
-    } else if (paramType === 'bool') {
-      if (typeof argValue === 'boolean') {
-        converted[argName] = argValue
-      } else if (typeof argValue === 'string') {
-        converted[argName] = argValue.toLowerCase() === 'true'
-      } else {
-        converted[argName] = Boolean(argValue)
-      }
-    } else if (paramType.startsWith('uint') || paramType.startsWith('int')) {
-      if (typeof argValue === 'number') {
-        converted[argName] = BigInt(argValue)
-      } else if (typeof argValue === 'string') {
-        converted[argName] = BigInt(argValue)
-      } else {
-        throw new Error(`Invalid type for ${paramType}: ${typeof argValue}`)
+  return Object.fromEntries(
+    Object.entries(eventArgs).map(([argName, argValue]) => {
+      const param = abiInputs.find((input) => input.name === argName)
+      if (!param) {
+        throw new Error(`Parameter '${argName}' not found in event ABI`)
       }
-    } else if (paramType === 'string') {
-      converted[argName] = String(argValue)
-    } else if (paramType === 'bytes' || paramType.startsWith('bytes')) {
-      converted[argName] = String(argValue)
-    } else {
-      // For other types, handle arrays and try to convert appropriately
-      if (Array.isArray(argValue)) {
-        converted[argName] = argValue
-      } else if (typeof argValue === 'string' && argValue.startsWith('0x')) {
-        converted[argName] = argValue // Assume it's already properly formatted
-      } else {
-        converted[argName] = argValue
+      if (!param.type) {
+        throw new Error(`Missing type information for parameter '${argName}'`)
       }
-    }
-  }
-
-  return converted
+      return [argName, coerce(argValue, param.type)]
+    })
+  )
 }
 
 // Format response as tool result
@@ -264,26 +206,12 @@ export function formatResponse(data: unknown): ToolResult {
 }
 
 // Parse command line arguments
-export function parseCommandLineArgs(): {
-  etherscanApiKey?: string
-  alchemyApiKey?: string
-  infuraApiKey?: string
-  customRpcUrls?: Record<string, string>
-  hypersyncApiKey?: string
-  showHelp?: boolean
-} {
-  const config: {
-    etherscanApiKey?: string
-    alchemyApiKey?: string
-    infuraApiKey?: string
-    customRpcUrls?: Record<string, string>
-    hypersyncApiKey?: string
-    showHelp?: boolean
-  } = {}
+export function parseCommandLineArgs(): Config & { showHelp?: boolean } {
+  const config: Config & { showHelp?: boolean } = {}
 
   function getArgValue(argName: string): string | undefined {
     const args = process.argv
-    const index = args.findIndex(arg => arg === argName)
+    const index = args.indexOf(argName)
     return index !== -1 && index + 1 < args.length ? args[index + 1] : undefined
   }
 
@@ -302,9 +230,10 @@ export function parseCommandLineArgs(): {
   config.alchemyApiKey = process.env.ALCHEMY_API_KEY || getArgValue('--alchemy-api-key')
   config.infuraApiKey = process.env.INFURA_API_KEY || getArgValue('--infura-api-key')
   config.hypersyncApiKey = process.env.HYPERSYNC_API_KEY || getArgValue('--hypersync-api-key')
+  config.walletConnectProjectId = process.env.WALLETCONNECT_PROJECT_ID || getArgValue('--walletconnect-project-id')
 
   // Parse custom RPC URLs
-  const customRpcs = getArgValue('--custom-rpc')
+  const customRpcs = process.env.CUSTOM_RPC || getArgValue('--custom-rpc')
   if (customRpcs) {
     try {
       config.customRpcUrls = JSON.parse(customRpcs)

package/src/wallet-client.ts

@@ -1,12 +1,21 @@
-import { WebSocket } from 'ws'
 import { execFile } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { WalletRelay, type TransactionRequest, type TransactionResponse } from 'web3-wallet-relay'
+import { LOCAL_PORT_ATTEMPTS, type TransactionRequest, type TransactionResponse, WalletRelay } from 'web3-wallet-relay'
+import { WebSocket } from 'ws'
 
 const REQUEST_TIMEOUT = 300_000
+
+/** Serving over HTTP means no desktop here: never try to open a browser, and never
+ *  hand out a loopback URL as the place to open the signing page. */
+const HOSTED = Boolean(process.env.MCP_HTTP_PORT)
+
+function pairingUrlFor(port: number, token: string): string {
+  const base = HOSTED ? (process.env.MCP_PUBLIC_URL ?? `http://localhost:${port}`) : `http://127.0.0.1:${port}`
+  return `${base.replace(/\/$/, '')}/#t=${token}`
+}
 const SIGNER_WAIT_TIMEOUT = 30_000
 const CONNECT_ATTEMPTS = 8
 const MAX_CONNECT_BACKOFF = 15_000
@@ -31,13 +40,14 @@ function browserApp(userAgent?: string): string | undefined {
 
 // Every MCP process on this machine looks for a relay here before starting one, so all
 // sessions end up sharing a single wallet page instead of each opening its own tab.
-const LOCAL_PORTS = [3456, 3457, 3458, 3459, 3460]
+// Kept in step with the relay: it walks the same span when 3456 is taken.
+const LOCAL_PORTS = Array.from({ length: LOCAL_PORT_ATTEMPTS }, (_, i) => 3456 + i)
 
 /**
  * Token shared by every local session, so a process can join a relay another one owns.
  * Stored 0600 because holding it is enough to push transactions at the signer.
  */
-function localToken(): string {
+export function localToken(): string {
   const dir = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'web3-tools-mcp')
   const file = join(dir, 'relay-token')
 
@@ -143,7 +153,7 @@ export class WalletClient {
     for (const port of ports) {
       try {
         await this.openSocket(`ws://127.0.0.1:${port}`, token)
-        this.pairingUrl = `http://127.0.0.1:${port}/#t=${token}`
+        this.pairingUrl = pairingUrlFor(port, token)
         return
       } catch {
         // Nothing on this port, or something that isn't our relay — keep looking.
@@ -253,7 +263,14 @@ export class WalletClient {
     // about the request over its own socket and raises itself (tab title + desktop
     // notification); asking the OS to open a URL cannot reliably focus an existing tab —
     // Chrome opens another one — and every attempt to do so left a stray tab behind.
-    if (!this.isRemote && this.pages === 0) this.openBrowser()
+    if (this.pages === 0) {
+      // Nothing to open a page with and nobody already watching one: waiting out the
+      // timeout would just stall the caller in front of a screen that does not exist.
+      if (!this.canOpenBrowser) {
+        throw new Error(`No wallet page is open. Open ${this.getUrl()}, connect your wallet, then try again.`)
+      }
+      this.openBrowser()
+    }
 
     const deadline = Date.now() + this.signerWaitTimeout
     while (this.signers === 0 && Date.now() < deadline) {
@@ -305,8 +322,13 @@ export class WalletClient {
     return `http://127.0.0.1:${LOCAL_PORTS[0]}/#t=${this.relayOptions.token ?? localToken()}`
   }
 
+  /** A relay we do not own, or a server with no desktop, has no browser for us to open. */
+  private get canOpenBrowser(): boolean {
+    return !this.isRemote && !HOSTED
+  }
+
   openBrowser() {
-    if (this.isRemote) return
+    if (!this.canOpenBrowser) return
     this.lastOpenedAt = Date.now()
     this.open(this.getUrl(), (url) => console.error(`[Wallet] Could not open a browser — visit ${url}`))
   }
@@ -374,7 +396,7 @@ export class WalletClient {
 
 let client: WalletClient | null = null
 
-export function getWalletClient(): WalletClient {
-  if (!client) client = new WalletClient()
+export function getWalletClient(relayOptions?: { port?: number; token?: string }): WalletClient {
+  if (!client) client = new WalletClient(relayOptions)
   return client
 }

package/src/walletconnect.ts

@@ -0,0 +1,269 @@
+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'
+import type { ChainName } from './types.js'
+
+/**
+ * Signing from a phone, with no page to load and nothing to host: the MCP server acts as
+ * the dApp, the wallet app is the signer, and WalletConnect's relay carries the (end-to-end
+ * encrypted) messages between them. Pair once by scanning a QR; the session is stored on
+ * disk, so it survives restarts.
+ */
+
+type SignClientType = Awaited<ReturnType<typeof importSignClient>>['prototype']
+
+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
+}
+
+interface Session {
+  topic: string
+  accounts: string[]
+  chains: number[]
+  peer?: string
+}
+
+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(): string {
+  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(): string {
+  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 {
+  private client: SignClientType | undefined
+  private starting: Promise<void> | undefined
+  private pairing: { uri: string; expiresAt: number } | undefined
+  /** Label shown in the wallet; whoever is driving this server says who they are. */
+  private agent: string | undefined
+
+  constructor(private projectId: string) {}
+
+  private async start(): Promise<void> {
+    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: []
+        }
+      })) as SignClientType
+    })().finally(() => {
+      this.starting = undefined
+    })
+
+    return this.starting
+  }
+
+  /** The most recent still-valid session, if the phone is already paired. */
+  async session(): Promise<Session | undefined> {
+    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] as string))],
+      chains: [...new Set(accounts.map((a) => Number(a.split(':')[1])))],
+      peer: session.peer?.metadata?.name
+    }
+  }
+
+  async isPaired(): Promise<boolean> {
+    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: ChainName[], agent?: string): Promise<string> {
+    // 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: ChainName, method: string, params: unknown[]): Promise<unknown> {
+    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(): Promise<Session[]> {
+    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] as string))],
+      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(): Promise<{ sessions: number; pairings: number }> {
+    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(): Promise<void> {
+    await this.disconnectAll()
+  }
+}
+
+interface WalletEntry {
+  name: string
+  native?: string
+  universal?: string
+}
+
+let wallets: WalletEntry[] | undefined
+
+/**
+ * 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: string): Promise<WalletEntry[]> {
+  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()) as { listings?: Record<string, { name: string; mobile?: WalletEntry }> }).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: string, uri: string, search?: string): Promise<Record<string, string>> {
+  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: PhoneSigner | null = null
+
+/** Configured only when a WalletConnect project id is present. */
+export function getPhoneSigner(): PhoneSigner | null {
+  const projectId = getClientManager().getConfig().walletConnectProjectId
+  if (!projectId) return null
+  if (!signer) signer = new PhoneSigner(projectId)
+  return signer
+}