web3-tools-mcp 1.0.0 → 1.1.0

package/src/index.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import packageJson from "../package.json" with { type: "json" };
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { initializeClientManager } from "./client.js";
+import { registerAllTools } from "./tools/index.js";
+import { parseCommandLineArgs } from "./utils.js";
+
+// Parse configuration
+const config = parseCommandLineArgs();
+
+// Show help if requested
+if (config.showHelp) {
+  console.log(`
+Web3 Tools MCP Server v${packageJson.version}
+${packageJson.description}
+
+USAGE:
+  npx web3-tools-mcp [OPTIONS]
+
+OPTIONS:
+  --help, -h                    Show this help message
+  --etherscan-api-key <key>     Etherscan API key (for contract ABI retrieval)
+  --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)
+  --custom-rpc <json>           Custom RPC URLs as JSON object
+                                Example: '{"mainnet":"https://...", "base":"https://..."}'
+
+ENVIRONMENT VARIABLES:
+  ETHERSCAN_API_KEY             Alternative to --etherscan-api-key
+  ALCHEMY_API_KEY               Alternative to --alchemy-api-key
+  INFURA_API_KEY                Alternative to --infura-api-key
+  HYPERSYNC_API_KEY             Alternative to --hypersync-api-key
+
+SUPPORTED CHAINS:
+  mainnet, base, arbitrum, polygon, optimism, celo, localhost
+
+EXAMPLES:
+  # Use with npx (recommended)
+  npx web3-tools-mcp --etherscan-api-key YOUR_KEY
+
+  # Use environment variables
+  export ETHERSCAN_API_KEY=your_key
+  npx web3-tools-mcp
+
+  # Use custom RPC
+  npx web3-tools-mcp --custom-rpc '{"mainnet":"https://my-rpc.com"}'
+
+DOCUMENTATION:
+  GitHub: ${packageJson.repository.url.replace('git+', '').replace('.git', '')}
+  Issues: ${packageJson.bugs.url}
+
+For MCP client configuration, see the README.md file.
+`);
+  process.exit(0);
+}
+
+// Log configuration info
+if (config.etherscanApiKey) {
+  console.error("[MCP] Etherscan API key configured");
+}
+if (config.alchemyApiKey) {
+  console.error("[MCP] Alchemy API key configured");
+}
+if (config.infuraApiKey) {
+  console.error("[MCP] Infura API key configured");
+}
+if (config.customRpcUrls) {
+  console.error("[MCP] Custom RPC URLs:", Object.keys(config.customRpcUrls));
+}
+
+// Initialize client manager
+initializeClientManager(config);
+
+// Create MCP server instance
+const server = new McpServer({
+  name: "web3-tools-mcp",
+  version: packageJson.version,
+});
+
+// Register all tools
+registerAllTools(server);
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Web3 Tools MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/tools/advanced.ts

