web3-tools-mcp 1.2.0 → 1.2.2

package/README.md

@@ -1,274 +1,137 @@
 # Web3 Tools MCP Server
 
-A Model Context Protocol (MCP) server that provides comprehensive blockchain interaction capabilities using [viem](https://viem.sh/), [Etherscan APIs](https://etherscan.io), and [Hypersync](https://docs.envio.dev/docs/HyperSync/overview). This server enables AI assistants to interact with multiple blockchain networks, query contract data, analyze transactions, and work with smart contracts with enhanced performance and reliability.
+A Model Context Protocol (MCP) server for blockchain interactions using [viem](https://viem.sh/), [Etherscan](https://etherscan.io), and [Hypersync](https://docs.envio.dev/docs/HyperSync/overview).
 
-## 📦 Installation & Setup
+## Features
 
-### Quick Start (Recommended)
-The easiest way to use this MCP server is with `npx` - no installation required! Add it directly to your MCP client configuration.
+- Multi-chain support (Ethereum, Base, Arbitrum, Polygon, Optimism, Celo)
+- Smart contract interactions (read functions, ABI retrieval, source code)
+- ENS resolution (names ↔ addresses, text records, avatars)
+- Token balances (native & ERC20, batch queries)
+- Event log queries with Hypersync acceleration
+- Transaction tracing and analysis
+- Storage slot reading with type decoding
 
-### MCP Client Configuration
-Add to your MCP client configuration (e.g., Claude Desktop `config.json`):
+## Quick Start
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "web3-tools": {
-        "command": "npx",
-        "args": [
-          "-y",
-          "web3-tools-mcp",
-          "--etherscan-api-key",
-          "YOUR_ETHERSCAN_API_KEY",
-          "--hypersync-api-key",
-          "YOUR_HYPERSYNC_API_KEY"
-        ]
-      }
-    }
-  }
-}
-```
-
-**Why npx?**
-- ✅ No global installation required
-- ✅ Always uses the latest version
-- ✅ Automatic dependency management
-- ✅ Works across different environments
-
-### Alternative: Global Installation
-If you prefer to install globally:
+### Claude Code
 ```bash
