Alchemy MCP Server

Implementation Reference

• index.ts:73-96 (handler)

  MCP tool handler function: processes input params by converting dates to ISO8601, delegates to alchemyApi.getTokenPriceHistoryBySymbol, formats response as text content or error.

  }, async (params) => {
    try {
      const result = await alchemyApi.getTokenPriceHistoryBySymbol({
        ...params,
        startTime: toISO8601(params.startTime),
        endTime: toISO8601(params.endTime)
      });
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      if (error instanceof Error) {
        console.error('Error in getTokenPriceHistoryBySymbol:', error);
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true
        };
      }
      return {
        content: [{ type: "text", text: 'Unknown error occurred' }],
        isError: true
      };
    }
  });

• index.ts:68-72 (registration)

  Registration of the 'fetchTokenPriceHistoryBySymbol' MCP tool with Zod input schema.

  server.tool('fetchTokenPriceHistoryBySymbol', {
    symbol: z.string().describe('The token symbol to query. e.g. "BTC" or "ETH"'),
    startTime: z.string().describe('The start time date to query. e.g. "2021-01-01"'),
    endTime: z.string().describe('The end time date to query. e.g. "2021-01-01"'),
    interval: z.string().describe('The interval to query. e.g. "1d" or "1h"')

• types/types.d.ts:15-20 (schema)

  TypeScript interface defining the input parameters for token price history by symbol, matching the Zod schema.

  export interface TokenPriceHistoryBySymbol {
    symbol: string;
    startTime: string;
    endTime: string;
    interval: string;
  }

• api/alchemyApi.ts:48-63 (helper)

  Core helper function that performs the HTTP POST to Alchemy Prices API '/historical' endpoint to fetch price history data.

  async getTokenPriceHistoryBySymbol(params: TokenPriceHistoryBySymbol) {
    console.log('Fetching token price history for symbol:', params.symbol);
    try {
      const client = createPricesClient();
      
      const response = await client.post('/historical', {
        ...params
      });
  
      console.log('Successfully fetched token price history:', response.data);
      return response.data;  
    } catch (error) {
      console.error('Error fetching token price history:', error);
      throw error;
    }
  },

• utils/dateUtils.ts:137-192 (helper)

  Helper utility to convert date strings (including keywords like 'today', 'now') to ISO8601 format, used in the tool handler for startTime and endTime.

  export function toISO8601(dateStr: string): string {
      // Handle keywords first
      const normalizedStr = dateStr.toLowerCase();
      
      const now = new Date();
      
      switch (normalizedStr) {
          case 'today': {
              const date = new Date(now);
              date.setHours(0, 0, 0, 0);
              return date.toISOString();
          }
          case 'yesterday': {
              const date = new Date(now);
              date.setDate(date.getDate() - 1);
              date.setHours(0, 0, 0, 0);
              return date.toISOString();
          }
          case 'last-week': {
              const date = new Date(now);
              date.setDate(date.getDate() - 7);
              date.setHours(0, 0, 0, 0);
              return date.toISOString();
          }
          case 'last-month': {
              const date = new Date(now);
              date.setMonth(date.getMonth() - 1);
              date.setHours(0, 0, 0, 0);
              return date.toISOString();
          }
          case 'start-of-year': {
              const date = new Date(now);
              date.setMonth(0, 1);
              date.setHours(0, 0, 0, 0);
              return date.toISOString();
          }
          case 'now': {
              return now.toISOString();
          }
      }
      
      // If already in ISO format, return as is
      if (dateStr.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/)) {
          return dateStr;
      }
    
      // For any other date string, parse it normally
      try {
          const date = new Date(dateStr);
          return date.toISOString();
      } catch (error) {
          console.error('Error parsing date:', error);
          // Return current time if parsing fails
          return now.toISOString();
      }
  }