web3-tools-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,37 +1,48 @@
-# Viem MCP Server
+# Web3 Tools MCP Server
 
-A Model Context Protocol (MCP) server that provides comprehensive blockchain interaction capabilities using the [viem](https://viem.sh/) TypeScript library. This server enables AI assistants to interact with multiple blockchain networks, query contract data, analyze transactions, and work with smart contracts.
+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.
 
-## 📦 Installation
+## 📦 Installation & Setup
 
-### NPM (Recommended)
-```bash
-npm install -g web3-tools-mcp
-```
+### 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.
 
-### Usage
-After installation, you can run the server directly:
-```bash
-web3-tools-mcp
-```
+### MCP Client Configuration
+Add to your MCP client configuration (e.g., Claude Desktop `config.json`):
 
-Or with configuration options:
-```bash
-web3-tools-mcp --etherscan-api-key YOUR_KEY --alchemy-api-key YOUR_KEY
+```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"
+        ]
+      }
+    }
+  }
+}
 ```
 
-### Environment Variables
-You can also set configuration via environment variables:
+**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:
 ```bash
-export ETHERSCAN_API_KEY=your_key_here
-export ALCHEMY_API_KEY=your_key_here
-export INFURA_API_KEY=your_key_here
-export HYPERSYNC_API_KEY=your_key_here
-web3-tools-mcp
+npm install -g web3-tools-mcp
 ```
 
-### MCP Client Configuration
-Add to your MCP client configuration (e.g., Claude Desktop):
+Then use in your MCP config:
 ```json
 {
   "mcp": {
@@ -39,8 +50,8 @@ Add to your MCP client configuration (e.g., Claude Desktop):
       "web3-tools": {
         "command": "web3-tools-mcp",
         "args": [
-          "--etherscan-api-key", "YOUR_ETHERSCAN_KEY",
-          "--alchemy-api-key", "YOUR_ALCHEMY_KEY"
+          "--etherscan-api-key", "YOUR_ETHERSCAN_API_KEY",
+          "--hypersync-api-key", "YOUR_HYPERSYNC_API_KEY"
         ]
       }
     }
@@ -48,6 +59,36 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 }
 ```
 
+### 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
@@ -77,173 +118,51 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 ### 1. ABI Signature Tools
 
 #### `get_function_signature`
-Generate 4-byte function selectors from ABI definitions.
-
-**Parameters:**
-- `functionAbi` (string): Function ABI (e.g., `"function transfer(address to, uint256 amount)"`)
-
-**Example:**
-```json
-{
-  "name": "get_function_signature",
-  "arguments": {
-    "functionAbi": "function balanceOf(address owner) view returns (uint256)"
-  }
-}
-```
+Generate 4-byte function selectors from ABI definitions. Supports batch operations for multiple functions at once.
 
 #### `get_event_signature`
-Generate 32-byte event signatures (topic0) from ABI definitions.
-
-**Parameters:**
-- `eventAbi` (string): Event ABI (e.g., `"event Transfer(address indexed from, address indexed to, uint256 value)"`)
+Generate 32-byte event signatures (topic0) from ABI definitions. Supports batch operations for multiple events at once.
 
 #### `get_error_signature`
-Generate 4-byte error selectors from ABI definitions.
-
-**Parameters:**
-- `errorAbi` (string): Error ABI (e.g., `"error InsufficientBalance(uint256 available, uint256 required)"`)
+Generate 4-byte error selectors from ABI definitions. Supports batch operations for multiple errors at once.
 
 ### 2. Contract Interaction Tools
 
 #### `call_contract_function`
-Call view/pure functions on smart contracts.
-
-**Parameters:**
-- `chain` (enum): Blockchain network (`mainnet`, `base`, `arbitrum`, `polygon`, `optimism`, `celo`, `localhost`)
-- `contractAddress` (string): Contract address to call
-- `functionAbi` (string): Function ABI definition
-- `args` (array, optional): Function arguments
-- `blockNumber` (string, optional): Specific block number to query
-
-**Example:**
-```json
-{
-  "name": "call_contract_function",
-  "arguments": {
-    "chain": "mainnet",
-    "contractAddress": "0xA0b86a33E6441c1e4e9c08975a0c8246e8dB8C4F",
-    "functionAbi": "function balanceOf(address owner) view returns (uint256)",
-    "args": ["0x742d35Cc6cF36C3e0C37d3f6D1D5e4f2C8F3E8A9"]
-  }
-}
-```
+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, and verification status from Etherscan.
+Get comprehensive contract information including ABI, proxy detection, compilation info, creation info, and verification status from Etherscan. Includes smart caching for performance.
 
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `address` (string): Contract address
+#### `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.
 
