getCOTReports

Instructions

Implementation Reference

• src/tools/cot.ts:13-47 (handler)

  The MCP tool handler for 'getCOTReports' - registers the tool with server.tool(), accepts symbol, from_date, and to parameters, calls cotClient.getReports(), and returns JSON-stringified results or an error.

  server.tool(
    "getCOTReports",
    "Access comprehensive Commitment of Traders (COT) reports with the FMP COT Report API. This API provides detailed information about long and short positions across various sectors, helping you assess market sentiment and track positions in commodities, indices, and financial instruments.",
    {
      symbol: z.string().describe("Commodity symbol"),
      from_date: z
        .string()
        .optional()
        .describe("Optional start date (YYYY-MM-DD)"),
      to: z
        .string()
        .optional()
        .describe("Optional end date (YYYY-MM-DD)"),
    },
    async ({ symbol, from_date: from, to }) => {
      try {
        const results = await cotClient.getReports(symbol, 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/tools/cot.ts:16-26 (schema)

  Zod schema for the tool's input parameters: symbol (required string), from_date (optional YYYY-MM-DD), to (optional YYYY-MM-DD).

  {
    symbol: z.string().describe("Commodity symbol"),
    from_date: z
      .string()
      .optional()
      .describe("Optional start date (YYYY-MM-DD)"),
    to: z
      .string()
      .optional()
      .describe("Optional end date (YYYY-MM-DD)"),
  },

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

  Registration of registerCOTTools via createModuleAdapter('cot', registerCOTTools) in the core module adapters registry.

  import { registerCOTTools } from '../tools/cot.js';
  import { registerESGTools } from '../tools/esg.js';
  import { registerEconomicsTools } from '../tools/economics.js';
  import { registerDCFTools } from '../tools/dcf.js';
  
  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/cot/COTClient.ts:15-25 (helper)

  COTClient.getReports() - makes the HTTP GET request to '/commitment-of-traders-report' endpoint with symbol, from, to parameters, returning COTReport[].

  async getReports(
    symbol: string,
    from?: string,
    to?: string,
    options?: {
      signal?: AbortSignal;
      context?: FMPContext;
    }
  ): Promise<COTReport[]> {
    return super.get<COTReport[]>("/commitment-of-traders-report", { symbol, from, to }, options);
  }

• src/api/cot/types.ts:1-130 (schema)

  TypeScript interface COTReport defining all fields returned by the COT reports API (symbol, date, name, sector, positions, percentages, concentration data, etc.).

  export interface COTReport {
    symbol: string;
    date: string;
    name: string;
    sector: string;
    marketAndExchangeNames: string;
    cftcContractMarketCode: string;
    cftcMarketCode: string; 
    cftcRegionCode: string;
    cftcCommodityCode: string;
    openInterestAll: number;
    noncommPositionsLongAll: number;
    noncommPositionsShortAll: number;
    noncommPositionsSpreadAll: number;  
    commPositionsLongAll: number;
    commPositionsShortAll: number;
    totReptPositionsLongAll: number;
    totReptPositionsShortAll: number;
    nonreptPositionsLongAll: number;
    nonreptPositionsShortAll: number; 
    openInterestOld: number;
    noncommPositionsLongOld: number;
    noncommPositionsShortOld: number;
    noncommPositionsSpreadOld: number;
    commPositionsLongOld: number;
    commPositionsShortOld: number;  
    totReptPositionsLongOld: number;
    totReptPositionsShortOld: number;
    nonreptPositionsLongOld: number;
    nonreptPositionsShortOld: number;
    openInterestOther: number;
    noncommPositionsLongOther: number;  
    noncommPositionsShortOther: number;
    noncommPositionsSpreadOther: number;
    commPositionsLongOther: number;
    commPositionsShortOther: number;
    totReptPositionsLongOther: number;
    totReptPositionsShortOther: number; 
    nonreptPositionsLongOther: number;
    nonreptPositionsShortOther: number;
    changeInOpenInterestAll: number;
    changeInNoncommLongAll: number;
    changeInNoncommShortAll: number;
    changeInNoncommSpeadAll: number;  
    changeInCommLongAll: number;
    changeInCommShortAll: number;
    changeInTotReptLongAll: number;
    changeInTotReptShortAll: number;
    changeInNonreptLongAll: number;
    changeInNonreptShortAll: number;  
    pctOfOpenInterestAll: number;
    pctOfOiNoncommLongAll: number;
    pctOfOiNoncommShortAll: number;
    pctOfOiNoncommSpreadAll: number;
    pctOfOiCommLongAll: number;
    pctOfOiCommShortAll: number;  
    pctOfOiTotReptLongAll: number;
    pctOfOiTotReptShortAll: number;
    pctOfOiNonreptLongAll: number;
    pctOfOiNonreptShortAll: number;
    pctOfOpenInterestOl: number;
    pctOfOiNoncommLongOl: number; 
    pctOfOiNoncommShortOl: number;
    pctOfOiNoncommSpreadOl: number;
    pctOfOiCommLongOl: number;
    pctOfOiCommShortOl: number;
    pctOfOiTotReptLongOl: number;
    pctOfOiTotReptShortOl: number;  
    pctOfOiNonreptLongOl: number;
    pctOfOiNonreptShortOl: number;
    pctOfOpenInterestOther: number;
    pctOfOiNoncommLongOther: number;
    pctOfOiNoncommShortOther: number;
    pctOfOiNoncommSpreadOther: number;  
    pctOfOiCommLongOther: number;
    pctOfOiCommShortOther: number;
    pctOfOiTotReptLongOther: number;
    pctOfOiTotReptShortOther: number;
    pctOfOiNonreptLongOther: number;
    pctOfOiNonreptShortOther: number; 
    tradersTotAll: number;
    tradersNoncommLongAll: number;
    tradersNoncommShortAll: number;
    tradersNoncommSpreadAll: number;
    tradersCommLongAll: number;
    tradersCommShortAll: number;  
    tradersTotReptLongAll: number;
    tradersTotReptShortAll: number;
    tradersTotOl: number;
    tradersNoncommLongOl: number;
    tradersNoncommShortOl: number;
    tradersNoncommSpeadOl: number;  
    tradersCommLongOl: number;
    tradersCommShortOl: number;
    tradersTotReptLongOl: number;
    tradersTotReptShortOl: number;
    tradersTotOther: number;
    tradersNoncommLongOther: number;  
    tradersNoncommShortOther: number;
    tradersNoncommSpreadOther: number;
    tradersCommLongOther: number;
    tradersCommShortOther: number;
    tradersTotReptLongOther: number;
    tradersTotReptShortOther: number; 
    concGrossLe4TdrLongAll: number;
    concGrossLe4TdrShortAll: number;
    concGrossLe8TdrLongAll: number;
    concGrossLe8TdrShortAll: number;
    concNetLe4TdrLongAll: number;
    concNetLe4TdrShortAll: number;  
    concNetLe8TdrLongAll: number;
    concNetLe8TdrShortAll: number;
    concGrossLe4TdrLongOl: number;
    concGrossLe4TdrShortOl: number;
    concGrossLe8TdrLongOl: number;
    concGrossLe8TdrShortOl: number; 
    concNetLe4TdrLongOl: number;
    concNetLe4TdrShortOl: number;
    concNetLe8TdrLongOl: number;
    concNetLe8TdrShortOl: number;
    concGrossLe4TdrLongOther: number;
    concGrossLe4TdrShortOther: number;  
    concGrossLe8TdrLongOther: number;
    concGrossLe8TdrShortOther: number;
    concNetLe4TdrLongOther: number;
    concNetLe4TdrShortOther: number;
    concNetLe8TdrLongOther: number;
    concNetLe8TdrShortOther: number;
    contractUnits: string;
  }