mcp-comexstat

Implementation Reference

• src/ComexstatMCP.ts:271-296 (handler)

  MCP tool handler that receives parameters, calls ComexstatClient.queryHistoricalData, stringifies the result as JSON, and returns it as text content.

  async ({
    flow,
    period,
    monthDetail,
    filters,
    details,
    metrics,
    language,
  }) => ({
    content: [
      {
        type: "text",
        text: JSON.stringify(
          await this.client.queryHistoricalData(
            flow,
            period,
            monthDetail,
            filters || [],
            details,
            metrics,
            language
          )
        ),
      },
    ],
  })

• src/ComexstatMCP.ts:242-270 (schema)

  Zod input schema for validating parameters of the queryHistoricalData MCP tool, including flow type, date period format, optional filters, required details and metrics arrays.

  {
    flow: z.enum(["export", "import"]),
    period: z.object({
      from: z
        .string()
        .regex(
          /^\d{4}-\d{2}$/,
          "Must be in YYYY-MM format (e.g., '2023-01')"
        ),
      to: z
        .string()
        .regex(
          /^\d{4}-\d{2}$/,
          "Must be in YYYY-MM format (e.g., '2023-01')"
        ),
    }),
    monthDetail: z.boolean().optional().default(false),
    filters: z
      .array(
        z.object({
          filter: z.string(),
          values: z.array(z.number()).or(z.array(z.string())),
        })
      )
      .optional(),
    details: z.array(z.string()),
    metrics: z.array(z.string()),
    language: z.string().optional().default("pt"),
  },

• src/ComexstatMCP.ts:241-297 (registration)

  Registration of the 'queryHistoricalData' MCP tool using server.tool(), specifying the tool name, input schema, and execution handler.

    "queryHistoricalData",
    {
      flow: z.enum(["export", "import"]),
      period: z.object({
        from: z
          .string()
          .regex(
            /^\d{4}-\d{2}$/,
            "Must be in YYYY-MM format (e.g., '2023-01')"
          ),
        to: z
          .string()
          .regex(
            /^\d{4}-\d{2}$/,
            "Must be in YYYY-MM format (e.g., '2023-01')"
          ),
      }),
      monthDetail: z.boolean().optional().default(false),
      filters: z
        .array(
          z.object({
            filter: z.string(),
            values: z.array(z.number()).or(z.array(z.string())),
          })
        )
        .optional(),
      details: z.array(z.string()),
      metrics: z.array(z.string()),
      language: z.string().optional().default("pt"),
    },
    async ({
      flow,
      period,
      monthDetail,
      filters,
      details,
      metrics,
      language,
    }) => ({
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await this.client.queryHistoricalData(
              flow,
              period,
              monthDetail,
              filters || [],
              details,
              metrics,
              language
            )
          ),
        },
      ],
    })
  );

• src/ComexstatClient.ts:403-447 (helper)

  Supporting client method implementation that validates input dates, constructs POST request to '/historical-data' endpoint with parameters, and returns the API response. This is called by the MCP handler.

  async queryHistoricalData(
    flow: "export" | "import",
    period: { from: string; to: string }, // Format: YYYY-MM (e.g., "2023-01")
    monthDetail: boolean = false,
    filters: Array<{ filter: string; values: number[] | string[] }> = [],
    details: string[],
    metrics: string[],
    language: string = "pt"
  ): Promise<{
    data: Array<{
      year: number;
      monthNumber?: number;
      metricFOB: string;
      metricKG: string;
      [key: string]: any;
    }>;
    success: boolean;
    message: string | null;
    processo_info: any;
    language: string;
  }> {
    // Validate date format
    const dateFormatRegex = /^\d{4}-\d{2}$/;
    if (
      !dateFormatRegex.test(period.from) ||
      !dateFormatRegex.test(period.to)
    ) {
      throw new Error(
        'Period dates must be in YYYY-MM format (e.g., "2023-01")'
      );
    }
  
    return this.post(
      "/historical-data",
      {
        flow,
        monthDetail,
        period,
        filters,
        details,
        metrics,
      },
      { language }
    );
  }