-#### `is_contract`
-Check if an address is a smart contract or EOA (Externally Owned Account).
+#### `get_contract_source_file`
+Retrieve specific source file from cached contract data. Use after calling `get_contract_source_code` with full source option.
 
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `address` (string): Address to check
+#### `is_contract`
+Check if an address is a smart contract or EOA (Externally Owned Account). Returns contract status and bytecode length.
 
 ### 3. Balance Query Tools
 
 #### `get_balance`
-Get native token balance for an address.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `address` (string): Address to check
-- `blockNumber` (string, optional): Specific block number
-
-#### `get_token_balance`
-Get ERC20/ERC777 token balance for an address.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `tokenAddress` (string): Token contract address
-- `holderAddress` (string): Address to check balance for
-- `blockNumber` (string, optional): Specific block number
-
-#### `batch_native_balances`
-Get native token balances for multiple addresses in a single call.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `addresses` (array): Array of addresses to check
-- `blockNumber` (string, optional): Specific block number
-
-#### `batch_token_balances`
-Get multiple token balances for multiple addresses efficiently.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `queries` (array): Array of balance queries with `tokenAddress`, `holderAddress`, and optional `label`
-- `blockNumber` (string, optional): Specific block number
+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.
 
 ### 4. Event Log Tools
 
 #### `get_logs`
-Query contract events with decoded output and parameter filtering. Automatically falls back to Hypersync for supported chains when needed.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `eventAbi` (string): Event ABI definition for decoding
-- `address` (string, optional): Contract address to filter logs
-- `fromBlock` (string, optional): Start block number
-- `toBlock` (string, optional): End block number
-- `eventArgs` (object, optional): Filter by indexed event parameters
-
-**Example:**
-```json
-{
-  "name": "get_logs",
-  "arguments": {
-    "chain": "mainnet",
-    "eventAbi": "event Transfer(address indexed from, address indexed to, uint256 value)",
-    "address": "0xA0b86a33E6441c1e4e9c08975a0c8246e8dB8C4F",
-    "fromBlock": "18000000",
-    "toBlock": "18001000",
-    "eventArgs": {
-      "from": "0x742d35Cc6cF36C3e0C37d3f6D1D5e4f2C8F3E8A9"
-    }
-  }
-}
-```
+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.
 
-### 5. Batch Operations
-
-#### `batch_contract_calls`
-Execute multiple contract calls in a single batch operation.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `calls` (array): Array of contract calls with `contractAddress`, `functionAbi`, `args`, and optional `label`
-- `blockNumber` (string, optional): Specific block number
-
-### 6. Advanced Tools
+### 5. Advanced Tools
 
 #### `get_storage_at`
-Read raw storage data from a contract with ABI-based decoding.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `address` (string): Contract address
-- `slot` (string): Storage slot to read (hex string)
-- `abiType` (string): ABI type for decoding (`uint256`, `address`, `bool`, `bytes32`, etc.)
-- `blockNumber` (string, optional): Specific block number
+Read raw storage data from a contract with ABI-based decoding. Supports various types like uint256, address, bool, bytes32, etc.
 
 #### `get_block_info`
-Get comprehensive block information including timestamp, hash, and formatted dates.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `blockNumber` (string, optional): Block number to query (defaults to latest)
+Get comprehensive block information including timestamp, hash, parent hash, and formatted dates. Defaults to latest block if not specified.
 
 #### `trace_transaction`
