getDividendsCalendar

Instructions

Implementation Reference

• src/tools/calendar.ts:50-77 (handler)

  MCP tool handler for 'getDividendsCalendar' - registers the tool with the MCP server, defines Zod schema for from_date and to (optional strings), and calls calendarClient.getDividendsCalendar(). Returns JSON results or error.

  server.tool(
    "getDividendsCalendar",
    "Stay informed on upcoming dividend events with the Dividend Events Calendar API. Access a comprehensive schedule of dividend-related dates for all stocks, including record dates, payment dates, declaration dates, and dividend yields.",
    {
      from_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
      to: z.string().optional().describe("End date (YYYY-MM-DD)"),
    },
    async ({ from_date: from, to }) => {
      try {
        const results = await calendarClient.getDividendsCalendar(from, to);
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/api/calendar/CalendarClient.ts:39-48 (handler)

  CalendarClient.getDividendsCalendar() - calls the FMP API endpoint '/dividends-calendar' with optional 'from' and 'to' query parameters via the parent FMPClient.get() method.

  async getDividendsCalendar(
    from?: string,
    to?: string,
    options?: {
      signal?: AbortSignal;
      context?: FMPContext;
    }
  ): Promise<Dividend[]> {
    return super.get<Dividend[]>("/dividends-calendar", { from, to }, options);
  }

• src/api/calendar/types.ts:1-11 (schema)

  The Dividend interface defines the shape of data returned by the getDividendsCalendar API call (symbol, date, recordDate, paymentDate, declarationDate, adjDividend, dividend, yield, frequency).

  export interface Dividend {
    symbol: string;
    date: string;
    recordDate: string;
    paymentDate: string;
    declarationDate: string;
    adjDividend: number;
    dividend: number;
    yield: number;
    frequency: string;
  }

• src/toolception-adapters/coreModuleAdapters.ts:22-33 (registration)

  The 'calendar' module adapter registration - maps the 'calendar' module name to registerCalendarTools via createModuleAdapter.

  export const CORE_MODULE_ADAPTERS: Record<string, ModuleLoader> = {
    search: createModuleAdapter('search', registerSearchTools),
    directory: createModuleAdapter('directory', registerDirectoryTools),
    analyst: createModuleAdapter('analyst', registerAnalystTools),
    calendar: createModuleAdapter('calendar', registerCalendarTools),
    chart: createModuleAdapter('chart', registerChartTools),
    company: createModuleAdapter('company', registerCompanyTools),
    cot: createModuleAdapter('cot', registerCOTTools),
    esg: createModuleAdapter('esg', registerESGTools),
    economics: createModuleAdapter('economics', registerEconomicsTools),
    dcf: createModuleAdapter('dcf', registerDCFTools),
  };

• src/api/FMPClient.ts:42-82 (helper)

  FMPClient.get() base method used by CalendarClient.getDividendsCalendar() to make the actual HTTP GET request to the FMP API with an API key.

  protected async get<T>(
    endpoint: string,
    params: Record<string, any> = {},
    options?: {
      signal?: AbortSignal;
      context?: { config?: { FMP_ACCESS_TOKEN?: string } };
    }
  ): Promise<T> {
    try {
      // Try to get API key from context first, fall back to instance API key
      const apiKey = this.getApiKey(options?.context);
  
      const config: AxiosRequestConfig = {
        params: {
          ...params,
          apikey: apiKey,
        },
      };
  
      if (options?.signal) {
        config.signal = options.signal;
      }
  
      const response = await this.client.get<T>(endpoint, config);
      return response.data;
    } catch (error: unknown) {
      if (axios.isAxiosError(error)) {
        const axiosError = error as AxiosError<FMPErrorResponse>;
        throw new Error(
          `FMP API Error: ${
            axiosError.response?.data?.message || axiosError.message
          }`, { cause: error }
        );
      }
      throw new Error(
        `Unexpected error: ${
          error instanceof Error ? error.message : String(error)
        }`, { cause: error }
      );
    }
  }