@@ -0,0 +1,262 @@
+import { type Address, decodeAbiParameters, isAddress, parseAbiParameters } from 'viem'
+import { z } from 'zod'
+import type { ChainName } from '../types.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
+import { createTool, formatResponse } from '../utils.js'
+
+export default {
+  get_storage_at: createTool(
+    'Read Contract Storage',
+    '⚠️ ADVANCED: Direct storage slot access with type decoding. Use for low-level contract inspection.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
+      address: z.string().describe('The contract address to inspect'),
+      slot: z.string().describe('Storage slot (hex string, e.g., "0x0")'),
+      abiType: z
+        .string()
+        .describe('ABI type for decoding (e.g., "uint256", "address", "bool", "bytes32")'),
+      blockNumber: z.string().optional().describe('Block number (optional, defaults to latest)')
+    }),
+    async (args) => {
+      if (!isAddress(args.address)) {
+        throw new Error('Invalid address format')
+      }
+
+      const clientManager = getClientManager()
+      const client = clientManager.getClient(args.chain as ChainName)
+      const blockTag = args.blockNumber ? BigInt(args.blockNumber) : 'latest'
+
+      try {
+        const storageValue = await client.getStorageAt({
+          address: args.address as Address,
+          slot: args.slot as `0x${string}`,
+          blockNumber: blockTag === 'latest' ? undefined : blockTag
+        })
+
+        if (!storageValue) {
+          throw new Error('No storage value found')
+        }
+
+        // Decode based on ABI type
+        let decodedValue: unknown
+        let formattedValue: string
+
+        try {
+          switch (args.abiType.toLowerCase()) {
+            case 'uint256':
+            case 'uint': {
+              decodedValue = BigInt(storageValue)
+              formattedValue = (decodedValue as bigint).toString()
+              break
+            }
+            case 'int256':
+            case 'int': {
+              // Handle two's complement for negative numbers
+              const uint256Value = BigInt(storageValue)
+              const maxUint256 = BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')
+              decodedValue = uint256Value > maxUint256 / 2n ? uint256Value - maxUint256 - 1n : uint256Value
+              formattedValue = (decodedValue as bigint).toString()
+              break
+            }
+            case 'address': {
+              decodedValue = `0x${storageValue.slice(-40)}`
+              formattedValue = decodedValue as string
+              break
+            }
+            case 'bool': {
+              decodedValue = BigInt(storageValue) !== 0n
+              formattedValue = String(decodedValue)
+              break
+            }
+            case 'bytes32': {
+              decodedValue = storageValue
+              formattedValue = storageValue
+              break
+            }
+            default: {
+              // Try to decode as ABI parameters
+              try {
+                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'
+                } else {
+                  decodedValue = null
+                  formattedValue = 'Invalid ABI type'
+                }
+              } catch {
+                decodedValue = null
+                formattedValue = 'Failed to decode with custom ABI type'
+              }
+              break
+            }
+          }
+        } catch {
+          decodedValue = null
+          formattedValue = 'Failed to decode'
+        }
+
+        return formatResponse({
+          rawValue: storageValue,
+          decodedValue,
+          formattedValue,
+          abiType: args.abiType,
+          slot: args.slot,
+          address: args.address,
+          chain: args.chain,
+          blockNumber: blockTag === 'latest' ? 'latest' : blockTag.toString()
+        })
+      } catch (error) {
+        throw new Error(`Failed to get storage: ${error}`)
+      }
+    }
+  ),
+
+  get_block_info: createTool(
+    'Get Block Information',
+    'Retrieve block data including timestamps, hashes, and dates. Use for time-based analysis.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
+      blockNumber: z.string().optional().describe('Block number (optional, defaults to latest)')
+    }),
+    async (args) => {
+      const clientManager = getClientManager()
+      const client = clientManager.getClient(args.chain as ChainName)
+      const blockTag = args.blockNumber ? BigInt(args.blockNumber) : 'latest'
+
+      try {
+        const block = await client.getBlock({
+          blockNumber: blockTag === 'latest' ? undefined : blockTag,
+          includeTransactions: false
+        })
+
+        const timestamp = Number(block.timestamp)
+        const date = new Date(timestamp * 1000)
+
+        return formatResponse({
+          blockNumber: block.number,
+          timestamp: block.timestamp,
+          timestampMs: timestamp * 1000,
+          dateIso: date.toISOString(),
+          dateReadable: date.toLocaleString(),
+          hash: block.hash,
+          parentHash: block.parentHash,
+          chain: args.chain
+        })
+      } catch (error) {
+        throw new Error(`Failed to get block time: ${error}`)
+      }
+    }
+  ),
+
+  trace_transaction: createTool(
+    'Trace Transaction',
+    '⚠️ INTENSIVE: Detailed transaction analysis including call traces and state changes. Use sparingly.',
+    z.object({
+      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'])
+        .optional()
+        .describe(
+          'Trace type: "trace" (call tree, recommended), "vmTrace" (VM execution), "stateDiff" (state changes)'
+        )
+        .default('trace')
+    }),
+    async (args) => {
+      const clientManager = getClientManager()
+      const client = clientManager.getClient(args.chain as ChainName)
+
+      try {
+        // First get the transaction receipt to make sure it exists
+        const transaction = await client.getTransaction({ hash: args.transactionHash as `0x${string}` })
+        const receipt = await client.getTransactionReceipt({ hash: args.transactionHash as `0x${string}` })
+
+        let traceResult: unknown = null
+
+        // Perform the requested trace type
+        switch (args.traceType) {
+          case 'trace':
+            try {
+              // Use debug_traceTransaction for call trace
+              traceResult = await client.request({
+                method: 'debug_traceTransaction',
+                params: [args.transactionHash, { tracer: 'callTracer' }]
+              })
+            } catch (e) {
+              traceResult = { error: (e as Error).message }
+            }
+            break
+
+          case 'vmTrace':
+            try {
+              traceResult = await client.request({
+                method: 'debug_traceTransaction',
+                params: [args.transactionHash, { tracer: 'prestateTracer' }]
+              })
+            } catch (e) {
+              traceResult = { error: (e as Error).message }
+            }
+            break
+
+          case 'stateDiff':
+            try {
+              traceResult = await client.request({
+                method: 'debug_traceTransaction',
+                params: [args.transactionHash, { tracer: 'stateDiffTracer' }]
+              })
+            } catch (e) {
+              traceResult = { error: (e as Error).message }
+            }
+            break
+
+          default:
+            traceResult = {
+              type: 'CALL',
+              from: transaction.from,
+              to: transaction.to,
+              value: transaction.value?.toString() || '0',
+              gas: transaction.gas?.toString() || '0',
+              gasUsed: receipt.gasUsed?.toString() || '0',
+              input: transaction.input,
+              output: '0x',
+              error: receipt.status === 'success' ? null : 'Transaction failed'
+            }
+        }
+
+        const result = {
+          success: true,
+          chain: args.chain,
+          transactionHash: args.transactionHash,
+          traceType: args.traceType,
+          transaction: {
+            blockNumber: transaction.blockNumber?.toString(),
+            from: transaction.from,
+            to: transaction.to,
+            value: transaction.value?.toString() || '0',
+            gas: transaction.gas?.toString() || '0',
+            gasPrice: transaction.gasPrice?.toString() || '0',
+            nonce: transaction.nonce?.toString() || '0',
+            input: transaction.input
+          },
+          receipt: {
+            status: receipt.status,
+            gasUsed: receipt.gasUsed?.toString() || '0',
+            effectiveGasPrice: receipt.effectiveGasPrice?.toString() || '0',
+            logs: receipt.logs.map(log => ({
+              address: log.address,
+              topics: log.topics,
+              data: log.data
+            }))
+          },
+          trace: traceResult
+        }
+
+        return formatResponse(result)
+      } catch (error) {
+        throw new Error(`Transaction trace failed: ${error}`)
+      }
+    }
+  )
+}

