web3-tools-mcp 1.0.0 → 1.1.0

package/src/tools/contract.ts

@@ -0,0 +1,180 @@
+import { type AbiFunction, type Address, isAddress, parseAbiItem } from "viem";
+import { z } from "zod";
+import type { ChainName } from "../types.js";
+import { getClientManager, SUPPORTED_CHAINS } from "../client.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)"),
+  contractAddress: z
+    .string()
+    .describe("Contract address to call (must be valid checksummed address)"),
+  functionAbi: z
+    .string()
+    .describe(
+      'Function ABI signature string (e.g., "function balanceOf(address owner) view returns (uint256)"). Only view/pure functions allowed.'
+    ),
+  args: z
+    .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+    .optional()
+    .describe(
+      "Function arguments in order matching the ABI signature. Automatically type-converted."
+    ),
+  blockNumber: z
+    .string()
+    .optional()
+    .describe("Block number for historical queries (defaults to latest)"),
+  label: z.string().optional().describe("Optional label to identify this call in batch results"),
+});
+
+export default {
+  call_contract_function: createTool(
+    "Call Contract Functions",
+    "Execute multiple view/pure contract functions efficiently. BATCH OPTIMIZED - use for reading contract state, token metadata.",
+    z.object({
+      calls: z
+        .array(ContractCallSchema)
+        .describe(
+          "Array of contract function calls. Automatically batched by chain/block for optimal performance."
+        ),
+    }),
+    async (args) => {
+      // Group by chain and blockNumber for efficient multicall
+      const groupedCalls = new Map<string, typeof args.calls>();
+      for (const item of args.calls) {
+        const key = `${item.chain}:${item.blockNumber || "latest"}`;
+        if (!groupedCalls.has(key)) {
+          groupedCalls.set(key, []);
+        }
+        groupedCalls.get(key)!.push(item);
+      }
+
+      const allResults: Array<{
+        index: number;
+        label?: string;
+        contractAddress: string;
+        functionName: string;
+        success: boolean;
+        result?: unknown;
+        error?: string;
+        chain: string;
+        blockNumber: string;
+      }> = [];
+
+      try {
+        // Process each group
+        for (const [key, calls] of groupedCalls) {
+          const [chain, blockNum] = key.split(":");
+          const clientManager = getClientManager();
+          const client = clientManager.getClient(chain as ChainName);
+          const blockTag = blockNum === "latest" ? "latest" : BigInt(blockNum);
+
+          // Prepare multicall contracts
+          const multicallContracts = calls.map((call) => {
+            if (!isAddress(call.contractAddress)) {
+              throw new Error(`Invalid contract address: ${call.contractAddress}`);
+            }
+
+            const abiItem = parseAbiItem(call.functionAbi) as AbiFunction;
+
+            if (abiItem.stateMutability !== "view" && abiItem.stateMutability !== "pure") {
+              throw new Error(`Only view and pure functions can be called: ${call.functionAbi}`);
+            }
+
+            const convertedArgs = convertArgumentsToTypes(call.args || [], abiItem.inputs);
+
+            return {
+              address: call.contractAddress as Address,
+              abi: [abiItem],
+              functionName: abiItem.name,
+              args: convertedArgs,
+            };
+          });
+
+          // Execute multicall
+          const multicallResults = await client.multicall({
+            contracts: multicallContracts,
+            blockNumber: blockTag === "latest" ? undefined : blockTag,
+          });
+
+          // Process results
+          multicallResults.forEach((result, idx) => {
+            const call = calls[idx]!;
+            const abiItem = parseAbiItem(call.functionAbi) as AbiFunction;
+            const originalIndex = args.calls.indexOf(call);
+
+            if (result.status === "success") {
+              allResults[originalIndex] = {
+                index: originalIndex,
+                label: call.label,
+                contractAddress: call.contractAddress,
+                functionName: abiItem.name,
+                success: true,
+                result: result.result,
+                chain: call.chain,
+                blockNumber: call.blockNumber || "latest",
+              };
+            } else {
+              allResults[originalIndex] = {
+                index: originalIndex,
+                label: call.label,
+                contractAddress: call.contractAddress,
+                functionName: abiItem.name,
+                success: false,
+                error: result.error instanceof Error ? result.error.message : String(result.error),
+                chain: call.chain,
+                blockNumber: call.blockNumber || "latest",
+              };
+            }
+          });
+        }
+
+        return formatResponse({
+          success: true,
+          totalCalls: args.calls.length,
+          successfulCalls: allResults.filter((r) => r.success).length,
+          failedCalls: allResults.filter((r) => !r.success).length,
+          results: allResults,
+        });
+      } catch (error) {
+        throw new Error(`Contract call failed: ${error}`);
+      }
+    }
+  ),
+
+  is_contract: createTool(
+    "Check Address Type",
+    "Determine if address is smart contract or EOA. Returns contract status and bytecode length.",
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe("Blockchain network to query"),
+      address: z
+        .string()
+        .describe("Address to check (returns true if contract, false if EOA/wallet)"),
+    }),
+    async (args) => {
+      if (!isAddress(args.address)) {
+        throw new Error("Invalid address format");
+      }
+
+      const clientManager = getClientManager();
+      const client = clientManager.getClient(args.chain as ChainName);
+
+      try {
+        const bytecode = await client.getBytecode({ address: args.address as Address });
+        const isContractFlag = bytecode !== undefined && bytecode !== "0x";
+
+        return formatResponse({
+          address: args.address,
+          isContract: isContractFlag,
+          type: isContractFlag ? "contract" : "EOA",
+          chain: args.chain,
+          bytecodeLength: bytecode ? bytecode.length - 2 : 0, // -2 for '0x' prefix
+        });
+      } catch (error) {
+        throw new Error(`Failed to check address type: ${error}`);
+      }
+    }
+  ),
+};

