get-forecast-by-zip-code

Instructions

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