web3-tools-mcp 1.5.0 → 1.6.0

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)
+}

package/src/preview.ts

@@ -244,8 +244,18 @@ export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string)
   const value = tx.value ? BigInt(tx.value).toString() : undefined
 
   const [decoded, simulation, toLabel] = await Promise.all([
-    decodeCalldata(chain, tx).catch(() => undefined),
-    from ? simulate(chain, tx, from as Address).catch(() => undefined) : Promise.resolve(undefined),
+    // A preview that cannot be built must not block the transaction, but swallowing the
+    // reason makes "no details shown" impossible to diagnose.
+    decodeCalldata(chain, tx).catch((error) => {
+      console.error('[Preview] Could not decode calldata:', error instanceof Error ? error.message : error)
+      return undefined
+    }),
+    from
+      ? simulate(chain, tx, from as Address).catch((error) => {
+          console.error('[Preview] Could not simulate:', error instanceof Error ? error.message : error)
+          return undefined
+        })
+      : Promise.resolve(undefined),
     // The registry's protocol name beats anything on-chain: "Aave", not a proxy's class name.
     Promise.resolve(lookupContract(chain, tx.to))
       .then((entry) => (entry ? protocolLabel(entry.protocol) : addressLabel(chain, tx.to)))

package/src/tools/transactions.ts

@@ -1,11 +1,18 @@
 import { z } from 'zod'
 import { getWalletClient } from '../wallet-client.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import { encodeFunctionData, isAddress, parseAbiItem, parseUnits, type AbiFunction, type Address } from 'viem'
+import { encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex, type AbiFunction, type Address } from 'viem'
 import { randomBytes } from 'node:crypto'
 import type { ChainName } from '../types.js'
-import { buildTxPreview, type RawTx } from '../preview.js'
+import { buildTxPreview, type RawTx, type TxPreview } from '../preview.js'
+import { getPhoneSigner } from '../walletconnect.js'
 import { createTool, formatResponse } from '../utils.js'
+import qrcode from 'qrcode-terminal'
+
+/** Render a pairing URI as an ASCII QR, so it can be scanned straight from the chat. */
+function qrFor(uri: string): Promise<string> {
+  return new Promise((resolve) => qrcode.generate(uri, { small: true }, resolve))
+}
 
 function generateRequestId(): string {
   return randomBytes(16).toString('hex')
@@ -21,10 +28,28 @@ function explorerTxUrl(chain: ChainName, txHash: unknown): string {
 }
 
 /**
- * Send a transaction for signing, with a decoded + simulated preview attached so the
- * wallet page can show what it actually does instead of raw calldata.
+ * Send a transaction for signing.
+ *
+ * A paired phone wins over the browser page: it was set up deliberately and is the only
+ * option when there is no browser to open. Either way the transaction is decoded and
+ * simulated first — the phone wallet shows its own summary, so the preview is returned to
+ * the caller as well, where it can be read before the prompt is approved.
  */
 async function requestSignature(chain: ChainName, tx: RawTx & { data?: string }) {
+  const phone = getPhoneSigner()
+
+  if (await phone?.isPaired()) {
+    const session = await phone!.session()
+    const from = session?.accounts[0]
+    const preview = await buildTxPreview(chain, tx, from)
+
+    const txHash = await phone!.request(chain, 'eth_sendTransaction', [
+      { from, to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) }
+    ])
+
+    return { txHash, preview, signedWith: 'phone' as const }
+  }
+
   const wallet = getWalletClient()
   await wallet.waitForSigner()
 
@@ -38,14 +63,42 @@ async function requestSignature(chain: ChainName, tx: RawTx & { data?: string })
       data: { to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) },
       preview
     }),
-    preview
+    preview,
+    signedWith: 'browser' as const
+  }
+}
+
+/** What the caller should see about a transaction before it is approved. */
+function previewSummary(preview: TxPreview) {
+  return {
+    action: preview.decoded?.intent ?? preview.decoded?.functionName,
+    protocol: preview.decoded?.protocol ?? preview.toLabel,
+    details: preview.decoded?.fields.map((f) => `${f.name}: ${f.value}${f.warning ? ` (${f.warning})` : ''}`),
+    simulation: preview.simulation
   }
 }
 
+/**
+ * WalletConnect rejects with a plain `{ code, message }` rather than an Error, which
+ * String() renders as "[object Object]" — the reason a wallet gave for refusing is the
+ * whole point of the message, so dig it out.
+ */
+function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (error && typeof error === 'object') {
+    const { message, code, reason } = error as { message?: string; code?: number; reason?: string }
+    const text = message ?? reason
+    if (text) return code === undefined ? text : `${text} (code ${code})`
+    return JSON.stringify(error)
+  }
+  return String(error)
+}
+
 function failure(error: unknown, message: string) {
+  console.error('[Transaction]', message, '—', describeError(error))
   return formatResponse({
     success: false,
-    error: error instanceof Error ? error.message : String(error),
+    error: describeError(error),
     message
   })
 }
