mcp-otc

Instructions

Implementation Reference

• src/server.ts:174-201 (handler)

  Handler for executing the 'get-transactions' tool: validates input, fetches data from service, formats and returns response.

  if (name === "get-transactions") {
    try {
      const { address, limit } = TransactionHistorySchema.parse(args);
      const transactions = await etherscanService.getTransactionHistory(address, limit);
      const formattedTransactions = transactions.map(tx => {
        const date = new Date(tx.timestamp * 1000).toLocaleString();
        return `Block ${tx.blockNumber} (${date}):\n` +
               `Hash: ${tx.hash}\n` +
               `From: ${tx.from}\n` +
               `To: ${tx.to}\n` +
               `Value: ${tx.value} ETH\n` +
               `---`;
      }).join('\n');
  
      const response = transactions.length > 0
        ? `Recent transactions for ${address}:\n\n${formattedTransactions}`
        : `No transactions 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:37-40 (schema)

  Zod validation schema for 'get-transactions' tool inputs.

  const TransactionHistorySchema = 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/server.ts:70-90 (registration)

  Tool registration in listTools response, defining name, description, and input schema.

  {
    name: "get-transactions",
    description: "Get recent transactions 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 transactions to return (max 100)",
          minimum: 1,
          maximum: 100
        },
      },
      required: ["address"],
    },
  },

• src/services/etherscanService.ts:64-95 (helper)

  Core logic for fetching and formatting transaction history from Etherscan API.

  async getTransactionHistory(address: string, limit: number = 10): Promise<Transaction[]> {
    try {
      // Validate the address
      const validAddress = ethers.getAddress(address);
      
      // Get transactions directly from Etherscan API
      const result = await fetch(
        `https://api.etherscan.io/api?module=account&action=txlist&address=${validAddress}&startblock=0&endblock=99999999&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 transactions");
      }
  
      // Format the results
      return data.result.slice(0, limit).map((tx: any) => ({
        hash: tx.hash,
        from: tx.from,
        to: tx.to || 'Contract Creation',
        value: ethers.formatEther(tx.value),
        timestamp: parseInt(tx.timeStamp) || 0,
        blockNumber: parseInt(tx.blockNumber) || 0
      }));
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get transaction history: ${error.message}`);
      }
      throw error;
    }
  }