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;
  }