web3-tools-mcp 2.0.2 → 3.0.0

package/src/tools/index.ts

@@ -1,17 +1,31 @@
 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 { identityFrom } from '../context.js'
+import type { ToolResult } from '../types.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 +34,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 +80,12 @@ 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
+        return await (middleware ? middleware({ tool: name, group, identity }, run) : run())
       }
     )
   })

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

@@ -1,9 +1,9 @@
 import { type Address, decodeAbiParameters, isAddress, 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 { createTool, formatResponse, summarizeTrace } from '../../utils.js'
 
 export default {
   get_storage_at: createTool(
@@ -155,7 +155,9 @@ export default {
       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()
@@ -213,14 +215,14 @@ 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, tracer)
           } catch (anvilError) {
             // Anvil tracing also failed
             traceResult = {
@@ -235,7 +237,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
@@ -299,7 +301,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'),
@@ -328,9 +330,9 @@ export default {
     }),
     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()

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

@@ -1,8 +1,8 @@
 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 { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse } from '../../utils.js'
 
 const BalanceQuerySchema = z.object({
   chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),

package/src/tools/{contract-info.ts → read/contract-info.ts}

@@ -1,8 +1,8 @@
 import { 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 { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse } from '../../utils.js'
 
 // Type for raw Etherscan contract info
 interface EtherscanContractInfo {

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

@@ -1,8 +1,8 @@
 import { type AbiFunction, type Address, isAddress, parseAbiItem } from 'viem'
 import { z } from 'zod'
-import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import type { ChainName } from '../types.js'
-import { convertArgumentsToTypes, createTool, formatResponse } from '../utils.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
 
 const ContractCallSchema = z.object({
   chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network (mainnet, base, arbitrum, polygon, optimism, celo, localhost)'),

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

@@ -1,9 +1,9 @@
 import { type Address, isAddress, namehash } from 'viem'
 import { normalize } from 'viem/ens'
 import { z } from 'zod'
-import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import type { ChainName } from '../types.js'
-import { createTool, formatResponse } from '../utils.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.js'
+import { createTool, formatResponse } from '../../utils.js'
 
 // Base ENS Contract Addresses
 const BASE_ENS_CONTRACTS = {