mcp-otc

Instructions

Implementation Reference

• src/services/etherscanService.ts:97-129 (handler)

  Core implementation of getTokenTransfers that fetches and formats ERC20 token transfer data from the Etherscan API.
  async getTokenTransfers(address: string, limit: number = 10): Promise<TokenTransfer[]> { try { const validAddress = ethers.getAddress(address); // Get ERC20 token transfers const result = await fetch( `https://api.etherscan.io/api?module=account&action=tokentx&address=${validAddress}&page=1&offset=${limit}&sort=desc&apikey=${this.provider.apiKey}` ); const data = await result.json(); if (data.status !== "1" || !data.result) { throw new Error(data.message || "Failed to fetch token transfers"); } // Format the results return data.result.slice(0, limit).map((tx: any) => ({ token: tx.contractAddress, tokenName: tx.tokenName, tokenSymbol: tx.tokenSymbol, from: tx.from, to: tx.to, value: ethers.formatUnits(tx.value, parseInt(tx.tokenDecimal)), timestamp: parseInt(tx.timeStamp) || 0, blockNumber: parseInt(tx.blockNumber) || 0 })); } catch (error) { if (error instanceof Error) { throw new Error(`Failed to get token transfers: ${error.message}`); } throw error; } }
• src/server.ts:203-231 (handler)

  MCP tool dispatch handler for 'get-token-transfers' that validates input, calls the service, formats output, and returns MCP response.
  if (name === "get-token-transfers") { try { const { address, limit } = TokenTransferSchema.parse(args); const transfers = await etherscanService.getTokenTransfers(address, limit); const formattedTransfers = transfers.map(tx => { const date = new Date(tx.timestamp * 1000).toLocaleString(); return `Block ${tx.blockNumber} (${date}):\n` + `Token: ${tx.tokenName} (${tx.tokenSymbol})\n` + `From: ${tx.from}\n` + `To: ${tx.to}\n` + `Value: ${tx.value}\n` + `Contract: ${tx.token}\n` + `---`; }).join('\n'); const response = transfers.length > 0 ? `Recent token transfers for ${address}:\n\n${formattedTransfers}` : `No token transfers found for ${address}`; return { content: [{ type: "text", text: response }], }; } catch (error) { if (error instanceof z.ZodError) { throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`); } throw error; } }
• src/server.ts:91-111 (registration)

  Registers the 'get-token-transfers' tool in the MCP server's tool list with description and input schema.
  { name: "get-token-transfers", description: "Get ERC20 token transfers for an Ethereum address", inputSchema: { type: "object", properties: { address: { type: "string", description: "Ethereum address (0x format)", pattern: "^0x[a-fA-F0-9]{40}$" }, limit: { type: "number", description: "Number of transfers to return (max 100)", minimum: 1, maximum: 100 }, }, required: ["address"], }, },
• src/server.ts:42-45 (schema)

  Zod schema for validating input parameters (address and optional limit) for the get-token-transfers tool.
  const TokenTransferSchema = z.object({ address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address format'), limit: z.number().min(1).max(100).optional(), });
• src/services/etherscanService.ts:12-21 (schema)

  TypeScript interface defining the structure of token transfer data returned by the service.
  export interface TokenTransfer { token: string; tokenName: string; tokenSymbol: string; from: string; to: string; value: string; timestamp: number; blockNumber: number; }