@@ -65,7 +118,7 @@ export default {
         const to = requireAddress('recipient address', args.to)
         const value = `0x${parseUnits(args.amount, 18).toString(16)}`
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to, value, data: args.data })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to, value, data: args.data })
 
         return formatResponse({
           success: true,
@@ -73,7 +126,8 @@ export default {
           transactionHash: txHash,
           to,
           amount: args.amount,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -102,7 +156,7 @@ export default {
           args: [to, parseUnits(args.amount, args.decimals ?? 18)]
         })
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to: tokenAddress, data, value: '0x0' })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to: tokenAddress, data, value: '0x0' })
 
         return formatResponse({
           success: true,
@@ -111,7 +165,8 @@ export default {
           tokenAddress,
           to,
           amount: args.amount,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -145,7 +200,7 @@ export default {
         })
         const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to: contractAddress, data, value })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to: contractAddress, data, value })
 
         return formatResponse({
           success: true,
@@ -153,7 +208,8 @@ export default {
           transactionHash: txHash,
           contractAddress,
           functionName: abiItem.name,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -164,23 +220,30 @@ export default {
 
   sign_message: createTool(
     'Sign Message',
-    'Sign a message with the connected wallet. Opens browser wallet for approval.',
+    'Sign a message with the connected wallet — a paired phone if there is one, otherwise the browser wallet.',
     z.object({
       message: z.string().describe('Message to sign')
     }),
     async (args) => {
       try {
-        const signature = await getWalletClient().request({
-          id: generateRequestId(),
-          type: 'sign_message',
-          chain: 'any',
-          data: { message: args.message }
-        })
+        // Same precedence as transactions: a hosted server has no browser to fall back on.
+        const phone = getPhoneSigner()
+        const session = await phone?.session()
+
+        const signature = session
+          ? await phone!.request('mainnet', 'personal_sign', [toHex(args.message), session.accounts[0]])
+          : await getWalletClient().request({
+              id: generateRequestId(),
+              type: 'sign_message',
+              chain: 'any',
+              data: { message: args.message }
+            })
 
         return formatResponse({
           success: true,
           message: args.message,
           signature,
+          signedWith: session ? 'phone' : 'browser',
           signatureType: 'personal_sign'
         })
       } catch (error) {
@@ -189,13 +252,74 @@ export default {
     }
   ),
 
+  pair_phone_wallet: createTool(
+    'Pair Phone Wallet',
+    'Pair a phone wallet over WalletConnect, so transactions are signed on the phone instead of in a browser. Returns a QR code to scan. Requires a WalletConnect project id.',
+    z.object({
+      chains: z
+        .array(z.enum(SUPPORTED_CHAINS))
+        .optional()
+        .describe('Chains to request access to (defaults to every supported network)')
+    }),
+    async (args) => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({
+          success: false,
+          message:
+            'No WalletConnect project id configured. Get a free one at https://dashboard.reown.com and pass --walletconnect-project-id or set WALLETCONNECT_PROJECT_ID.'
+        })
+      }
+
+      try {
+        const existing = await phone.session()
+        if (existing) {
+          return formatResponse({
+            alreadyPaired: true,
+            address: existing.accounts[0],
+            wallet: existing.peer,
+            message: 'A phone wallet is already paired. Transactions will be sent to it.'
+          })
+        }
+
+        const chains = (args.chains ?? SUPPORTED_CHAINS.filter((c) => c !== 'localhost')) as ChainName[]
+        const uri = await phone.pair(chains)
+
+        return formatResponse({
+          qr: await qrFor(uri),
+          uri,
+          message:
+            'Scan this QR with your phone wallet (MetaMask, Rabby, Trust…), or open the uri on the phone. ' +
+            'Approve the session, then run wallet_status to confirm.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not start WalletConnect pairing')
+      }
+    }
+  ),
+
   wallet_status: createTool(
     'Wallet Status',
     'Check if a wallet is connected to the browser interface',
     z.object({}),
     async () => {
-      const wallet = getWalletClient()
+      // A paired phone is the signer of record, so look there first. Connecting to the
+      // browser relay before checking would start one on a hosted server, which has no
+      // browser to open it in.
+      const phone = getPhoneSigner()
+      const phoneSession = await phone?.session().catch(() => undefined)
+      if (phoneSession) {
+        return formatResponse({
+          connected: true,
+          signer: 'phone',
+          address: phoneSession.accounts[0],
+          wallet: phoneSession.peer,
+          chains: phoneSession.chains,
+          message: 'A phone wallet is paired over WalletConnect. Transactions are sent there for signing.'
+        })
+      }
 
+      const wallet = getWalletClient()
       try {
         await wallet.connect()
       } catch (error) {
@@ -206,6 +330,8 @@ export default {
 
       return formatResponse({
         connected: wallet.isConnected(),
+        signer: 'browser',
+        phonePairing: phone ? 'Not paired — run pair_phone_wallet to sign from a phone.' : undefined,
         address: wallet.getAddress(),
         walletUrl: wallet.getUrl(),
         openTab: wallet.getPageUrl(),

package/src/types.ts

@@ -14,6 +14,7 @@ export interface Config {
   infuraApiKey?: string
   customRpcUrls?: Record<string, string>
   hypersyncApiKey?: string
+  walletConnectProjectId?: string
 }
 
 // Chain names

package/src/utils.ts

@@ -1,5 +1,5 @@
 import type { AbiParameter } from 'viem'
-import type { ToolResult } from './types.js'
+import type { Config, ToolResult } from './types.js'
 import { z } from 'zod'
 
 // Create tool helper
@@ -264,22 +264,8 @@ 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
@@ -302,6 +288,7 @@ 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')