-npm install -g web3-tools-mcp
+claude mcp add --scope user --transport stdio web3-tools -- npx -y web3-tools-mcp
 ```
 
-Then use in your MCP config:
+### Claude Desktop
+Add to `config.json`:
 ```json
 {
-  "mcp": {
-    "servers": {
-      "web3-tools": {
-        "command": "web3-tools-mcp",
-        "args": [
-          "--etherscan-api-key", "YOUR_ETHERSCAN_API_KEY",
-          "--hypersync-api-key", "YOUR_HYPERSYNC_API_KEY"
-        ]
-      }
+  "mcpServers": {
+    "web3-tools": {
+      "command": "npx",
+      "args": ["-y", "web3-tools-mcp"]
     }
   }
 }
 ```
 
-### Command Line Usage
-You can also run the server directly:
-```bash
-# Using npx (recommended)
-npx web3-tools-mcp --etherscan-api-key YOUR_KEY --hypersync-api-key YOUR_KEY
-
-# Or if globally installed
-web3-tools-mcp --etherscan-api-key YOUR_KEY --hypersync-api-key YOUR_KEY
-```
-
-### Environment Variables
-Alternative to command line arguments:
-```bash
-export ETHERSCAN_API_KEY=your_etherscan_key_here
-export HYPERSYNC_API_KEY=your_hypersync_key_here
-export ALCHEMY_API_KEY=your_alchemy_key_here  # optional
-export INFURA_API_KEY=your_infura_key_here    # optional
-npx web3-tools-mcp
-```
-
-### API Keys
-- **Etherscan API Key**: Required for contract ABI fetching and verification status
-  - Get free API key at [etherscan.io/apis](https://etherscan.io/apis)
-- **Hypersync API Key**: Required for fast event log querying
-  - Get free API key at [hypersync.xyz](https://hypersync.xyz)
-- **Alchemy API Key**: Optional, provides enhanced RPC reliability
-  - Get free API key at [alchemy.com](https://alchemy.com)
-- **Infura API Key**: Optional, additional RPC provider for failover
-  - Get free API key at [infura.io](https://infura.io)
-
-## 🌟 Key Features
-
-- **Multi-chain Support**: Works with Ethereum mainnet, Base, Arbitrum, Polygon, Optimism, Celo, and localhost
-- **ENS Name Resolution**: Resolve ENS names to addresses, reverse lookup addresses to names, and query ENS records
-- **Smart Contract Interactions**: Call view/pure functions, get contract ABIs, and analyze contract bytecode
-- **Event Log Analysis**: Query and decode blockchain events with flexible filtering
-- **Token Operations**: Get native and ERC20 token balances for single or multiple addresses
-- **ABI Utilities**: Generate function, event, and error signatures from ABI definitions
-- **Batch Operations**: Execute multiple contract calls, balance queries, or ENS resolutions efficiently
-- **Transaction Analysis**: Trace transactions for detailed execution information
-- **Enhanced RPC Support**: Automatic failover between providers (Alchemy, Infura, public RPCs)
-- **Hypersync Integration**: Fast event log querying with fallback support
-
-## 🚀 Supported Blockchain Networks
-
-| Network | Chain ID | Default RPC | Hypersync Support |
-|---------|----------|-------------|------------------|
-| Ethereum Mainnet | 1 | ✅ | ✅ |
-| Base | 8453 | ✅ | ✅ |
-| Arbitrum One | 42161 | ✅ | ✅ |
-| Polygon | 137 | ✅ | ✅ |
-| Optimism | 10 | ✅ | ✅ |
-| Celo | 42220 | ✅ | ❌ |
-| Localhost | 31337 | ✅ | ❌ |
-
-## 🛠 Available Tools
-
-### 1. ABI Signature Tools
-
-#### `get_function_signature`
-Generate 4-byte function selectors from ABI definitions. Supports batch operations for multiple functions at once.
+## API Keys (Optional)
 
-#### `get_event_signature`
-Generate 32-byte event signatures (topic0) from ABI definitions. Supports batch operations for multiple events at once.
+All API keys are optional. The server uses public RPCs by default. Add keys to unlock additional features:
 
-#### `get_error_signature`
-Generate 4-byte error selectors from ABI definitions. Supports batch operations for multiple errors at once.
+**Configuration options:**
+- `--etherscan-api-key` or `ETHERSCAN_API_KEY` - Enables contract ABI/source retrieval
+- `--hypersync-api-key` or `HYPERSYNC_API_KEY` - Fast event queries (10-100x faster)
+- `--alchemy-api-key` or `ALCHEMY_API_KEY` - Enhanced RPC reliability
+- `--infura-api-key` or `INFURA_API_KEY` - Additional RPC provider
+- `--custom-rpc` - Custom RPC URLs as JSON
 
-### 2. Contract Interaction Tools
+**Get free API keys:**
+- Etherscan: [etherscan.io/apis](https://etherscan.io/apis)
+- Hypersync: [hypersync.xyz](https://hypersync.xyz)
+- Alchemy: [alchemy.com](https://alchemy.com)
+- Infura: [infura.io](https://infura.io)
 
-#### `call_contract_function`
-Call view/pure functions on smart contracts. Supports batch operations for executing multiple calls efficiently across different contracts and chains.
-
-#### `get_contract_abi`
-Get comprehensive contract information including ABI, proxy detection, compilation info, creation info, and verification status from Etherscan. Includes smart caching for performance.
-
-#### `get_contract_source_code`
-Retrieve verified contract source code from Etherscan with proxy support and flexible output options (full source, summary, or metadata only). Features smart caching.
-
-#### `get_contract_source_file`
-Retrieve specific source file from cached contract data. Use after calling `get_contract_source_code` with full source option.
-
-#### `is_contract`
-Check if an address is a smart contract or EOA (Externally Owned Account). Returns contract status and bytecode length.
-
-### 3. ENS (Ethereum Name Service) Tools
-
-#### `resolve_ens_name`
-Resolve an ENS name to its Ethereum address. ENS names are human-readable identifiers (like vitalik.eth) that resolve to Ethereum addresses. Returns the resolved address or null if not found.
-
-#### `reverse_resolve_ens`
-Reverse resolve an Ethereum address to its primary ENS name. Returns the ENS name if the address has set a reverse record, useful for displaying human-readable names for addresses.
-
-#### `get_ens_text_record`
-Retrieve text records from an ENS name. Common text record keys include:
-- `avatar`: Avatar image URL
-- `description`: Description text
-- `email`: Email address
-- `url`: Website URL
-- `com.twitter`: Twitter handle
-- `com.github`: GitHub username
-
-#### `get_ens_avatar`
-Get the avatar URI for an ENS name. Returns the avatar URL if set, which can be an HTTPS URL, IPFS hash, or NFT reference.
-
-#### `batch_resolve_ens_names`
-Resolve multiple ENS names to addresses in a single batch operation for improved efficiency. Returns results for all names with success/failure status.
+**Example with API keys:**
+```bash
+# Claude Code
+claude mcp add --scope user --transport stdio web3-tools -- npx -y web3-tools-mcp --etherscan-api-key YOUR_KEY --hypersync-api-key YOUR_KEY
 
-### 4. Balance Query Tools
+# Environment variables
+export ETHERSCAN_API_KEY=your_key
+export HYPERSYNC_API_KEY=your_key
+npx web3-tools-mcp
+```
 
-#### `get_balance`
-Get native or ERC20 token balances for single or multiple addresses efficiently. Supports batch operations for optimal performance. Omit `tokenAddress` for native balance, include it for ERC20 tokens.
+## Supported Networks
 
-### 5. Event Log Tools
+| Network | Chain ID | Hypersync |
+|---------|----------|-----------|
+| Ethereum | 1 | ✅ |
+| Base | 8453 | ✅ |
+| Arbitrum | 42161 | ✅ |
+| Polygon | 137 | ✅ |
+| Optimism | 10 | ✅ |
+| Celo | 42220 | ❌ |
+| Localhost | 31337 | ❌ |
 
-#### `get_logs`
-Query contract events with decoded output and parameter filtering. Automatically falls back to Hypersync for supported chains when needed. Supports filtering by contract address, block range, and indexed event parameters.
+## Available Tools
 
-### 6. Advanced Tools
+### Signatures
+- `get_function_signature` - Generate 4-byte function selectors
+- `get_event_signature` - Generate 32-byte event topic0 hashes
+- `get_error_signature` - Generate 4-byte error selectors
 
-#### `get_storage_at`
-Read raw storage data from a contract with ABI-based decoding. Supports various types like uint256, address, bool, bytes32, etc.
+### Contract Info
+- `get_contract_abi` - Get ABI with proxy detection and verification status
+- `get_contract_source_code` - Get verified source code with proxy support
+- `get_contract_source_file` - Retrieve specific source file from cache
+- `is_contract` - Check if address is contract or EOA
 
-#### `get_block_info`
-Get comprehensive block information including timestamp, hash, parent hash, and formatted dates. Defaults to latest block if not specified.
+### Contract Interaction
+- `call_contract_function` - Call view/pure functions (supports batch)
 
-#### `trace_transaction`
-Trace a transaction to see detailed execution information including internal calls, state changes, and gas usage. Supports multiple trace types: `trace` (call tree), `vmTrace` (VM execution), `stateDiff` (state changes).
+### ENS
+- `resolve_ens_name` - ENS name → address
+- `reverse_resolve_ens` - Address → ENS name
+- `get_ens_text_record` - Get text records (avatar, email, twitter, etc.)
+- `get_ens_avatar` - Get avatar URI
+- `batch_resolve_ens_names` - Batch resolve multiple names
 
-## ⚙️ Configuration
+### Balances
+- `get_balance` - Get native or ERC20 balances (supports batch)
 
-The server supports multiple configuration options through environment variables or command-line arguments:
+### Events & Logs
+- `get_logs` - Query and decode events with Hypersync fallback
 
-### API Keys
-- `ETHERSCAN_API_KEY` / `--etherscan-api-key`: For contract ABI retrieval
-- `ALCHEMY_API_KEY` / `--alchemy-api-key`: Enhanced RPC endpoints
-- `INFURA_API_KEY` / `--infura-api-key`: Alternative RPC provider
-- `HYPERSYNC_API_KEY` / `--hypersync-api-key`: Fast event log querying
+### Advanced
+- `get_storage_at` - Read storage slots with type decoding
+- `get_block_info` - Get block data (timestamp, hash, etc.)
+- `trace_transaction` - Trace execution (call tree, VM, state diff)
 
-### Custom RPC URLs
-- `--custom-rpc`: JSON object with custom RPC URLs per chain
+## Advanced Configuration
 
-**Example:**
+### Custom RPC
 ```bash
-npx web3-tools-mcp --custom-rpc '{"mainnet": "https://my-custom-rpc.com", "base": "https://base-rpc.com"}'
+npx web3-tools-mcp --custom-rpc '{"mainnet":"https://my-rpc.com","base":"https://base-rpc.com"}'
 ```
 
-## 🔧 Technical Features
-
-### Enhanced RPC Configuration
-- **Automatic Provider Selection**: Prioritizes Alchemy → Infura → Public RPCs
-- **Custom RPC Support**: Override default providers with custom endpoints
-- **Failover Mechanisms**: Graceful handling of RPC failures
-
-### Hypersync Integration
-- **Fast Event Queries**: Significantly faster than traditional RPC for event logs
-- **Automatic Fallback**: Falls back to regular viem when Hypersync fails
-- **Selective Support**: Available for mainnet, Base, Arbitrum, Polygon, and Optimism
-
-### Data Type Handling
-- **BigInt Serialization**: Automatic conversion of BigInt values to strings for JSON compatibility
-- **Type Conversion**: Smart conversion of arguments based on ABI parameter types
-- **Error Handling**: Comprehensive error messages and graceful failure handling
+### RPC Failover
+Automatic provider selection: Alchemy → Infura → Public RPCs
 
 ### Batch Operations
-- **Multicall Support**: Execute multiple contract calls efficiently
-- **Balance Batching**: Query multiple balances in parallel
-- **Result Aggregation**: Organized results with success/failure tracking
-
-## 📋 Requirements
-
-- **Runtime**: Node.js v20.0.0 or higher
-- **Package Manager**: npm (recommended) or yarn/pnpm
-- **Dependencies**: viem, @envio-dev/hypersync-client, @modelcontextprotocol/sdk
-- **Network Access**: Internet connection for blockchain RPC calls
+Many tools support batching for improved efficiency (contract calls, balances, ENS resolution).
 
-## 🧪 Testing
+## Requirements
 
-The server includes a comprehensive test suite with 70 tests covering all functionality:
+- Node.js ≥ 20.0.0
+- Internet connection for RPC calls
 
-### Running Tests
+## Testing
 
 ```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with UI
-npm run test:ui
+npm test              # Run all tests
+npm run test:watch   # Watch mode
+npm run test:ui      # UI mode
 ```
 
-## 🔗 Related Tools
-
-This server is designed to work seamlessly with other blockchain development tools and can be used alongside:
-- Block explorers (Etherscan, Basescan, etc.)
-- DeFi protocols analysis
-- Smart contract development workflows
-- Token analysis and portfolio tracking
-- Event monitoring and alerting systems
-
-## 🎯 Use Cases
-
-- **Smart Contract Analysis**: Analyze contract behavior, storage, and interactions
-- **Token Research**: Query token balances, transfers, and metadata
-- **DeFi Protocol Monitoring**: Track liquidity, swaps, and protocol events
-- **Transaction Analysis**: Understand complex transaction flows and internal calls
-- **Multi-chain Portfolio Tracking**: Monitor assets across different networks
-- **Event-driven Analysis**: Build insights from blockchain event data
-- **Contract Verification**: Check contract deployment and proxy patterns
+## License
 
-This MCP server provides a comprehensive toolkit for blockchain interaction, making it easy for AI assistants to help users analyze, query, and understand blockchain data across multiple networks.
+MIT

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "web3-tools-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Model Context Protocol server for blockchain interactions using viem, Etherscan, and Hypersync",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "bin": {
-    "web3-tools-mcp": "dist/index.js"
+    "web3-tools-mcp": "dist/src/index.js"
   },
   "files": [
-    "dist",
+    "dist/src",
     "README.md",
     "LICENSE",
     "src"

package/dist/package.json

@@ -1,63 +0,0 @@
-{
-    "name": "web3-tools-mcp",
-    "version": "1.2.0",
-    "description": "Model Context Protocol server for blockchain interactions using viem, Etherscan, and Hypersync",
-    "type": "module",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "bin": {
-        "web3-tools-mcp": "dist/index.js"
-    },
-    "files": [
-        "dist",
-        "README.md",
-        "LICENSE",
-        "src"
-    ],
-    "engines": {
-        "node": ">=20.0.0"
-    },
-    "scripts": {
-        "clean": "rm -rf dist",
-        "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",
-        "ens",
-        "ethereum-name-service",
-        "model-context-protocol",
-        "ai"
-    ],
-    "author": "Benjamin Hajnal <hajnalbenjamin@gmail.com>",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/hajnalben/web3-tools-mcp.git"
-    },
-    "bugs": {
-        "url": "https://github.com/hajnalben/web3-tools-mcp/issues"
-    },
-    "homepage": "https://github.com/hajnalben/web3-tools-mcp#readme",
-    "dependencies": {
-        "@envio-dev/hypersync-client": "^0.6.5",
-        "@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/dist/test/tools/advanced.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=advanced.test.d.ts.map

package/dist/test/tools/advanced.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"advanced.test.d.ts","sourceRoot":"","sources":["../../../test/tools/advanced.test.ts"],"names":[],"mappings":""}