feat: adding ENS support

Author: vcart

README.md

@@ -33,6 +33,7 @@ The MCP EVM Server leverages the Model Context Protocol to provide blockchain op
 - Transferring tokens (native, ERC20, ERC721, ERC1155)
 - Querying token metadata and balances
 - Chain-specific operations across 30+ EVM networks
+- ENS name resolution for all address parameters
 
 All operations are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use blockchain functionality.
 
@@ -45,6 +46,7 @@ All operations are exposed through a consistent interface of MCP tools and resou
 - **Block data** access by number, hash, or latest
 - **Transaction details** and receipts with decoded logs
 - **Address balances** for native tokens and all token standards
+- **ENS resolution** for human-readable Ethereum addresses
 
 ### Token Operations
 
@@ -195,22 +197,22 @@ bun dev:http
 
 Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
 
-### Example: Getting a Token Balance
+### Example: Getting a Token Balance with ENS
 
 ```javascript
-// Example of using the MCP client to check a token balance
+// Example of using the MCP client to check a token balance using ENS
 const mcp = new McpClient("http://localhost:3000");
 
 const result = await mcp.invokeTool("get-token-balance", {
   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
-  ownerAddress: "0x1234567890abcdef1234567890abcdef12345678",
+  ownerAddress: "vitalik.eth", // ENS name instead of address
   network: "ethereum"
 });
 
 console.log(result);
 // {
 //   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
-//   owner: "0x1234567890abcdef1234567890abcdef12345678",
+//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
 //   network: "ethereum",
 //   raw: "1000000000",
 //   formatted: "1000",

src/core/operations/balance.ts

@@ -7,6 +7,7 @@ import {
 } from 'viem';
 import { getPublicClient } from './clients.js';
 import { readContract } from './contracts.js';
+import { resolveAddress } from './ens.js';
 
 // Standard ERC20 ABI (minimal for reading)
 const erc20Abi = [
@@ -66,27 +67,37 @@ const erc1155Abi = [
 ] as const;
 
 /**
- * Get the ETH balance of an address for a specific network
+ * Get the ETH balance for an address
+ * @param addressOrEns Ethereum address or ENS name
+ * @param network Network name or chain ID
+ * @returns Balance in wei and ether
  */
 export async function getETHBalance(
-  address: Address, 
+  addressOrEns: string, 
   network = 'ethereum'
 ): Promise<{ wei: bigint; ether: string }> {
+  // Resolve ENS name to address if needed
+  const address = await resolveAddress(addressOrEns, network);
+  
   const client = getPublicClient(network);
-  const balanceWei = await client.getBalance({ address });
+  const balance = await client.getBalance({ address });
 
   return {
-    wei: balanceWei,
-    ether: formatEther(balanceWei)
+    wei: balance,
+    ether: formatEther(balance)
   };
 }
 
 /**
- * Get the ERC20 token balance of an address for a specific network
+ * Get the balance of an ERC20 token for an address
+ * @param tokenAddressOrEns Token contract address or ENS name
+ * @param ownerAddressOrEns Owner address or ENS name
+ * @param network Network name or chain ID
+ * @returns Token balance with formatting information
  */
 export async function getERC20Balance(
-  tokenAddress: Address,
-  ownerAddress: Address,
+  tokenAddressOrEns: string,
+  ownerAddressOrEns: string,
   network = 'ethereum'
 ): Promise<{
   raw: bigint;
@@ -96,6 +107,10 @@ export async function getERC20Balance(
     decimals: number;
   }
 }> {
+  // Resolve ENS names to addresses if needed
+  const tokenAddress = await resolveAddress(tokenAddressOrEns, network);
+  const ownerAddress = await resolveAddress(ownerAddressOrEns, network);
+  
   const publicClient = getPublicClient(network);
 
   const contract = getContract({
@@ -122,65 +137,83 @@ export async function getERC20Balance(
 
 /**
  * Check if an address owns a specific NFT
+ * @param tokenAddressOrEns NFT contract address or ENS name
+ * @param ownerAddressOrEns Owner address or ENS name
+ * @param tokenId Token ID to check
+ * @param network Network name or chain ID
+ * @returns True if the address owns the NFT
  */
 export async function isNFTOwner(
-  tokenAddress: Address,
-  ownerAddress: Address,
+  tokenAddressOrEns: string,
+  ownerAddressOrEns: string,
   tokenId: bigint,
   network = 'ethereum'
 ): Promise<boolean> {
-  const publicClient = getPublicClient(network);
-
-  const contract = getContract({
-    address: tokenAddress,
-    abi: erc721Abi,
-    client: publicClient,
-  });
-
+  // Resolve ENS names to addresses if needed
+  const tokenAddress = await resolveAddress(tokenAddressOrEns, network);
+  const ownerAddress = await resolveAddress(ownerAddressOrEns, network);
+  
   try {
-    const owner = await contract.read.ownerOf([tokenId]);
-    return owner.toLowerCase() === ownerAddress.toLowerCase();
-  } catch (error) {
-    // If the token doesn't exist or there's an error, return false
+    const actualOwner = await readContract({
+      address: tokenAddress,
+      abi: erc721Abi,
+      functionName: 'ownerOf',
+      args: [tokenId]
+    }, network) as Address;
+    
+    return actualOwner.toLowerCase() === ownerAddress.toLowerCase();
+  } catch (error: any) {
+    console.error(`Error checking NFT ownership: ${error.message}`);
     return false;
   }
 }
 
 /**
- * Get ERC721 NFT balance for an address (number of NFTs owned)
+ * Get the number of NFTs owned by an address for a specific collection
+ * @param tokenAddressOrEns NFT contract address or ENS name
+ * @param ownerAddressOrEns Owner address or ENS name
+ * @param network Network name or chain ID
+ * @returns Number of NFTs owned
  */
 export async function getERC721Balance(
-  tokenAddress: Address,
-  ownerAddress: Address,
+  tokenAddressOrEns: string,
+  ownerAddressOrEns: string,
   network = 'ethereum'
 ): Promise<bigint> {
-  const publicClient = getPublicClient(network);
-
-  const contract = getContract({
+  // Resolve ENS names to addresses if needed
+  const tokenAddress = await resolveAddress(tokenAddressOrEns, network);
+  const ownerAddress = await resolveAddress(ownerAddressOrEns, network);
+  
+  return readContract({
     address: tokenAddress,
     abi: erc721Abi,
-    client: publicClient,
-  });
-
-  return contract.read.balanceOf([ownerAddress]);
+    functionName: 'balanceOf',
+    args: [ownerAddress]
+  }, network) as Promise<bigint>;
 }
 
 /**
- * Get ERC1155 token balance
+ * Get the balance of an ERC1155 token for an address
+ * @param tokenAddressOrEns ERC1155 contract address or ENS name
+ * @param ownerAddressOrEns Owner address or ENS name
+ * @param tokenId Token ID to check
+ * @param network Network name or chain ID
+ * @returns Token balance
  */
 export async function getERC1155Balance(
-  tokenAddress: Address,
-  ownerAddress: Address,
+  tokenAddressOrEns: string,
+  ownerAddressOrEns: string,
   tokenId: bigint,
   network = 'ethereum'
 ): Promise<bigint> {
-  const publicClient = getPublicClient(network);
-
-  const contract = getContract({
+  // Resolve ENS names to addresses if needed
+  const tokenAddress = await resolveAddress(tokenAddressOrEns, network);
+  const ownerAddress = await resolveAddress(ownerAddressOrEns, network);
+  
+  return readContract({
     address: tokenAddress,
     abi: erc1155Abi,
-    client: publicClient,
-  });
-
-  return contract.read.balanceOf([ownerAddress, tokenId]);
+    functionName: 'balanceOf',
+    args: [ownerAddress, tokenId]
+  }, network) as Promise<bigint>;
 } 

src/core/operations/contracts.ts

@@ -7,6 +7,7 @@ import {
   type Log
 } from 'viem';
 import { getPublicClient, getWalletClient } from './clients.js';
+import { resolveAddress } from './ens.js';
 
 /**
  * Read from a contract for a specific network
@@ -38,8 +39,14 @@ export async function getLogs(params: GetLogsParameters, network = 'ethereum'):
 
 /**
  * Check if an address is a contract
+ * @param addressOrEns Address or ENS name to check
+ * @param network Network name or chain ID
+ * @returns True if the address is a contract, false if it's an EOA
  */
-export async function isContract(address: Address, network = 'ethereum'): Promise<boolean> {
+export async function isContract(addressOrEns: string, network = 'ethereum'): Promise<boolean> {
+  // Resolve ENS name to address if needed
+  const address = await resolveAddress(addressOrEns, network);
+  
   const client = getPublicClient(network);
   const code = await client.getBytecode({ address });
   return code !== undefined && code !== '0x';

src/core/operations/ens.ts

@@ -0,0 +1,46 @@
+import { normalize } from 'viem/ens';
+import { getPublicClient } from './clients.js';
+import { type Address } from 'viem';
+
+/**
+ * Resolves an ENS name to an Ethereum address or returns the original address if it's already valid
+ * @param addressOrEns An Ethereum address or ENS name
+ * @param network The network to use for ENS resolution (defaults to Ethereum mainnet)
+ * @returns The resolved Ethereum address
+ */
+export async function resolveAddress(
+  addressOrEns: string,
+  network = 'ethereum'
+): Promise<Address> {
+  // If it's already a valid Ethereum address (0x followed by 40 hex chars), return it
+  if (/^0x[a-fA-F0-9]{40}$/.test(addressOrEns)) {
+    return addressOrEns as Address;
+  }
+
+  // If it looks like an ENS name (contains a dot), try to resolve it
+  if (addressOrEns.includes('.')) {
+    try {
+      // Normalize the ENS name first
+      const normalizedEns = normalize(addressOrEns);
+      
+      // Get the public client for the network
+      const publicClient = getPublicClient(network);
+      
+      // Resolve the ENS name to an address
+      const address = await publicClient.getEnsAddress({
+        name: normalizedEns,
+      });
+      
+      if (!address) {
+        throw new Error(`ENS name ${addressOrEns} could not be resolved to an address`);
+      }
+      
+      return address;
+    } catch (error: any) {
+      throw new Error(`Failed to resolve ENS name ${addressOrEns}: ${error.message}`);
+    }
+  }
+  
+  // If it's neither a valid address nor an ENS name, throw an error
+  throw new Error(`Invalid address or ENS name: ${addressOrEns}`);
+} 

src/core/operations/index.ts

@@ -6,6 +6,7 @@ export * from './blocks.js';
 export * from './transactions.js';
 export * from './contracts.js';
 export * from './tokens.js';
+export * from './ens.js';
 export { utils as helpers } from './utils.js';
 
 // Re-export common types for convenience