Marketstack MCP Server

Instructions

Implementation Reference

• src/tools/marketData/getDividendsData.ts:56-78 (handler)

  The main handler function that executes the tool logic by constructing API parameters and calling the Marketstack client to fetch dividends data.

  const getDividendsDataHandler = async (input: Input, client: MarketstackClient): Promise<Output> => {
    try {
      const { symbols, sort, date_from, date_to, limit, offset } = input;
  
      const apiRequestParams: MarketstackApiParams = {
        endpoint: 'dividends',
        symbols,
        ...(sort && { sort }), // Include if sort is provided
        ...(date_from && { date_from }), // Include if date_from is provided
        ...(date_to && { date_to }), // Include if date_to is provided
        ...(limit && { limit }), // Include if limit is provided
        ...(offset && { offset }), // Include if offset is provided
      };
  
      const data = await client.fetchApiData(apiRequestParams);
  
      return data;
    } catch (error: unknown) {
      console.error('getDividendsData tool error:', error);
      const message = error instanceof Error ? error.message : 'An unknown error occurred.';
      throw new Error(`getDividendsData tool failed: ${message}`);
    }
  };

• src/tools/marketData/getDividendsData.ts:5-49 (schema)

  Zod schema defining the input parameters for the get_dividends_data tool.

  const getDividendsDataInputSchemaShape = {
    symbols: z
      .string()
      .describe(
        'Specify one or multiple comma-separated stock symbols (tickers) for your request, e.g. `AAPL` or `AAPL,MSFT`. Each symbol consumes one API request. Maximum: 100 symbols'
      ),
    sort: z
      .enum(['DESC', 'ASC'])
      .optional()
      .default('DESC')
      .describe(
        'By default, results are sorted by date/time descending. Use this parameter to specify a sorting order. Available values: `DESC` (Default), `ASC`.'
      ),
    date_from: z
      .string()
      .optional()
      .describe(
        'Filter results based on a specific timeframe by passing a from-date in `YYYY-MM-DD` format. You can also specify an exact time in ISO-8601 date format, e.g. `2020-05-21T00:00:00+0000`.'
      ),
    date_to: z
      .string()
      .optional()
      .describe(
        'Filter results based on a specific timeframe by passing an end-date in `YYYY-MM-DD` format. You can also specify an exact time in ISO-8601 date format, e.g. `2020-05-21T00:00:00+0000`.'
      ),
    limit: z
      .number()
      .int()
      .min(1)
      .max(1000)
      .optional()
      .default(100)
      .describe(
        'Specify a pagination limit (number of results per page) for your API request. Default limit value is `100`, maximum allowed limit value is `1000`.'
      ),
    offset: z
      .number()
      .int()
      .min(0)
      .optional()
      .default(0)
      .describe(
        'Specify a pagination offset value for your API request. Example: An offset value of `100` combined with a limit value of 10 would show results 100-110. Default value is `0`, starting with the first available result.'
      ),
  };

• src/tools/marketData/getDividendsData.ts:88-93 (registration)

  Tool definition object exporting the name, description, schema, and handler.

  export const getDividendsDataTool: MarketstackToolDefinition = {
    name: 'get_dividends_data',
    description: 'Look up information about the stock dividend for different symbols.',
    inputSchemaShape: getDividendsDataInputSchemaShape,
    handler: getDividendsDataHandler,
  };

• src/tools/marketData/index.ts:39-44 (registration)

  MCP server registration of the get_dividends_data tool using server.tool().

  server.tool(
    getDividendsDataTool.name,
    getDividendsDataTool.description,
    getDividendsDataTool.inputSchemaShape,
    wrapToolHandler((input) => getDividendsDataTool.handler(input, client))
  );