web3-tools-mcp 1.0.1 → 1.2.0

package/package.json

@@ -1,28 +1,42 @@
 {
   "name": "web3-tools-mcp",
-  "version": "1.0.1",
-  "description": "MCP server for blockchain interactions using viem, etherscan and hypersync.",
+  "version": "1.2.0",
+  "description": "Model Context Protocol server for blockchain interactions using viem, Etherscan, and Hypersync",
+  "type": "module",
   "main": "dist/index.js",
-  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "web3-tools-mcp": "dist/index.js"
   },
-  "type": "module",
   "files": [
-    "dist/**/*",
+    "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
-    "start": "node dist/index.js",
-    "dev": "bun --watch index.ts",
-    "build": "bun build index.ts --outdir dist --target node --format esm && chmod +x dist/index.js",
     "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build",
-    "type-check": "tsc --noEmit",
-    "lint": "bun run type-check"
+    "build": "npm run clean && tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui"
   },
-  "keywords": ["mcp", "ethereum", "viem", "blockchain", "web3", "model-context-protocol", "ai"],
+  "keywords": [
+    "mcp",
+    "ethereum",
+    "viem",
+    "blockchain",
+    "web3",
+    "ens",
+    "ethereum-name-service",
+    "model-context-protocol",
+    "ai"
+  ],
   "author": "Benjamin Hajnal <hajnalbenjamin@gmail.com>",
   "license": "MIT",
   "repository": {
@@ -33,16 +47,17 @@
     "url": "https://github.com/hajnalben/web3-tools-mcp/issues"
   },
   "homepage": "https://github.com/hajnalben/web3-tools-mcp#readme",
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^24.0.4"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
-  },
   "dependencies": {
     "@envio-dev/hypersync-client": "^0.6.5",
-    "@modelcontextprotocol/sdk": "^1.13.1",
-    "viem": "^2.31.4"
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "viem": "^2.31.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.23",
+    "@vitest/ui": "^3.2.4",
+    "dotenv": "^17.2.3",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
   }
 }

package/src/client.ts

@@ -0,0 +1,160 @@
+import { http, createPublicClient } from 'viem'
+import { arbitrum, base, celo, localhost, mainnet, optimism, polygon } from 'viem/chains'
+import type { ChainName, Config } from './types.js'
+
+// Enhanced RPC configuration with API keys
+function getRpcUrl(chainName: string, config: Config): string {
+  // Check for custom RPC URLs first
+  if (config.customRpcUrls?.[chainName]) {
+    return config.customRpcUrls[chainName]
+  }
+
+  // Enhanced RPC URLs with API keys
+  const enhancedRpcs: Record<string, string> = {
+    mainnet: config.alchemyApiKey
+      ? `https://eth-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
+      : config.infuraApiKey
+        ? `https://mainnet.infura.io/v3/${config.infuraApiKey}`
+        : 'https://eth.llamarpc.com',
+
+    base: config.alchemyApiKey
+      ? `https://base-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
+      : 'https://base.llamarpc.com',
+
+    arbitrum: config.alchemyApiKey
+      ? `https://arb-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
+      : config.infuraApiKey
+        ? `https://arbitrum-mainnet.infura.io/v3/${config.infuraApiKey}`
+        : 'https://arb1.arbitrum.io/rpc',
+
+    polygon: config.alchemyApiKey
+      ? `https://polygon-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
+      : config.infuraApiKey
+        ? `https://polygon-mainnet.infura.io/v3/${config.infuraApiKey}`
+        : 'https://polygon-rpc.com/',
+
+    optimism: config.alchemyApiKey
+      ? `https://opt-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
+      : config.infuraApiKey
+        ? `https://optimism-mainnet.infura.io/v3/${config.infuraApiKey}`
+        : 'https://mainnet.optimism.io',
+
+    celo: 'https://celo.drpc.org',
+    localhost: 'http://localhost:8545'
+  }
+
+  return enhancedRpcs[chainName] ?? 'https://eth.llamarpc.com'
+}
+
+// Supported chains with their RPC endpoints (now dynamic)
+export const CHAINS = (config: Config) => ({
+  mainnet: {
+    chain: mainnet,
+    get rpc() {
+      return getRpcUrl('mainnet', config)
+    }
+  },
+  base: {
+    chain: base,
+    get rpc() {
+      return getRpcUrl('base', config)
+    }
+  },
+  arbitrum: {
+    chain: arbitrum,
+    get rpc() {
+      return getRpcUrl('arbitrum', config)
+    }
+  },
+  polygon: {
+    chain: polygon,
+    get rpc() {
+      return getRpcUrl('polygon', config)
+    }
+  },
+  optimism: {
+    chain: optimism,
+    get rpc() {
+      return getRpcUrl('optimism', config)
+    }
+  },
+  celo: {
+    chain: celo,
+    get rpc() {
+      return getRpcUrl('celo', config)
+    }
+  },
+  localhost: {
+    chain: localhost,
+    get rpc() {
+      return getRpcUrl('localhost', config)
+    }
+  }
+})
+
+// Hypersync URLs for supported chains (localhost is not supported)
+export const HYPERSYNC_URLS: Partial<Record<ChainName, string>> = {
+  base: 'https://base.hypersync.xyz',
+  arbitrum: 'https://arbitrum.hypersync.xyz',
+  mainnet: 'https://eth.hypersync.xyz',
+  polygon: 'https://polygon.hypersync.xyz',
+  optimism: 'https://optimism.hypersync.xyz'
+  // celo and localhost are not supported by hypersync
+}
+
+export const SUPPORTED_CHAINS = ['mainnet', 'base', 'arbitrum', 'polygon', 'optimism', 'celo', 'localhost'] as const
+
+// Client manager
+export class ClientManager {
+  private clients: Map<ChainName, unknown> = new Map()
+  private config: Config
+
+  constructor(config: Config) {
+    this.config = config
+  }
+
+  getClient(chainName: ChainName) {
+    if (!this.clients.has(chainName)) {
+      const chains = CHAINS(this.config)
+      const { chain, rpc } = chains[chainName]
+      const client = createPublicClient({
+        chain,
+        transport: http(rpc)
+      })
+      this.clients.set(chainName, client)
+    }
+    const client = this.clients.get(chainName)
+    if (!client) {
+      throw new Error(`Failed to create client for chain: ${chainName}`)
+    }
+    return client as ReturnType<typeof createPublicClient>
+  }
+
+  getEtherscanDomain(chainName: ChainName): string {
+    const domains: Record<ChainName, string> = {
+      mainnet: 'etherscan.io',
+      base: 'basescan.org',
+      arbitrum: 'arbiscan.io',
+      polygon: 'polygonscan.com',
+      optimism: 'optimistic.etherscan.io',
+      celo: 'celoscan.io',
+      localhost: 'etherscan.io'
+    }
+    return domains[chainName] || 'etherscan.io'
+  }
+}
+
+// Export a global client manager instance
+let clientManager: ClientManager | null = null
+
+export function initializeClientManager(config: Config): ClientManager {
+  clientManager = new ClientManager(config)
+  return clientManager
+}
+
+export function getClientManager(): ClientManager {
+  if (!clientManager) {
+    throw new Error('Client manager not initialized')
+  }
+  return clientManager
+}

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}`)
+      }
+    }
+  )
+}