MCP Ethers Wallet

Implementation Reference

• src/tools/erc721.ts:323-352 (registration)

  Registration of the getNFTMetadata MCP tool, including inline Zod input schema and async handler function that delegates to getMetadata service.

      "getNFTMetadata",
      {
        contractAddress: contractAddressSchema,
        tokenId: tokenIdSchema,
        provider: providerSchema,
        chainId: chainIdSchema
      },
      async ({ contractAddress, tokenId, provider, chainId }) => {
        try {
          const metadata = await getMetadata(ethersService, contractAddress, tokenId.toString(), provider, chainId);
          return {
            content: [{ 
              type: "text", 
              text: `NFT #${tokenId} Metadata:
  Name: ${metadata.name || 'No name available'}
  Description: ${metadata.description || 'No description available'}
  Image URL: ${metadata.image || 'No image available'}`
            }]
          };
        } catch (error) {
          return {
            isError: true,
            content: [{ 
              type: "text", 
              text: `Error getting token metadata: ${error instanceof Error ? error.message : String(error)}`
            }]
          };
        }
      }
    );

• src/tools/erc721.ts:61-66 (schema)

  TypeScript type definition for GetNFTMetadataParams matching the tool input schema.

  type GetNFTMetadataParams = {
    contractAddress: string;
    tokenId: string | number;
    provider?: string;
    chainId?: number;
  };

• src/services/erc/erc721.ts:274-326 (helper)

  Helper function getMetadata that implements the core logic: caches token URI, fetches and parses metadata from URI, handles errors and caching.

  export async function getMetadata(
    ethersService: EthersService,
    contractAddress: string,
    tokenId: string | number,
    provider?: string,
    chainId?: number
  ): Promise<NFTMetadata> {
    metrics.incrementCounter('erc721.getMetadata');
    
    return timeAsync('erc721.getMetadata', async () => {
      try {
        // Create cache key
        const cacheKey = createTokenCacheKey(
          CACHE_KEYS.ERC721_METADATA,
          contractAddress,
          tokenId,
          chainId
        );
        
        // Check cache first
        const cachedMetadata = contractCache.get(cacheKey);
        if (cachedMetadata) {
          return cachedMetadata as NFTMetadata;
        }
        
        // Get token URI
        const tokenURI = await getTokenURI(ethersService, contractAddress, tokenId, provider, chainId);
        
        // Fetch and parse metadata
        const metadata = await fetchMetadata(tokenURI, contractAddress, tokenId);
        
        // Cache result for future use (1 hour TTL)
        contractCache.set(cacheKey, metadata, { ttl: 3600000 });
        
        return metadata;
      } catch (error) {
        logger.debug('Error getting NFT metadata', { contractAddress, tokenId, error });
        
        if (error instanceof TokenNotFoundError) {
          throw error;
        }
        
        // Handle metadata parsing errors
        if (!(error instanceof TokenMetadataError)) {
          throw new TokenMetadataError(contractAddress, tokenId, undefined, {
            originalError: error instanceof Error ? error.message : String(error)
          });
        }
        
        throw error;
      }
    });
  }