get-current-observations-by-reporting-area-by-zip-code

Instructions

Implementation Reference

• src/tools/current-observations-by-reporting-area-by-zip-code.ts:27-51 (handler)

  The handler function that executes the tool logic by calling the AirNow API helper and formatting the response.

  async (params) => {
    const result =
      await airnowApi.fetchCurrentObservationsByReportingAreaByZipCode(
        params
      );
    if (result === null) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to fetch current observations data from AirNow API.",
          },
        ],
        isError: true,
      };
    }
    return {
      content: [
        {
          type: "text",
          text: result,
        },
      ],
    };
  }

• src/tools/current-observations-by-reporting-area-by-zip-code.ts:9-26 (schema)

  Zod schema defining the input parameters: zipCode (required), format (enum), distance (optional).

  {
    zipCode: z
      .string()
      .describe(
        "Zip code to get the current observations for. Example: 94954"
      ),
    format: z
      .enum(["text/csv", "application/json", "application/xml"])
      .describe(
        "Format of the payload file returned. Example: application/json"
      ),
    distance: z
      .string()
      .optional()
      .describe(
        "If no reporting area is associated with the Zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
      ),
  },

• src/tools/current-observations-by-reporting-area-by-zip-code.ts:5-53 (registration)

  Primary registration of the tool with MCP server, including name, description, schema, and handler.

  export const registerCurrentObservationsByZipCode = (server: McpServer): void => {
    server.tool(
      "get-current-observations-by-reporting-area-by-zip-code",
      "Get current AQI values and categories for a reporting area by Zip code.",
      {
        zipCode: z
          .string()
          .describe(
            "Zip code to get the current observations for. Example: 94954"
          ),
        format: z
          .enum(["text/csv", "application/json", "application/xml"])
          .describe(
            "Format of the payload file returned. Example: application/json"
          ),
        distance: z
          .string()
          .optional()
          .describe(
            "If no reporting area is associated with the Zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
          ),
      },
      async (params) => {
        const result =
          await airnowApi.fetchCurrentObservationsByReportingAreaByZipCode(
            params
          );
        if (result === null) {
          return {
            content: [
              {
                type: "text",
                text: "Failed to fetch current observations data from AirNow API.",
              },
            ],
            isError: true,
          };
        }
        return {
          content: [
            {
              type: "text",
              text: result,
            },
          ],
        };
      }
    );
  };

• src/airnow-api.ts:42-50 (helper)

  API helper function that constructs the AirNow API request for current observations by zip code and fetches the data.

  export async function fetchCurrentObservationsByReportingAreaByZipCode(params: Record<string, string>): Promise<string | null> {
    const endpoint = 'aq/observation/zipcode/current/';
    const queryParams = new URLSearchParams();
    queryParams.append('zipCode', params.zipCode);
    queryParams.append('format', params.format);
    if (params.distance) queryParams.append('distance', params.distance);
  
    return airnowGet(endpoint, queryParams);
  }

• src/tools/index.ts:5-17 (registration)

  Secondary registration: import and invocation of the tool registrar within the tools index.

  import { registerCurrentObservationsByZipCode } from "./current-observations-by-reporting-area-by-zip-code.js";
  import { registerCurrentObservationsByLatLong } from "./current-observations-by-reporting-area-by-lat-long.js";
  import { registerForecastByLatLong } from "./forecast-by-lat-long.js";
  import { registerForecastByZipCode } from "./forecast-by-zip-code.js";
  import { registerHistoricalObservationsByLatLong } from "./historical-observations-by-reporting-area-by-lat-long.js";
  import { registerHistoricalObservationsByZipCode } from "./historical-observations-by-reporting-area-by-zip-code.js";
  import { registerObservationsByBoundingBox } from "./observations-by-monitoring-site-by-geographic-bounding-box.js";
  
  export const registerTools = (server: McpServer): void => {
    registerContourMapsByBoundingBoxCombined(server);
    registerContourMapsByBoundingBoxOzone(server);
    registerContourMapsByBoundingBoxPM25(server);
    registerCurrentObservationsByZipCode(server);