web3-tools-mcp 2.0.1 → 3.0.0

package/src/anvil.ts

@@ -1,226 +1,155 @@
-import { type ChildProcess, spawn } from 'node:child_process'
 import { createPublicClient, http } from 'viem'
 import { mainnet } from 'viem/chains'
-
-export interface AnvilInstance {
-  process: ChildProcess
-  port: number
-  rpcUrl: string
-  client: ReturnType<typeof createPublicClient>
+import { HOSTED } from './hosted.js'
+
+/**
+ * Tracing through a node that already supports `debug_*`, usually a local Anvil. Nothing
+ * is started here.
+ *
+ * Anvil serves no block below its own fork height — `debug_traceCall` at an earlier one
+ * fails with BlockOutOfRangeError — so replaying an old transaction means re-forking the
+ * node there with `anvil_reset`. That discards whatever state it held, which is why it
+ * happens only when ANVIL_ALLOW_RESET says so. A provider whose endpoint exposes
+ * `debug_traceTransaction` needs none of this and is tried first.
+ */
+
+const DEFAULT_DEBUG_RPC = 'http://127.0.0.1:8545'
+
+/** Re-forking clears the node, so it is never done to someone's dev chain uninvited. */
+const ALLOW_RESET = ['1', 'true', 'yes'].includes((process.env.ANVIL_ALLOW_RESET ?? '').toLowerCase())
+
+/**
+ * The node to ask for traces, or undefined when there is none.
+ *
+ * Hosted, only an explicit setting counts: defaulting to loopback would turn every trace
+ * into a request against the server's own private network.
+ */
+export function debugRpcUrl(): string | undefined {
+  if (process.env.ANVIL_RPC_URL) return process.env.ANVIL_RPC_URL
+  return HOSTED ? undefined : DEFAULT_DEBUG_RPC
 }
 
-export interface AnvilConfig {
-  forkUrl: string
-  forkBlockNumber?: bigint
-  port?: number
-  chainId?: number
+function debugClient(url: string) {
+  return createPublicClient({ chain: mainnet, transport: http(url) })
 }
 
-// Check if anvil is installed
-export async function isAnvilInstalled(): Promise<boolean> {
-  return new Promise((resolve) => {
-    const proc = spawn('anvil', ['--version'], { shell: true })
-    proc.on('close', (code) => resolve(code === 0))
-    proc.on('error', () => resolve(false))
-  })
-}
+/** Whether a tracing node is reachable and actually offers the debug namespace. */
+export async function isDebugNodeAvailable(): Promise<boolean> {
+  const url = debugRpcUrl()
+  if (!url) return false
 
-// Find an available port
-async function findAvailablePort(startPort: number = 8545): Promise<number> {
-  const net = await import('node:net')
-  return new Promise((resolve, reject) => {
-    const server = net.createServer()
-    server.listen(startPort, () => {
-      const address = server.address()
-      if (address && typeof address === 'object') {
-        server.close(() => resolve(address.port))
-      } else {
-        server.close(() => reject(new Error('Could not get port')))
-      }
-    })
-    server.on('error', () => {
-      // Port in use, try next one
-      findAvailablePort(startPort + 1)
-        .then(resolve)
-        .catch(reject)
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'web3_clientVersion', params: [], id: 1 }),
+      signal: AbortSignal.timeout(2000)
     })
-  })
-}
-
-// Start an Anvil instance
-export async function startAnvil(config: AnvilConfig): Promise<AnvilInstance> {
-  const installed = await isAnvilInstalled()
-  if (!installed) {
-    throw new Error('Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation')
+    return response.ok
+  } catch {
+    return false
   }
+}
 
-  const port = config.port ?? (await findAvailablePort())
-  const rpcUrl = `http://127.0.0.1:${port}`
-
-  const args = ['--fork-url', config.forkUrl, '--port', port.toString(), '--silent']
+export interface SimulateCallParams {
+  to: string
+  data?: string
+  from?: string
+  value?: bigint
+  gas?: bigint
+}
 
-  if (config.forkBlockNumber !== undefined) {
-    args.push('--fork-block-number', config.forkBlockNumber.toString())
-  }
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
 
-  if (config.chainId !== undefined) {
-    args.push('--chain-id', config.chainId.toString())
+function callObject(params: SimulateCallParams) {
+  return {
+    to: params.to,
+    data: params.data,
+    from: params.from ?? ZERO_ADDRESS,
+    value: params.value ? `0x${params.value.toString(16)}` : undefined,
+    gas: params.gas ? `0x${params.gas.toString(16)}` : undefined
   }
+}
 
-  return new Promise((resolve, reject) => {
-    const proc = spawn('anvil', args, {
-      shell: true,
-      stdio: ['ignore', 'pipe', 'pipe']
-    })
-
-    let stderr = ''
-    proc.stderr?.on('data', (data) => {
-      stderr += data.toString()
-    })
+function blockTag(blockNumber?: bigint): string {
+  return blockNumber === undefined ? 'latest' : `0x${blockNumber.toString(16)}`
+}
 
-    proc.on('error', (err) => {
-      reject(new Error(`Failed to start Anvil: ${err.message}`))
-    })
+function requireDebugNode(): string {
+  const url = debugRpcUrl()
+  if (!url) {
+    throw new Error('No tracing node configured. Set ANVIL_RPC_URL to a node exposing debug_traceCall, such as a local Anvil.')
+  }
+  return url
+}
 
-    proc.on('close', (code) => {
-      if (code !== 0 && code !== null) {
-        reject(new Error(`Anvil exited with code ${code}: ${stderr}`))
-      }
-    })
+function isBlockOutOfRange(error: unknown): boolean {
+  return /BlockOutOfRangeError|block height is/i.test((error as Error)?.message ?? '')
+}
 
-    // Wait for Anvil to be ready by polling the RPC
-    const maxAttempts = 50 // 5 seconds
-    let attempts = 0
+type DebugClient = ReturnType<typeof debugClient>
 
-    const checkReady = async () => {
-      attempts++
-      try {
-        const response = await fetch(rpcUrl, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            jsonrpc: '2.0',
-            method: 'eth_blockNumber',
-            params: [],
-            id: 1
-          })
-        })
-        if (response.ok) {
-          // Add small delay to ensure all RPC methods are ready (including debug_*)
-          await new Promise((r) => setTimeout(r, 100))
-          const client = createPublicClient({
-            chain: mainnet, // Chain is overridden by fork anyway
-            transport: http(rpcUrl)
-          })
-          resolve({ process: proc, port, rpcUrl, client })
-        } else if (attempts < maxAttempts) {
-          setTimeout(checkReady, 100)
-        } else {
-          proc.kill()
-          reject(new Error('Anvil failed to start within timeout'))
-        }
-      } catch {
-        if (attempts < maxAttempts) {
-          setTimeout(checkReady, 100)
-        } else {
-          proc.kill()
-          reject(new Error('Anvil failed to start within timeout'))
-        }
-      }
+/**
+ * Run something against a block, re-forking the node when it cannot reach that far back.
+ *
+ * Returns to head afterwards rather than leaving the node pinned to an old block, which
+ * would silently break whatever the owner does with it next. Its state is gone either way.
+ */
+async function atBlock<T>(
+  client: DebugClient,
+  forkUrl: string,
+  blockNumber: bigint | undefined,
+  run: (block: string) => Promise<T>
+): Promise<T> {
+  try {
+    return await run(blockTag(blockNumber))
+  } catch (error) {
+    if (blockNumber === undefined || !isBlockOutOfRange(error)) throw error
+
+    if (!ALLOW_RESET) {
+      throw new Error(
+        `The tracing node is forked past block ${blockNumber}, and Anvil serves nothing earlier. Re-forking it there would clear its state, so set ANVIL_ALLOW_RESET=1 to allow that — or use an RPC whose endpoint supports debug_traceTransaction.`
+      )
     }
 
-    // Start checking after a small delay
-    setTimeout(checkReady, 200)
-  })
-}
-
-// Stop an Anvil instance
-export function stopAnvil(instance: AnvilInstance): void {
-  if (instance.process && !instance.process.killed) {
-    instance.process.kill('SIGTERM')
-  }
-}
+    const refork = (block?: bigint) =>
+      client.request({
+        method: 'anvil_reset' as never,
+        params: [{ forking: { jsonRpcUrl: forkUrl, ...(block === undefined ? {} : { blockNumber: Number(block) }) } }] as never
+      })
 
-// Helper to run a function with a temporary Anvil instance
-export async function withAnvil<T>(config: AnvilConfig, fn: (instance: AnvilInstance) => Promise<T>): Promise<T> {
-  const instance = await startAnvil(config)
-  try {
-    return await fn(instance)
-  } finally {
-    stopAnvil(instance)
+    await refork(blockNumber)
+    try {
+      return await run('latest')
+    } finally {
+      await refork().catch(() => {})
+    }
   }
 }
 
-// Archive RPC URLs for chains that need historical state access
-const ARCHIVE_RPCS: Record<string, string> = {
-  arbitrum: 'https://arbitrum-one.arpc.x.superfluid.dev'
+function traceCall(client: DebugClient, call: ReturnType<typeof callObject>, block: string, tracer: string): Promise<unknown> {
+  return client.request({ method: 'debug_traceCall' as never, params: [call, block, { tracer }] as never })
 }
 
-// Trace a transaction using Anvil fork
+/**
+ * Replay a transaction through the tracing node.
+ *
+ * Run against the block before it, so the state is what the transaction actually saw. The
+ * node needs archive access to that block; without it this fails rather than quietly
+ * tracing against the wrong state.
+ */
 export async function traceTransactionWithAnvil(
   forkUrl: string,
   transactionHash: string,
   blockNumber: bigint,
-  tracer: 'callTracer' | 'prestateTracer' | 'stateDiffTracer' = 'callTracer',
-  chainName?: string
+  tracer: 'callTracer' | 'prestateTracer' | 'stateDiffTracer' = 'callTracer'
 ): Promise<unknown> {
-  // Use archive RPC if available for better historical state access
-  const archiveUrl = chainName && ARCHIVE_RPCS[chainName] ? ARCHIVE_RPCS[chainName] : forkUrl
-
-  // First, fetch the original transaction from the RPC
-  const fetchClient = createPublicClient({
-    chain: mainnet,
-    transport: http(forkUrl)
-  })
-
-  const tx = await fetchClient.getTransaction({
-    hash: transactionHash as `0x${string}`
-  })
-
-  if (!tx) {
-    throw new Error(`Transaction ${transactionHash} not found`)
-  }
-
-  // Fork at the block BEFORE the transaction to replay it accurately
-  // Note: This requires an archival RPC that has historical state
-  const forkBlock = blockNumber > 0n ? blockNumber - 1n : 0n
-
-  return withAnvil(
-    {
-      forkUrl: archiveUrl,
-      forkBlockNumber: forkBlock
-    },
-    async (instance) => {
-      // Use debug_traceCall to simulate and trace the transaction
-      // Note: This replays the tx against the post-block state, which may differ slightly
-      // from the original execution if state changed within the block
-      const trace = await instance.client.request({
-        method: 'debug_traceCall' as never,
-        params: [
-          {
-            from: tx.from,
-            to: tx.to,
-            data: tx.input,
-            value: tx.value ? `0x${tx.value.toString(16)}` : '0x0',
-            gas: tx.gas ? `0x${tx.gas.toString(16)}` : undefined
-          },
-          'latest',
-          { tracer }
-        ] as never
-      })
+  const tx = await debugClient(forkUrl).getTransaction({ hash: transactionHash as `0x${string}` })
+  if (!tx) throw new Error(`Transaction ${transactionHash} not found`)
 
-      return trace
-    }
-  )
-}
-
-// Simulate a call with tracing
-export interface SimulateCallParams {
-  to: string
-  data?: string
-  from?: string
-  value?: bigint
-  gas?: bigint
+  const client = debugClient(requireDebugNode())
+  const call = callObject({ to: tx.to ?? ZERO_ADDRESS, data: tx.input, from: tx.from, value: tx.value, gas: tx.gas })
+  return atBlock(client, forkUrl, blockNumber > 0n ? blockNumber - 1n : 0n, (block) => traceCall(client, call, block, tracer))
 }
 
 export async function simulateCallWithTrace(
@@ -235,86 +164,36 @@ export async function simulateCallWithTrace(
   success: boolean
   revertReason?: string
 }> {
-  return withAnvil(
-    {
-      forkUrl,
-      forkBlockNumber: blockNumber
-    },
-    async (instance) => {
-      // First, try a regular call to get the result
-      let result = '0x'
-      let success = true
-      let revertReason: string | undefined
-      let gasUsed = 0n
-
-      try {
-        // Use eth_call to get the result
-        result = (await instance.client.request({
-          method: 'eth_call' as never,
-          params: [
-            {
-              to: params.to,
-              data: params.data,
-              from: params.from ?? '0x0000000000000000000000000000000000000000',
-              value: params.value ? `0x${params.value.toString(16)}` : undefined,
-              gas: params.gas ? `0x${params.gas.toString(16)}` : undefined
-            },
-            'latest'
-          ] as never
-        })) as string
-
-        // Estimate gas
-        try {
-          gasUsed = await instance.client.estimateGas({
-            to: params.to as `0x${string}`,
-            data: params.data as `0x${string}` | undefined,
-            account: params.from as `0x${string}` | undefined,
-            value: params.value
-          })
-        } catch {
-          // Ignore gas estimation errors
-        }
-      } catch (error) {
-        success = false
-        const errorMessage = (error as Error).message
-        // Try to extract revert reason
-        const revertMatch = errorMessage.match(/revert(?:ed)?[:\s]*(.+?)(?:\n|$)/i)
-        if (revertMatch) {
-          revertReason = revertMatch[1].trim()
-        } else {
-          revertReason = errorMessage
-        }
-      }
+  const client = debugClient(requireDebugNode())
+  const call = callObject(params)
+
+  // Call, gas and trace all inside one atBlock, so they describe the same state: a block
+  // the node cannot serve re-forks it once, instead of being reported as a revert.
+  return atBlock(client, forkUrl, blockNumber, async (block) => {
+    let result = '0x'
+    let success = true
+    let revertReason: string | undefined
+    let gasUsed = 0n
+
+    try {
+      result = (await client.request({ method: 'eth_call' as never, params: [call, block] as never })) as string
+      gasUsed = await client
+        .request({ method: 'eth_estimateGas' as never, params: [call, block] as never })
+        .then((gas) => BigInt(gas as string))
+        // Gas estimation is a nicety; a failure here says nothing about the call itself.
+        .catch(() => 0n)
+    } catch (error) {
+      if (isBlockOutOfRange(error)) throw error
+      success = false
+      const message = (error as Error).message
+      revertReason = message.match(/revert(?:ed)?[:\s]*(.+?)(?:\n|$)/i)?.[1]?.trim() ?? message
+    }
 
-      // Get the trace using debug_traceCall
-      let trace: unknown = null
-      try {
-        trace = await instance.client.request({
-          method: 'debug_traceCall' as never,
-          params: [
-            {
-              to: params.to,
-              data: params.data,
-              from: params.from ?? '0x0000000000000000000000000000000000000000',
-              value: params.value ? `0x${params.value.toString(16)}` : undefined,
-              gas: params.gas ? `0x${params.gas.toString(16)}` : undefined
-            },
-            'latest',
-            { tracer }
-          ] as never
-        })
-      } catch (traceError) {
-        // If tracing fails, include the error
-        trace = { error: (traceError as Error).message }
-      }
+    const trace = await traceCall(client, call, block, tracer).catch((error) => {
+      if (isBlockOutOfRange(error)) throw error
+      return { error: (error as Error).message }
+    })
 
-      return {
-        result,
-        trace,
-        gasUsed,
-        success,
-        revertReason
-      }
-    }
-  )
+    return { result, trace, gasUsed, success, revertReason }
+  })
 }

package/src/chains.ts

@@ -14,6 +14,7 @@ import {
   unichain,
   zksync
 } from 'viem/chains'
+import { HOSTED } from './hosted.js'
 
 /**
  * Every chain this server knows, in one table. Adding one here is the whole change: the
@@ -141,5 +142,16 @@ export type ChainName = keyof typeof TABLE
 // literal entry would otherwise lose the fields that not every chain sets.
 export const CHAINS: Record<ChainName, ChainInfo> = TABLE
 
-/** Tuple rather than array, because `z.enum` needs a non-empty literal list. */
-export const SUPPORTED_CHAINS = Object.keys(CHAINS) as [ChainName, ...ChainName[]]
+/**
+ * Chains the tools will accept.
+ *
+ * `localhost` is dropped when hosted. It resolves to the machine running the server, so on
+ * a shared host it is not the caller's dev node — it is a way to aim requests at whatever
+ * that host has listening on its own loopback.
+ *
+ * Tuple rather than array, because `z.enum` needs a non-empty literal list.
+ */
+export const SUPPORTED_CHAINS = (HOSTED ? Object.keys(CHAINS).filter((name) => name !== 'localhost') : Object.keys(CHAINS)) as [
+  ChainName,
+  ...ChainName[]
+]

package/src/client.ts

@@ -44,7 +44,6 @@ export class ClientManager {
   getRpcUrl(chainName: ChainName): string {
     return getRpcUrl(chainName, this.config)
   }
-
   getChainId(chainName: ChainName): number {
     return CHAINS[chainName].chain.id
   }

package/src/context.ts

@@ -0,0 +1,27 @@
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'
+
+/**
+ * Who a tool call is acting for.
+ *
+ * A hosted server can carry several people, and signing must never cross between them: a
+ * transaction belongs to the person whose agent asked for it and reaches only their wallet.
+ *
+ * Passed explicitly from the tool wrapper down to whatever looks up a signer. Ambient
+ * storage would read better at the call sites and fail worse: a context lost across some
+ * later boundary would silently fall back to the shared identity, which is the same
+ * cross-tenant delivery the room boundary exists to prevent — and it would not show up in
+ * a test, because tests run inside the context.
+ */
+
+/** Every self-hosted run, and every call arriving without an authenticated identity. */
+export const DEFAULT_IDENTITY = 'default'
+
+/**
+ * The identity an authenticated request belongs to. Hosted multi-tenancy is what fills
+ * this in; a single-credential server authenticates the deployment, not a person, so
+ * everyone on it is the same user.
+ */
+export function identityFrom(authInfo?: AuthInfo): string {
+  const address = authInfo?.extra?.address
+  return typeof address === 'string' && address ? address : DEFAULT_IDENTITY
+}

package/src/hosted.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether this process serves other people over HTTP, rather than one person on their own
+ * machine over stdio. It decides what a caller may reach: `localhost` as a chain, a tracing
+ * node on loopback, a browser to open. Every module that guards one of those reads it here.
+ *
+ * An environment variable rather than an argument, because the chain list is baked into the
+ * tool schemas as they are defined — so the answer has to exist before this package is
+ * imported, not when a server is started. The CLI sets MCP_HTTP_PORT; a host assembling its
+ * own server sets MCP_HOSTED=1, and startHttpServer refuses to run without one of them.
+ */
+export const HOSTED = Boolean(process.env.MCP_HTTP_PORT || process.env.MCP_HOSTED)

package/src/http-server.ts

@@ -1,9 +1,11 @@
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js'
+import type { OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js'
 import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-import express from 'express'
+import express, { type Express } from 'express'
 import type { WalletRelay } from 'web3-wallet-relay'
+import { HOSTED } from './hosted.js'
 import { SingleUserOAuthProvider } from './oauth.js'
 
 /**
@@ -31,22 +33,43 @@ export interface HttpServerOptions {
   /** Serve the signing page on this same server, so browser signing works when hosted. */
   walletRelay?: WalletRelay
   createMcpServer: () => McpServer
+  /**
+   * Who may connect, and as whom.
+   *
+   * The default authenticates the deployment rather than a person: one token, shared. A
+   * host serving several people supplies its own — logging them in however it likes, and
+   * putting the identity in the issued token's `extra`, which is where the tools read it
+   * from. `MCP_TOKEN` is then no longer required.
+   */
+  provider?: OAuthServerProvider
+  /** A host's own routes, mounted before the signing page claims whatever is left at the root. */
+  routes?: (app: Express) => void
 }
 
 export async function startHttpServer(options: HttpServerOptions): Promise<{ url: string; port: number; walletUrl?: string }> {
+  // The guards a shared host needs — no `localhost` chain, no loopback tracing node, no
+  // browser opened on the server — were decided when the package loaded, and cannot be
+  // switched on from here.
+  if (!HOSTED) {
+    throw new Error(
+      'Serving over HTTP needs MCP_HOSTED=1 (or MCP_HTTP_PORT) in the environment before web3-tools-mcp is imported'
+    )
+  }
+
   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
 
   // A reachable MCP server with a paired phone can push signing prompts at that phone. It
-  // never runs without a token.
-  if (!token) {
+  // never runs unauthenticated — either a host brought its own way to log people in, or
+  // there is a token.
+  if (!options.provider && !token) {
     throw new Error('MCP_TOKEN is required to serve MCP over HTTP — anyone reaching the URL could request signatures')
   }
 
   const publicUrl = options.publicUrl ?? process.env.MCP_PUBLIC_URL ?? `http://localhost:${port}`
   const issuer = new URL(publicUrl)
-  const provider = new SingleUserOAuthProvider(token)
+  const provider = options.provider ?? new SingleUserOAuthProvider(token as string)
 
   const app = express()
   app.use(express.json())
@@ -78,6 +101,8 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
     resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(new URL('/mcp', issuer))
   })
 
+  options.routes?.(app)
+
   app.all('/mcp', authenticate, async (req, res) => {
     const mcp = options.createMcpServer()
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
@@ -110,7 +135,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
   let walletUrl: string | undefined
   if (options.walletRelay) {
     options.walletRelay.attach(server, (relayApp) => app.use(relayApp))
-    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.token}`
+    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.signerToken}`
   }
 
   return { url: `${publicUrl.replace(/\/$/, '')}/mcp`, port: (server.address() as { port: number }).port, walletUrl }