queryHistoricalData
Retrieve historical trade data by specifying flow, time period, detailed metrics, and filters for exports or imports using the MCP server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| details | Yes | ||
| filters | No | ||
| flow | Yes | ||
| language | No | pt | |
| metrics | Yes | ||
| monthDetail | No | ||
| period | Yes |
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 } ); }