package/src/tools/balance.ts

@@ -0,0 +1,176 @@
+import { type Address, formatEther, formatUnits, isAddress } from 'viem'
+import { z } from 'zod'
+import type { ChainName } from '../types.js'
+import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
+import { createTool, formatResponse } from '../utils.js'
+
+const BalanceQuerySchema = z.object({
+  chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
+  address: z.string().describe('The address to check balance for'),
+  tokenAddress: z
+    .string()
+    .optional()
+    .describe('Token contract address (optional, if not provided returns native token balance)'),
+  blockNumber: z.string().optional().describe('Block number to query (optional, defaults to latest)'),
+  label: z.string().optional().describe('Optional label for batch results')
+})
+
+export default {
+  get_balance: createTool(
+    'Get Token Balances',
+    'Retrieve native and ERC20 token balances for multiple addresses. BATCH OPTIMIZED - use for portfolio tracking, wallet monitoring.',
+    z.object({
+      queries: z.array(BalanceQuerySchema).describe('Array of balance queries. Omit tokenAddress for native balance, include for ERC20.')
+    }),
+    async (args) => {
+      // Group by chain and blockNumber for efficient processing
+      const groupedQueries = new Map<string, typeof args.queries>()
+      for (const item of args.queries) {
+        const key = `${item.chain}:${item.blockNumber || 'latest'}`
+        if (!groupedQueries.has(key)) {
+          groupedQueries.set(key, [])
+        }
+        groupedQueries.get(key)!.push(item)
+      }
+
+      const allResults: Array<{
+        index: number
+        label?: string
+        address: string
+        tokenAddress?: string
+        chain: string
+        blockNumber: string
+        success: boolean
+        balance?: unknown
+        balanceFormatted?: string
+        decimals?: number
+        error?: string
+      }> = []
+
+      try {
+        // Process each group
+        for (const [key, queries] of groupedQueries) {
+          const [chain, blockNum] = key.split(':')
+          const clientManager = getClientManager()
+          const client = clientManager.getClient(chain as ChainName)
+          const blockTag = blockNum === 'latest' ? 'latest' : BigInt(blockNum)
+
+          // Process all queries in this group
+          const results = await Promise.allSettled(
+            queries.map(async (query) => {
+              if (!isAddress(query.address)) {
+                throw new Error(`Invalid address format: ${query.address}`)
+              }
+
+              const originalIndex = args.queries.indexOf(query)
+
+              // Native token balance
+              if (!query.tokenAddress) {
+                const balance = await client.getBalance({
+                  address: query.address as Address,
+                  blockNumber: blockTag === 'latest' ? undefined : blockTag
+                })
+
+                return {
+                  index: originalIndex,
+                  label: query.label,
+                  address: query.address,
+                  chain: query.chain,
+                  blockNumber: query.blockNumber || 'latest',
+                  success: true,
+                  balance,
+                  balanceFormatted: formatEther(balance)
+                }
+              }
+
+              // ERC20 token balance
+              if (!isAddress(query.tokenAddress)) {
+                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({
+                  address: query.tokenAddress as Address,
+                  abi: [
+                    {
+                      name: 'decimals',
+                      type: 'function',
+                      stateMutability: 'view',
+                      inputs: [],
+                      outputs: [{ name: '', type: 'uint8' }]
+                    }
+                  ],
+                  functionName: 'decimals',
+                  blockNumber: blockTag === 'latest' ? undefined : blockTag
+                })) as number
+              } catch {
+                // Use default decimals if call fails
+              }
+
+              return {
+                index: originalIndex,
+                label: query.label,
+                address: query.address,
+                tokenAddress: query.tokenAddress,
+                chain: query.chain,
+                blockNumber: query.blockNumber || 'latest',
+                success: true,
+                balance,
+                balanceFormatted: formatUnits(balance as bigint, decimals),
+                decimals
+              }
+            })
+          )
+
+          // Process results
+          results.forEach((result, idx) => {
+            if (result.status === 'fulfilled') {
+              allResults[result.value.index] = result.value
+            } else {
+              const query = queries[idx]!
+              const originalIndex = args.queries.indexOf(query)
+              allResults[originalIndex] = {
+                index: originalIndex,
+                label: query.label,
+                address: query.address,
+                tokenAddress: query.tokenAddress,
+                chain: query.chain,
+                blockNumber: query.blockNumber || 'latest',
+                success: false,
+                error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+              }
+            }
+          })
+        }
+
+        return formatResponse({
+          success: true,
+          totalQueries: args.queries.length,
+          successfulQueries: allResults.filter((r) => r.success).length,
+          failedQueries: allResults.filter((r) => !r.success).length,
+          results: allResults
+        })
+      } catch (error) {
+        throw new Error(`Balance query failed: ${error}`)
+      }
+    }
+  )
+}