package/src/tools/index.ts

@@ -0,0 +1,35 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { 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 logTools from './logs.js'
+import signatureTools from './signatures.js'
+
+const allToolDefinitions = {
+  ...signatureTools,
+  ...contractTools,
+  ...contractInfoTools,
+  ...balanceTools,
+  ...logTools,
+  ...advancedTools
+} as const
+
+// Register all tools with the MCP server
+export function registerAllTools(server: McpServer) {
+  Object.entries(allToolDefinitions).forEach(([name, tool]) => {
+    server.registerTool(
+      name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.schema.shape
+      },
+      async (args: any, _extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
+        return await tool.handler(args)
+      }
+    )
+  })
+}

package/src/tools/logs.ts

@@ -0,0 +1,291 @@
+import { HypersyncClient, type Log, LogField } from '@envio-dev/hypersync-client'
+import {
+  type AbiEvent,
+  type Address,
+  isAddress,
+  keccak256,
+  parseAbiItem,
+  toBytes,
+  toEventSignature
+} from 'viem'
+import { z } from 'zod'
+import type { ChainName } from '../types.js'
+import { getClientManager, HYPERSYNC_URLS, SUPPORTED_CHAINS } from '../client.js'
+import { convertEventArgsToTypes, createTool, formatResponse } from '../utils.js'
+
+async function getLogsWithHypersync(
+  chainName: ChainName,
+  eventAbi: string,
+  hypersyncApiKey?: string,
+  address?: string,
+  fromBlock?: string,
+  toBlock?: string,
+  eventArgs?: Record<string, unknown>
+) {
+  const hypersyncUrl = HYPERSYNC_URLS[chainName]
+  if (!hypersyncUrl) {
+    throw new Error(`Hypersync not supported for chain: ${chainName}`)
+  }
+
+  const client = HypersyncClient.new({
+    url: hypersyncUrl,
+    bearerToken: hypersyncApiKey
+  })
+
+  const abiItem = parseAbiItem(eventAbi) as AbiEvent
+  const eventSignature = toEventSignature(abiItem)
+  const topic0 = keccak256(toBytes(eventSignature))
+
+  // Build topics array for filtering
+  const topics: (string | string[] | null)[] = [topic0]
+
+  // Add indexed parameter filtering if eventArgs provided
+  if (eventArgs && Object.keys(eventArgs).length > 0) {
+    const indexedInputs = abiItem.inputs.filter(input => input.indexed)
+
+    for (let i = 0; i < indexedInputs.length && i < 3; i++) {
+      const input = indexedInputs[i]
+      const argValue = input?.name ? eventArgs[input.name] : undefined
+
+      if (argValue !== undefined) {
+        // Convert the argument to the proper format for topic filtering
+        let topicValue: string
+        if (typeof argValue === 'string' && argValue.startsWith('0x')) {
+          topicValue = argValue
+        } else if (typeof argValue === 'string' && isAddress(argValue)) {
+          topicValue = argValue.toLowerCase().padStart(66, '0x000000000000000000000000')
+        } else {
+          // For other types, we'd need more sophisticated encoding
+          topicValue = String(argValue)
+        }
+        topics.push(topicValue)
+      } else {
+        topics.push(null)
+      }
+    }
+  }
+
+  const query = {
+    fieldSelection: {
+      log: [
+        LogField.Address,
+        LogField.Topic0,
+        LogField.Topic1,
+        LogField.Topic2,
+        LogField.Topic3,
+        LogField.Data,
+        LogField.BlockNumber,
+        LogField.BlockHash,
+        LogField.TransactionHash,
+        LogField.TransactionIndex,
+        LogField.LogIndex
+      ]
+    },
+    fromBlock: fromBlock ? Number.parseInt(fromBlock) : 0,
+    toBlock: toBlock ? Number.parseInt(toBlock) : undefined,
+    logs: [
+      {
+        address: address ? [address] : undefined,
+        topics: topics.filter(t => t !== null).map(t => (Array.isArray(t) ? t : [t]))
+      }
+    ]
+  }
+
+  const res = await client.get(query)
+
+  // Convert hypersync logs to viem-compatible format
+  const decodedLogs = res.data.logs
+    .map((log: Log) => {
+      try {
+        return {
+          address: log.address as Address,
+          blockHash: log.blockHash as `0x${string}`,
+          blockNumber: log.blockNumber ? BigInt(log.blockNumber) : 0n,
+          data: log.data as `0x${string}`,
+          logIndex: log.logIndex,
+          topics: log.topics as `0x${string}`[],
+          transactionHash: log.transactionHash as `0x${string}`,
+          transactionIndex: log.transactionIndex,
+          eventName: abiItem.name,
+          args: {}
+        }
+      } catch (error) {
+        console.warn('Failed to decode log:', error)
+        return null
+      }
+    })
+    .filter((log): log is NonNullable<typeof log> => log !== null)
+
+  return decodedLogs
+}
+
+export default {
+  get_logs: createTool(
+    'Query Contract Events',
+    'Search and decode contract events with filtering. Uses viem with hypersync fallback. Specify address and block ranges for best performance.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
+      eventAbi: z
+        .string()
+        .describe(
+          'Event ABI definition (e.g., "event Transfer(address indexed from, address indexed to, uint256 value)")'
+        ),
+      address: z.string().optional().describe('Contract address (RECOMMENDED for performance)'),
+      fromBlock: z.string().optional().describe('Start block (defaults to latest-1000)'),
+      toBlock: z.string().optional().describe('End block (defaults to latest)'),
+      eventArgs: z
+        .record(
+          z.union([
+            z.string(),
+            z.number(),
+            z.boolean(),
+            z.array(z.union([z.string(), z.number(), z.boolean()]))
+          ])
+        )
+        .optional()
+        .describe('Filter by indexed parameters: {"from": "0x123...", "to": "0x456..."}')
+    }),
+    async (args) => {
+      const clientManager = getClientManager()
+      const config = (clientManager as any).config
+
+      // First try with regular viem client
+      try {
+        const client = clientManager.getClient(args.chain as ChainName)
+        const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
+
+        // Determine block range
+        const fromBlockNum = args.fromBlock ? BigInt(args.fromBlock) : undefined
+        const toBlockNum = args.toBlock ? BigInt(args.toBlock) : undefined
+
+        // Prepare getLogs parameters
+        const getLogsParams: {
+          address?: Address
+          event: AbiEvent
+          fromBlock?: bigint
+          toBlock?: bigint
+          args?: Record<string, unknown>
+        } = {
+          event: abiItem,
+          fromBlock: fromBlockNum,
+          toBlock: toBlockNum
+        }
+
+        // Add address filter if provided
+        if (args.address && isAddress(args.address)) {
+          getLogsParams.address = args.address as Address
+        }
+
+        // Add event argument filters if provided
+        if (args.eventArgs && Object.keys(args.eventArgs).length > 0) {
+          // Convert event arguments to proper types based on ABI
+          const convertedEventArgs = convertEventArgsToTypes(args.eventArgs, abiItem.inputs)
+          getLogsParams.args = convertedEventArgs
+        }
+
+        // Use client.getLogs with proper typing
+        const logs = await client.getLogs(getLogsParams)
+
+        // Convert logs to serializable format
+        const serializedLogs = logs.map(log => {
+          const baseLogData = {
+            address: log.address,
+            blockHash: log.blockHash,
+            blockNumber: log.blockNumber?.toString(),
+            data: log.data,
+            logIndex: log.logIndex,
+            topics: log.topics,
+            transactionHash: log.transactionHash,
+            transactionIndex: log.transactionIndex
+          }
+
+          return {
+            ...baseLogData,
+            decoded: {
+              eventName: log.eventName,
+              args: log.args
+            }
+          }
+        })
+
+        return formatResponse({
+          logs: serializedLogs,
+          eventSignature: toEventSignature(abiItem),
+          chain: args.chain,
+          fromBlock: fromBlockNum?.toString() || 'latest',
+          toBlock: toBlockNum?.toString() || 'latest',
+          count: logs.length,
+          dataSource: 'viem',
+          filters: {
+            address: args.address || null,
+            eventArgs: args.eventArgs || null
+          }
+        })
+      } catch (viemError) {
+        // If viem fails and we have hypersync support for this chain, try hypersync as fallback
+        if (HYPERSYNC_URLS[args.chain as ChainName] && args.chain !== 'localhost') {
+          console.warn(`Viem getLogs failed for ${args.chain}, trying hypersync fallback:`, viemError)
+
+          try {
+            const hypersyncLogs = await getLogsWithHypersync(
+              args.chain as ChainName,
+              args.eventAbi,
+              config.hypersyncApiKey,
+              args.address,
+              args.fromBlock,
+              args.toBlock,
+              args.eventArgs
+            )
+
+            const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
+            const fromBlockNum = args.fromBlock ? BigInt(args.fromBlock) : undefined
+            const toBlockNum = args.toBlock ? BigInt(args.toBlock) : undefined
+
+            // Convert hypersync logs to the same format as viem logs
+            const serializedLogs = hypersyncLogs.map(log => {
+              const baseLogData = {
+                address: log.address,
+                blockHash: log.blockHash,
+                blockNumber: log.blockNumber?.toString(),
+                data: log.data,
+                logIndex: log.logIndex,
+                topics: log.topics,
+                transactionHash: log.transactionHash,
+                transactionIndex: log.transactionIndex
+              }
+
+              return {
+                ...baseLogData,
+                decoded: {
+                  eventName: log.eventName,
+                  args: log.args
+                }
+              }
+            })
+
+            return formatResponse({
+              logs: serializedLogs,
+              eventSignature: toEventSignature(abiItem),
+              chain: args.chain,
+              fromBlock: fromBlockNum?.toString() || 'latest',
+              toBlock: toBlockNum?.toString() || 'latest',
+              count: hypersyncLogs.length,
+              dataSource: 'hypersync',
+              filters: {
+                address: args.address || null,
+                eventArgs: args.eventArgs || null
+              }
+            })
+          } catch (hypersyncError) {
+            throw new Error(
+              `Both viem and hypersync failed. Viem error: ${viemError}. Hypersync error: ${hypersyncError}`
+            )
+          }
+        } else {
+          // No hypersync fallback available for this chain
+          throw new Error(`Failed to get logs with viem (hypersync not available for ${args.chain}): ${viemError}`)
+        }
+      }
+    }
+  )
+}

