web3-tools-mcp 2.0.2 → 3.1.0

package/src/tools/index.ts

@@ -1,17 +1,33 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js'
 import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js'
-import advancedTools from './advanced.js'
-import balanceTools from './balance.js'
-import contractTools from './contract.js'
-import contractInfoTools from './contract-info.js'
-import ensTools from './ens.js'
-import gasTools from './gas.js'
-import logTools from './logs.js'
-import signatureTools from './signatures.js'
-import transactionTools from './transactions.js'
-
-const allToolDefinitions = {
+import { getClientManager } from '../client.js'
+import { identityFrom } from '../context.js'
+import type { ToolResult } from '../types.js'
+import { redactSecrets } from '../utils.js'
+import advancedTools from './read/advanced.js'
+import balanceTools from './read/balance.js'
+import contractTools from './read/contract.js'
+import contractInfoTools from './read/contract-info.js'
+import ensTools from './read/ens.js'
+import gasTools from './read/gas.js'
+import logTools from './read/logs.js'
+import signatureTools from './read/signatures.js'
+import signingRequestTools from './read/signing.js'
+import transactionTools from './sign/transactions.js'
+import walletTools from './sign/wallet.js'
+
+/**
+ * What a tool does with a wallet, which is the line everything else divides along.
+ *
+ * `read` answers questions about a chain and costs an RPC call. `sign` puts a transaction
+ * in front of somebody's wallet, and is the reason identity and rooms exist. A host pricing
+ * or rate-limiting tool calls almost always wants this distinction, and taking it from the
+ * folder a tool lives in means it cannot drift from a hand-kept list.
+ */
+export type ToolGroup = 'read' | 'sign'
+
+const readTools = {
   ...signatureTools,
   ...contractTools,
   ...contractInfoTools,
@@ -20,12 +36,45 @@ const allToolDefinitions = {
   ...advancedTools,
   ...ensTools,
   ...gasTools,
-  ...transactionTools
+  // A signature already asked for and paid for; collecting it is not a second request.
+  ...signingRequestTools
 } as const
 
-// Register all tools with the MCP server
-export function registerAllTools(server: McpServer) {
+const signTools = {
+  ...transactionTools,
+  ...walletTools
+} as const
+
+const allToolDefinitions = { ...readTools, ...signTools } as const
+
+const groups = new Map<string, ToolGroup>([
+  ...Object.keys(readTools).map((name) => [name, 'read'] as const),
+  ...Object.keys(signTools).map((name) => [name, 'sign'] as const)
+])
+
+/** The group a tool belongs to, for a host deciding what it costs or who may call it. */
+export function toolGroup(name: string): ToolGroup | undefined {
+  return groups.get(name)
+}
+
+/**
+ * Wraps every tool call, for a host that needs to say who may run what.
+ *
+ * Deliberately only the tool's name, its group and who is calling: enough to count calls,
+ * refuse them past a limit and record what was used, without this package taking a view on
+ * any of it. Throwing refuses the call, and the message reaches the agent — so it should
+ * say what to do about it. Whatever the returned promise settles as is what the caller
+ * sees, so a host can also time a call or meter it once it has succeeded.
+ */
+export type ToolMiddleware = (
+  call: { tool: string; group: ToolGroup; identity: string },
+  run: () => Promise<ToolResult>
+) => Promise<ToolResult>
+
+export function registerAllTools(server: McpServer, middleware?: ToolMiddleware) {
   Object.entries(allToolDefinitions).forEach(([name, tool]) => {
+    if (tool.available && !tool.available()) return
+
     server.registerTool(
       name,
       {
@@ -33,8 +82,21 @@ export function registerAllTools(server: McpServer) {
         description: tool.description,
         inputSchema: tool.schema.shape
       },
-      async (args: any, _extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
-        return await tool.handler(args)
+      async (args: any, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
+        // Passed to every handler; the ones that reach a signer must say whose it is.
+        const identity = identityFrom(extra.authInfo)
+        const run = () => tool.handler(args, identity)
+        const group = toolGroup(name) as ToolGroup
+        // Anything a tool returns or throws may quote an RPC URL, and those carry provider keys.
+        const config = getClientManager().getConfig()
+        try {
+          const result = await (middleware ? middleware({ tool: name, group, identity }, run) : run())
+          return { ...result, content: result.content.map((item) => ({ ...item, text: redactSecrets(item.text, config) })) }
+        } catch (error) {
+          if (!(error instanceof Error)) throw new Error(redactSecrets(String(error), config))
+          error.message = redactSecrets(error.message, config)
+          throw error
+        }
       }
     )
   })

package/src/tools/{advanced.ts → read/advanced.ts}

@@ -1,9 +1,37 @@
-import { type Address, decodeAbiParameters, isAddress, parseAbiParameters } from 'viem'
+import {
+  type AbiFunction,
+  type Address,
+  decodeAbiParameters,
+  encodeFunctionData,
+  isAddress,
+  parseAbiItem,
+  parseAbiParameters
+} from 'viem'
 import { z } from 'zod'
-import { isAnvilInstalled, simulateCallWithTrace, traceTransactionWithAnvil } from '../anvil.js'
-import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import type { ChainName } from '../types.js'
-import { createTool, formatResponse, summarizeTrace } from '../utils.js'
+import { isDebugNodeAvailable, simulateCallWithTrace, traceTransactionWithAnvil } from '../../anvil.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { convertArgumentsToTypes, createTool, formatResponse, rpcReason, summarizeTrace } from '../../utils.js'
+
+/** Past these, a trace would crowd everything else out of the agent's context. */
+const MAX_TRACE_CHARS = 50_000
+const MAX_INPUT_CHARS = 10_000
+const MAX_RECEIPT_LOGS = 100
+
+const SUMMARIZE_DESCRIPTION =
+  'Return a compact summary instead of the full trace: the path to the revert, or the top-level calls, with selectors only and no calldata.'
+
+/** The trace itself if it fits, otherwise its JSON cut short. */
+export function boundTrace(trace: unknown): { trace: unknown; truncated?: true } {
+  const json = JSON.stringify(trace) ?? ''
+  return json.length > MAX_TRACE_CHARS ? { trace: json.slice(0, MAX_TRACE_CHARS), truncated: true } : { trace }
+}
+
+const TRACERS = {
+  trace: { tracer: 'callTracer' },
+  prestate: { tracer: 'prestateTracer' },
+  stateDiff: { tracer: 'prestateTracer', tracerConfig: { diffMode: true } }
+} as const
 
 export default {
   get_storage_at: createTool(
@@ -77,8 +105,8 @@ export default {
               const parsedTypes = parseAbiParameters([args.abiType])
               if (parsedTypes.length > 0) {
                 const decoded = decodeAbiParameters(parsedTypes, storageValue) as readonly unknown[]
-                decodedValue = decoded.length > 0 ? decoded[0] : null
-                formattedValue = decodedValue ? String(decodedValue) : 'No data'
+                decodedValue = decoded[0]
+                formattedValue = decodedValue === undefined ? 'No data' : String(decodedValue)
               } else {
                 decodedValue = null
                 formattedValue = 'Invalid ABI type'
@@ -148,20 +176,20 @@ export default {
       chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
       transactionHash: z.string().describe('Transaction hash to trace (0x prefixed)'),
       traceType: z
-        .enum(['trace', 'vmTrace', 'stateDiff'])
+        .enum(['trace', 'prestate', 'stateDiff'])
         .optional()
-        .describe('Trace type: "trace" (call tree, recommended), "vmTrace" (VM execution), "stateDiff" (state changes)')
+        .describe(
+          'Trace type: "trace" (call tree, recommended), "prestate" (state of every touched account before the tx), "stateDiff" (state before and after, changed fields only)'
+        )
         .default('trace'),
       useAnvil: z
         .boolean()
         .optional()
-        .describe('Force using Anvil for tracing (requires Foundry installed). Auto-used as fallback when RPC tracing fails.')
+        .describe(
+          'Force tracing through the debug node (ANVIL_RPC_URL). Used automatically as a fallback when the RPC cannot trace.'
+        )
         .default(false),
-      summarize: z
-        .boolean()
-        .optional()
-        .describe('Return a compact summary instead of full trace. Truncates hex data and flattens nested calls.')
-        .default(false)
+      summarize: z.boolean().optional().describe(SUMMARIZE_DESCRIPTION).default(false)
     }),
     async (args) => {
       const clientManager = getClientManager()
@@ -174,24 +202,18 @@ export default {
       let traceResult: unknown = null
       let usedAnvil = false
 
-      // Map trace type to tracer name
-      const tracerMap: Record<string, 'callTracer' | 'prestateTracer' | 'stateDiffTracer'> = {
-        trace: 'callTracer',
-        vmTrace: 'prestateTracer',
-        stateDiff: 'stateDiffTracer'
-      }
-      const tracer = tracerMap[args.traceType ?? 'trace'] ?? 'callTracer'
+      const tracerOptions = TRACERS[args.traceType ?? 'trace']
 
       // Try RPC tracing first (unless forceAnvil is true)
       if (!args.useAnvil) {
         try {
           traceResult = await client.request({
             method: 'debug_traceTransaction',
-            params: [args.transactionHash, { tracer }]
+            params: [args.transactionHash, tracerOptions]
           })
         } catch (rpcError) {
           // RPC tracing failed, will try Anvil fallback
-          const errorMessage = (rpcError as Error).message
+          const errorMessage = rpcReason(rpcError)
           if (
             errorMessage.includes('not supported') ||
             errorMessage.includes('not available') ||
@@ -213,18 +235,18 @@ export default {
         (traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult) ||
         args.useAnvil
       ) {
-        const anvilAvailable = await isAnvilInstalled()
+        const anvilAvailable = await isDebugNodeAvailable()
         if (anvilAvailable) {
           usedAnvil = true // Mark as used before attempting (even if it fails)
           try {
             const forkUrl = clientManager.getRpcUrl(args.chain as ChainName)
             const blockNumber = transaction.blockNumber ?? 0n
 
-            traceResult = await traceTransactionWithAnvil(forkUrl, args.transactionHash, blockNumber, tracer, args.chain)
+            traceResult = await traceTransactionWithAnvil(forkUrl, args.transactionHash, blockNumber, tracerOptions.tracer)
           } catch (anvilError) {
             // Anvil tracing also failed
             traceResult = {
-              error: `Anvil tracing failed: ${(anvilError as Error).message}`,
+              error: `Anvil tracing failed: ${rpcReason(anvilError)}`,
               rpcError:
                 traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult
                   ? (traceResult as { rpcError: string }).rpcError
@@ -235,7 +257,7 @@ export default {
           // Anvil not available and RPC failed
           traceResult = {
             error:
-              'Tracing not available. Install Foundry (anvil) for local tracing: https://book.getfoundry.sh/getting-started/installation',
+              'Tracing not available. Point ANVIL_RPC_URL at a node exposing debug_traceCall — a local Anvil on 127.0.0.1:8545 is picked up automatically.',
             rpcError:
               traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult
                 ? (traceResult as { rpcError: string }).rpcError
@@ -255,11 +277,20 @@ export default {
       const traceSummary =
         args.summarize && traceResult && typeof traceResult === 'object' && !isPlainError ? summarizeTrace(traceResult) : null
 
+      const replayNote =
+        usedAnvil && !isPlainError
+          ? 'Replayed on the debug node against the state at the end of the previous block: transactions before this one in the same block were not applied, so the trace can differ from what happened on chain.' +
+            (args.traceType === 'stateDiff' ? ' This replay shows the prestate only, not a diff.' : '')
+          : undefined
+      const bounded = boundTrace(traceResult)
+      const input = transaction.input ?? '0x'
+
       const result =
         args.summarize && traceSummary
           ? {
               chain: args.chain,
               transactionHash: args.transactionHash,
+              ...(replayNote && { note: replayNote }),
               status: receipt.status,
               gasUsed: receipt.gasUsed?.toString(),
               ...traceSummary // { hasError, errorPath, summary }
@@ -270,6 +301,10 @@ export default {
               transactionHash: args.transactionHash,
               traceType: args.traceType,
               usedAnvil,
+              ...(replayNote && { note: replayNote }),
+              ...((bounded.truncated || input.length > MAX_INPUT_CHARS || receipt.logs.length > MAX_RECEIPT_LOGS) && {
+                truncated: true
+              }),
               transaction: {
                 blockNumber: transaction.blockNumber?.toString(),
                 from: transaction.from,
@@ -278,19 +313,20 @@ export default {
                 gas: transaction.gas?.toString() || '0',
                 gasPrice: transaction.gasPrice?.toString() || '0',
                 nonce: transaction.nonce?.toString() || '0',
-                input: transaction.input
+                input: input.length > MAX_INPUT_CHARS ? `${input.slice(0, MAX_INPUT_CHARS)}…` : input
               },
               receipt: {
                 status: receipt.status,
                 gasUsed: receipt.gasUsed?.toString() || '0',
                 effectiveGasPrice: receipt.effectiveGasPrice?.toString() || '0',
-                logs: receipt.logs.map((log) => ({
+                logCount: receipt.logs.length,
+                logs: receipt.logs.slice(0, MAX_RECEIPT_LOGS).map((log) => ({
                   address: log.address,
                   topics: log.topics,
                   data: log.data
                 }))
               },
-              trace: traceResult
+              trace: bounded.trace
             }
 
       return formatResponse(result)
@@ -299,7 +335,7 @@ export default {
 
   debug_call: createTool(
     'Debug Contract Call',
-    'Simulate a contract call with full trace output. Requires Foundry (anvil) installed. Useful for debugging reverts and understanding call execution.',
+    'Simulate a contract call with full trace output. Needs a node exposing debug_traceCall (a local Anvil, or ANVIL_RPC_URL). Useful for debugging reverts and understanding call execution.',
     z.object({
       chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to fork'),
       to: z.string().describe('Contract address to call'),
@@ -320,17 +356,13 @@ export default {
         .optional()
         .default('callTracer')
         .describe('Trace type: callTracer (call tree) or prestateTracer (state before execution)'),
-      summarize: z
-        .boolean()
-        .optional()
-        .describe('Return a compact summary instead of full trace. Truncates hex data and flattens nested calls.')
-        .default(false)
+      summarize: z.boolean().optional().describe(SUMMARIZE_DESCRIPTION).default(false)
     }),
     async (args) => {
       // Check if Anvil is installed
-      const anvilAvailable = await isAnvilInstalled()
+      const anvilAvailable = await isDebugNodeAvailable()
       if (!anvilAvailable) {
-        throw new Error('Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation')
+        throw new Error('No tracing node reachable. Run a local Anvil, or set ANVIL_RPC_URL to a node exposing debug_traceCall.')
       }
 
       const clientManager = getClientManager()
@@ -340,15 +372,14 @@ export default {
       let calldata = args.data
       if (args.functionAbi && !calldata) {
         try {
-          const { encodeFunctionData, parseAbiItem } = await import('viem')
-          const abiItem = parseAbiItem(args.functionAbi)
+          const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
           if (abiItem.type !== 'function') {
             throw new Error('ABI must be a function signature')
           }
           calldata = encodeFunctionData({
             abi: [abiItem],
             functionName: abiItem.name,
-            args: (args.args ?? []) as readonly unknown[]
+            args: convertArgumentsToTypes(args.args ?? [], abiItem.inputs)
           })
         } catch (encodeError) {
           throw new Error(`Failed to encode function call: ${(encodeError as Error).message}`)
@@ -404,7 +435,7 @@ export default {
               result: traceResult.result,
               gasUsed: traceResult.gasUsed.toString(),
               revertReason: traceResult.revertReason,
-              trace: traceResult.trace
+              ...boundTrace(traceResult.trace)
             }
 
       return formatResponse(result)

package/src/tools/{balance.ts → read/balance.ts}

@@ -1,8 +1,9 @@
 import { type Address, formatEther, formatUnits, isAddress } from 'viem'
 import { z } from 'zod'
-import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import type { ChainName } from '../types.js'
-import { createTool, formatResponse } from '../utils.js'
+import { tokenMeta } from '../../chain-meta.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse, MAX_BATCH, rpcReason } from '../../utils.js'
 
 const BalanceQuerySchema = z.object({
   chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
@@ -19,6 +20,7 @@ export default {
     z.object({
       queries: z
         .array(BalanceQuerySchema)
+        .max(MAX_BATCH)
         .describe('Array of balance queries. Omit tokenAddress for native balance, include for ERC20.')
     }),
     async (args) => {
@@ -42,7 +44,7 @@ export default {
         success: boolean
         balance?: unknown
         balanceFormatted?: string
-        decimals?: number
+        decimals?: number | null
         error?: string
       }> = []
 
@@ -86,42 +88,24 @@ export default {
               throw new Error(`Invalid token address format: ${query.tokenAddress}`)
             }
 
-            const balance = await client.readContract({
-              address: query.tokenAddress as Address,
-              abi: [
-                {
-                  name: 'balanceOf',
-                  type: 'function',
-                  stateMutability: 'view',
-                  inputs: [{ name: 'account', type: 'address' }],
-                  outputs: [{ name: '', type: 'uint256' }]
-                }
-              ],
-              functionName: 'balanceOf',
-              args: [query.address as Address],
-              blockNumber: blockTag === 'latest' ? undefined : blockTag
-            })
-
-            // Try to get decimals
-            let decimals = 18
-            try {
-              decimals = (await client.readContract({
+            const [balance, { decimals }] = await Promise.all([
+              client.readContract({
                 address: query.tokenAddress as Address,
                 abi: [
                   {
-                    name: 'decimals',
+                    name: 'balanceOf',
                     type: 'function',
                     stateMutability: 'view',
-                    inputs: [],
-                    outputs: [{ name: '', type: 'uint8' }]
+                    inputs: [{ name: 'account', type: 'address' }],
+                    outputs: [{ name: '', type: 'uint256' }]
                   }
                 ],
-                functionName: 'decimals',
+                functionName: 'balanceOf',
+                args: [query.address as Address],
                 blockNumber: blockTag === 'latest' ? undefined : blockTag
-              })) as number
-            } catch {
-              // Use default decimals if call fails
-            }
+              }),
+              tokenMeta(chain as ChainName, query.tokenAddress).catch(() => ({ decimals: undefined }))
+            ])
 
             return {
               index: originalIndex,
@@ -132,8 +116,9 @@ export default {
               blockNumber: query.blockNumber || 'latest',
               success: true,
               balance,
-              balanceFormatted: formatUnits(balance as bigint, decimals),
-              decimals
+              // Unknown decimals leave only the raw balance: guessing 18 could be off by 10^12.
+              balanceFormatted: decimals === undefined ? undefined : formatUnits(balance, decimals),
+              decimals: decimals ?? null
             }
           })
         )
@@ -153,7 +138,7 @@ export default {
               chain: query.chain,
               blockNumber: query.blockNumber || 'latest',
               success: false,
-              error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+              error: rpcReason(result.reason)
             }
           }
         })