MCP Ethers Wallet

Instructions

Implementation Reference

• src/tools/erc20.ts:72-106 (handler)

  Primary MCP tool handler for getERC20TokenInfo. Maps parameters, calls ethersService, formats and returns token information or error.

      async (params) => {
        // Map deprecated parameters
        const mapped = mapParameters(params);
        
        try {
          const contractAddr = mapped.contractAddress || params.tokenAddress;
          if (!contractAddr) {
            throw new Error('Either contractAddress or tokenAddress must be provided');
          }
          const tokenInfo = await ethersService.getERC20TokenInfo(
            contractAddr,
            mapped.provider,
            mapped.chainId
          );
          
          return {
            content: [{ 
              type: "text", 
              text: `Token Information:
  Name: ${tokenInfo.name}
  Symbol: ${tokenInfo.symbol}
  Decimals: ${tokenInfo.decimals}
  Total Supply: ${tokenInfo.totalSupply}`
            }]
          };
        } catch (error) {
          return {
            isError: true,
            content: [{ 
              type: "text", 
              text: `Error getting token information: ${error instanceof Error ? error.message : String(error)}`
            }]
          };
        }
      }

• src/tools/definitions/erc20.ts:9-30 (schema)

  Tool schema definition including name, description, and inputSchema for MCP tool registry.

  {
    name: "getERC20TokenInfo",
    description: "Get basic information about an ERC20 token including name, symbol, decimals, and total supply",
    inputSchema: {
      type: "object",
      properties: {
        tokenAddress: {
          type: "string",
          description: "The address of the ERC20 token contract"
        },
        provider: {
          type: "string",
          description: "Optional. Either a network name or custom RPC URL. Use getSupportedNetworks to get a list of supported networks."
        },
        chainId: {
          type: "number",
          description: "Optional. The chain ID to use. If provided with a named network and they don't match, the RPC's chain ID will be used."
        }
      },
      required: ["tokenAddress"]
    }
  },

• src/tools/erc20.ts:64-107 (registration)

  MCP server.tool registration for getERC20TokenInfo with zod input schema, description, and inline handler function.

      "getERC20TokenInfo",
      "Get detailed information about an ERC20 token including its name, symbol, decimals, and total supply. Requires the contract address of the token.",
      {
        contractAddress: contractAddressSchema,
        tokenAddress: tokenAddressSchema.optional(),  // Deprecated
        provider: providerSchema,
        chainId: chainIdSchema
      },
      async (params) => {
        // Map deprecated parameters
        const mapped = mapParameters(params);
        
        try {
          const contractAddr = mapped.contractAddress || params.tokenAddress;
          if (!contractAddr) {
            throw new Error('Either contractAddress or tokenAddress must be provided');
          }
          const tokenInfo = await ethersService.getERC20TokenInfo(
            contractAddr,
            mapped.provider,
            mapped.chainId
          );
          
          return {
            content: [{ 
              type: "text", 
              text: `Token Information:
  Name: ${tokenInfo.name}
  Symbol: ${tokenInfo.symbol}
  Decimals: ${tokenInfo.decimals}
  Total Supply: ${tokenInfo.totalSupply}`
            }]
          };
        } catch (error) {
          return {
            isError: true,
            content: [{ 
              type: "text", 
              text: `Error getting token information: ${error instanceof Error ? error.message : String(error)}`
            }]
          };
        }
      }
    );

• src/services/erc/erc20.ts:34-102 (helper)

  Core ERC20 helper function that implements token info retrieval using ethers.js Contract interface, with caching, error handling, and metrics.

  export async function getTokenInfo(
    ethersService: EthersService,
    tokenAddress: string,
    provider?: string,
    chainId?: number
  ): Promise<ERC20Info> {
    metrics.incrementCounter('erc20.getTokenInfo');
    
    return timeAsync('erc20.getTokenInfo', async () => {
      try {
        // Check rate limiting
        const identity = `${tokenAddress}:${provider || 'default'}`;
        if (!rateLimiter.consume('token', identity)) {
          throw new ERC20Error('Rate limit exceeded for token operations');
        }
        
        // Create cache key
        const cacheKey = createTokenCacheKey(
          CACHE_KEYS.ERC20_INFO,
          tokenAddress,
          chainId
        );
        
        // Check cache first
        const cachedInfo = contractCache.get(cacheKey);
        if (cachedInfo) {
          return cachedInfo as ERC20Info;
        }
        
        // Get provider from ethers service
        const ethersProvider = ethersService['getProvider'](provider, chainId);
        
        // Create contract instance
        const contract = new ethers.Contract(tokenAddress, ERC20_ABI, ethersProvider);
        
        // Fetch token information
        const [name, symbol, decimals, totalSupply] = await Promise.all([
          contract.name(),
          contract.symbol(),
          contract.decimals(),
          contract.totalSupply()
        ]);
        
        // Format data
        const tokenInfo: ERC20Info = {
          name,
          symbol,
          decimals,
          totalSupply: totalSupply.toString()
        };
        
        // Cache result for future use (1 day TTL)
        contractCache.set(cacheKey, tokenInfo, { ttl: 86400000 });
        
        return tokenInfo;
      } catch (error) {
        logger.debug('Error getting ERC20 token info', { tokenAddress, error });
        
        if (error instanceof Error && (
          error.message.includes('contract not deployed') || 
          error.message.includes('invalid address')
        )) {
          throw new TokenNotFoundError(tokenAddress);
        }
        
        throw handleTokenError(error, 'Failed to get token information');
      }
    });
  }

• src/tools/index.ts:24-24 (registration)

  Top-level registration call within registerAllTools that invokes ERC20 tool registrations including getERC20TokenInfo.

  registerERC20Tools(server, ethersService);