get-forecast-by-zip-code
Retrieve current or historical air quality forecast data by Zip code, specifying format and optional date or distance. Access AQI values and categories for informed decision-making.
Instructions
Get current or historical forecasted AQI values and categories for a reporting area by Zip code.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date to get the forecast for. Format: YYYY-MM-DD. Example: 2012-02-01 | |
| distance | No | Distance in miles to search for the forecast. Example: 150 | |
| format | Yes | Format of the payload file returned. Example: application/json | |
| zipCode | Yes | Zip code to get the forecast for. Example: 94954 |
Implementation Reference
- src/tools/forecast-by-zip-code.ts:29-51 (handler)The MCP tool handler function that invokes the AirNow API helper to fetch forecast data by zip code and formats the response as MCP content.async (params) => { const result = await airnowApi.fetchForecastByZipCode(params); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch forecast data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; } );
- Zod-based input schema defining parameters for the get-forecast-by-zip-code tool: zipCode (string), date (optional string), format (enum), distance (optional string).{ zipCode: z .string() .describe("Zip code to get the forecast for. Example: 94954"), date: z .string() .optional() .describe( "Date to get the forecast for. Format: YYYY-MM-DD. Example: 2012-02-01" ), format: z .enum(["text/csv", "application/json", "application/xml"]) .describe( "Format of the payload file returned. Example: application/json" ), distance: z .string() .optional() .describe("Distance in miles to search for the forecast. Example: 150"), },
- src/tools/forecast-by-zip-code.ts:5-52 (registration)Exported registration function specific to this tool, called from tools/index.ts to register the tool on the MCP server.export const registerForecastByZipCode = (server: McpServer): void => { server.tool( "get-forecast-by-zip-code", "Get current or historical forecasted AQI values and categories for a reporting area by Zip code.", { zipCode: z .string() .describe("Zip code to get the forecast for. Example: 94954"), date: z .string() .optional() .describe( "Date to get the forecast for. Format: YYYY-MM-DD. Example: 2012-02-01" ), format: z .enum(["text/csv", "application/json", "application/xml"]) .describe( "Format of the payload file returned. Example: application/json" ), distance: z .string() .optional() .describe("Distance in miles to search for the forecast. Example: 150"), }, async (params) => { const result = await airnowApi.fetchForecastByZipCode(params); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch forecast data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; } ); }
- src/airnow-api.ts:19-28 (helper)Core helper function that constructs the API request to AirNow's forecast/zipcode endpoint and fetches the data using the shared airnowGet function.export async function fetchForecastByZipCode(params: Record<string, string>): Promise<string | null> { const endpoint = 'aq/forecast/zipcode/'; const queryParams = new URLSearchParams(); queryParams.append('zipCode', params.zipCode); queryParams.append('format', params.format); if (params.date) queryParams.append('date', params.date); if (params.distance) queryParams.append('distance', params.distance); return airnowGet(endpoint, queryParams); }
- src/tools/index.ts:20-20 (registration)Invocation of the tool's registration function within the central registerTools function.registerForecastByZipCode(server);