web3-tools-mcp 1.0.1 → 1.2.0

package/README.md

@@ -92,11 +92,12 @@ npx web3-tools-mcp
 ## 🌟 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 or balance queries efficiently
+- **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
@@ -118,173 +119,74 @@ npx web3-tools-mcp
 ### 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
+### 3. ENS (Ethereum Name Service) Tools
 
-#### `get_balance`
-Get native token balance for an address.
+#### `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.
 
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `address` (string): Address to check
-- `blockNumber` (string, optional): Specific block number
+#### `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_token_balance`
-Get ERC20/ERC777 token balance for an address.
+#### `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
 
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `tokenAddress` (string): Token contract address
-- `holderAddress` (string): Address to check balance for
-- `blockNumber` (string, optional): Specific block number
+#### `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_native_balances`
-Get native token balances for multiple addresses in a single call.
+#### `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.
 
-**Parameters:**
-- `chain` (enum): Blockchain network
-- `addresses` (array): Array of addresses to check
-- `blockNumber` (string, optional): Specific block number
+### 4. Balance Query Tools
 
-#### `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_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.
 
-### 4. Event Log Tools
+### 5. 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"
-    }
-  }
-}
-```
-
-### 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
+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.
 
 ### 6. 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
 
@@ -301,7 +203,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
@@ -326,114 +228,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
-
-# Run tests with coverage
-bun run test:coverage
-
-# Run type checking
-bun run lint
-```
-
-### Test Coverage
-
-The test suite covers:
+npm run test:watch
 
-- **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

package/dist/package.json

@@ -0,0 +1,63 @@
+{
+    "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"
+    }
+}