-Trace a transaction to see detailed execution information including internal calls, state changes, and gas usage.
-
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `transactionHash` (string): Transaction hash to trace
-- `traceType` (enum, optional): Type of trace (`trace`, `vmTrace`, `stateDiff`)
+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).
 
 ## ⚙️ Configuration
 
@@ -260,7 +179,7 @@ The server supports multiple configuration options through environment variables
 
 **Example:**
 ```bash
-bun index.ts --custom-rpc '{"mainnet": "https://my-custom-rpc.com", "base": "https://base-rpc.com"}'
+npx web3-tools-mcp --custom-rpc '{"mainnet": "https://my-custom-rpc.com", "base": "https://base-rpc.com"}'
 ```
 
 ## 🔧 Technical Features
@@ -285,114 +204,28 @@ bun index.ts --custom-rpc '{"mainnet": "https://my-custom-rpc.com", "base": "htt
 - **Balance Batching**: Query multiple balances in parallel
 - **Result Aggregation**: Organized results with success/failure tracking
 
-## 🚀 Usage Examples
-
-### Basic Contract Call
-```json
-{
-  "name": "call_contract_function",
-  "arguments": {
-    "chain": "mainnet",
-    "contractAddress": "0xA0b86a33E6441c1e4e9c08975a0c8246e8dB8C4F",
-    "functionAbi": "function name() view returns (string)",
-    "args": []
-  }
-}
-```
-
-### Event Log Analysis
-```json
-{
-  "name": "get_logs",
-  "arguments": {
-    "chain": "base",
-    "eventAbi": "event Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)",
-    "fromBlock": "10000000",
-    "toBlock": "latest"
-  }
-}
-```
-
-### Batch Balance Queries
-```json
-{
-  "name": "batch_token_balances",
-  "arguments": {
-    "chain": "mainnet",
-    "queries": [
-      {
-        "tokenAddress": "0xA0b86a33E6441c1e4e9c08975a0c8246e8dB8C4F",
-        "holderAddress": "0x742d35Cc6cF36C3e0C37d3f6D1D5e4f2C8F3E8A9",
-        "label": "USDC Balance"
-      },
-      {
-        "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
-        "holderAddress": "0x742d35Cc6cF36C3e0C37d3f6D1D5e4f2C8F3E8A9",
-        "label": "WETH Balance"
-      }
-    ]
-  }
-}
-```
-
 ## 📋 Requirements
 
-- **Runtime**: Bun (recommended) or Node.js
+- **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
 
 ## 🧪 Testing
 
-The server includes a comprehensive test suite that validates all functionality:
+The server includes a comprehensive test suite with 70 tests covering all functionality:
 
 ### Running Tests
 
 ```bash
 # Run all tests
-bun test
+npm test
 
 # Run tests in watch mode
-bun run test:watch
+npm run test:watch
 
-# Run tests with coverage
-bun run test:coverage
-
-# Run type checking
-bun run lint
-```
-
-### Test Coverage
-
-The test suite covers:
-
-- **ABI Signature Generation**: Function, event, and error signatures
-- **Contract Interactions**: Detecting contracts vs EOAs, calling view functions
-- **Balance Queries**: Native and token balances, batch operations
-- **Block Information**: Latest and historical block data
-- **Multi-chain Support**: Testing across different networks
-- **Error Handling**: Invalid inputs, network failures, malformed requests
-- **Data Type Handling**: BigInt serialization, address normalization
-- **Performance**: Batch vs individual operation timing
-
-### Example Usage
-
-```bash
-# Run example demonstrations
-bun run examples
-```
-
-The examples file demonstrates:
-- Function signature generation
-- Contract vs EOA detection
-- Smart contract function calls
-- Balance queries
-- Block information retrieval
-
-### Test Structure
-
-```
-test.ts                 # Main test suite
-examples.ts            # Usage examples and demonstrations
+# Run tests with UI
+npm run test:ui
 ```
 
 ## 🔗 Related Tools