package/src/tools/signatures.ts

@@ -0,0 +1,126 @@
+import {
+  type AbiEvent,
+  type AbiFunction,
+  type AbiParameter,
+  keccak256,
+  parseAbiItem,
+  toBytes,
+  toEventSignature,
+  toFunctionSignature
+} from 'viem'
+import { z } from 'zod'
+import type { AbiError } from '../types.js'
+import { createTool, formatResponse } from '../utils.js'
+
+const FunctionAbiSchema = z.object({
+  functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")')
+})
+
+const EventAbiSchema = z.object({
+  eventAbi: z
+    .string()
+    .describe('Event ABI definition (e.g., "event Transfer(address indexed from, address indexed to, uint256 value)")')
+})
+
+const ErrorAbiSchema = z.object({
+  errorAbi: z
+    .string()
+    .describe('Error ABI definition (e.g., "error InsufficientBalance(uint256 available, uint256 required)")')
+})
+
+export default {
+  get_function_signature: createTool(
+    'Calculate Function Signatures',
+    'Generate 4-byte function selectors from ABI definitions. BATCH OPTIMIZED - use for transaction decoding.',
+    z.object({
+      items: z
+        .array(FunctionAbiSchema)
+        .describe('Array of function ABI definitions. Batch multiple functions for efficiency.')
+    }),
+    async (args) => {
+      try {
+        const results = args.items.map((item) => {
+          const abiItem = parseAbiItem(item.functionAbi) as AbiFunction
+          const signature = toFunctionSignature(abiItem)
+          const hash = keccak256(toBytes(signature))
+          const selector = hash.slice(0, 10)
+
+          return {
+            signature: selector,
+            fullSignature: signature,
+            functionName: abiItem.name,
+            inputs: abiItem.inputs,
+            outputs: abiItem.outputs || [],
+            stateMutability: abiItem.stateMutability,
+            originalAbi: item.functionAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse function ABI: ${error}`)
+      }
+    }
+  ),
+
+  get_event_signature: createTool(
+    'Calculate Event Signatures',
+    'Generate event topic0 hashes from ABI definitions. BATCH OPTIMIZED - use for log filtering setup.',
+    z.object({
+      items: z.array(EventAbiSchema).describe('Array of event ABI definitions. Batch multiple events for optimal performance.')
+    }),
+    async (args) => {
+      try {
+        const results = args.items.map((item) => {
+          const abiItem = parseAbiItem(item.eventAbi) as AbiEvent
+          const signature = toEventSignature(abiItem)
+          const hash = keccak256(toBytes(signature))
+
+          return {
+            signature: hash,
+            topic0: hash,
+            fullSignature: signature,
+            eventName: abiItem.name,
+            inputs: abiItem.inputs,
+            anonymous: abiItem.anonymous || false,
+            originalAbi: item.eventAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse event ABI: ${error}`)
+      }
+    }
+  ),
+
+  get_error_signature: createTool(
+    'Calculate Error Signatures',
+    'Generate 4-byte error selectors from ABI definitions. BATCH OPTIMIZED - use for revert reason decoding.',
+    z.object({
+      items: z.array(ErrorAbiSchema).describe('Array of error ABI definitions. Batch related errors for efficiency.')
+    }),
+    async (args) => {
+      try {
+        const results = args.items.map((item) => {
+          const abiItem = parseAbiItem(item.errorAbi) as AbiError
+          const signature = `${abiItem.name}(${abiItem.inputs.map((input: AbiParameter) => input.type).join(',')})`
+          const hash = keccak256(toBytes(signature))
+          const selector = hash.slice(0, 10)
+
+          return {
+            signature: selector,
+            fullSignature: signature,
+            errorName: abiItem.name,
+            inputs: abiItem.inputs,
+            originalAbi: item.errorAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse error ABI: ${error}`)
+      }
+    }
+  )
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { AbiParameter } from 'viem'
+
+// Define AbiError type since it's not exported by viem
+export interface AbiError {
+  type: 'error'
+  name: string
+  inputs: readonly AbiParameter[]
+}
+
+// Configuration interface
+export interface Config {
+  etherscanApiKey?: string
+  alchemyApiKey?: string
+  infuraApiKey?: string
+  customRpcUrls?: Record<string, string>
+  hypersyncApiKey?: string
+}
+
+// Chain names
+export type ChainName = 'mainnet' | 'base' | 'arbitrum' | 'polygon' | 'optimism' | 'celo' | 'localhost'
+
+// Tool handler result type
+export interface ToolResult {
+  [x: string]: unknown
+  content: Array<{
+    type: 'text'
+    text: string
+  }>
+}