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
`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,
        },
      ],
    };
  }
);

src/tools/forecast-by-zip-code.ts:9-28 (schema)

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);
```

AirNow MCP Server