Weather MCP Server

Instructions

Implementation Reference

• src/index.ts:145-219 (handler)

  The async handler function implementing the get_forecast tool logic. Fetches weather forecast data from the National Weather Service API using provided latitude and longitude, handles errors, formats the forecast periods into a readable text summary, and returns it as MCP content.

  async ({ latitude, longitude }) => {
      // Get grid point data
      const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
      const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
  
      if (!pointsData) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
                  },
              ],
          };
      }
  
      const forecastUrl = pointsData.properties?.forecast;
      if (!forecastUrl) {
          return {
              content: [
                  {
                      type: "text",
                      text: "Failed to get forecast URL from grid point data",
                  },
              ],
          };
      }
  
      // Get forecast data
      const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
      if (!forecastData) {
          return {
              content: [
                  {
                      type: "text",
                      text: "Failed to retrieve forecast data",
                  },
              ],
          };
      }
  
      const periods = forecastData.properties?.periods || [];
      if (periods.length === 0) {
          return {
              content: [
                  {
                      type: "text",
                      text: "No forecast periods available",
                  },
              ],
          };
      }
  
      // Format forecast periods
      const formattedForecast = periods.map((period: ForecastPeriod) =>
          [
              `${period.name || "Unknown"}:`,
              `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
              `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
              `${period.shortForecast || "No forecast available"}`,
              "---",
          ].join("\n"),
      );
  
      const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;
  
      return {
          content: [
              {
                  type: "text",
                  text: forecastText,
              },
          ],
      };
  },

• src/index.ts:137-144 (schema)

  Zod schema defining the input parameters for the get_forecast tool: latitude (number between -90 and 90) and longitude (number between -180 and 180).

  {
      latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
      longitude: z
          .number()
          .min(-180)
          .max(180)
          .describe("Longitude of the location"),
  },

• src/index.ts:134-220 (registration)

  Registration of the get_forecast tool on the MCP server using server.tool(), specifying the tool name, description, input schema, and handler function.

  server.tool(
      "get_forecast",
      "Get weather forecast for a location",
      {
          latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
          longitude: z
              .number()
              .min(-180)
              .max(180)
              .describe("Longitude of the location"),
      },
      async ({ latitude, longitude }) => {
          // Get grid point data
          const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
          const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
  
          if (!pointsData) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
                      },
                  ],
              };
          }
  
          const forecastUrl = pointsData.properties?.forecast;
          if (!forecastUrl) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Failed to get forecast URL from grid point data",
                      },
                  ],
              };
          }
  
          // Get forecast data
          const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
          if (!forecastData) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Failed to retrieve forecast data",
                      },
                  ],
              };
          }
  
          const periods = forecastData.properties?.periods || [];
          if (periods.length === 0) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "No forecast periods available",
                      },
                  ],
              };
          }
  
          // Format forecast periods
          const formattedForecast = periods.map((period: ForecastPeriod) =>
              [
                  `${period.name || "Unknown"}:`,
                  `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
                  `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
                  `${period.shortForecast || "No forecast available"}`,
                  "---",
              ].join("\n"),
          );
  
          const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;
  
          return {
              content: [
                  {
                      type: "text",
                      text: forecastText,
                  },
              ],
          };
      },
  );

• src/index.ts:19-35 (helper)

  Helper utility function for making authenticated and error-handled HTTP requests to the National Weather Service (NWS) API, used within the get_forecast handler.

  async function makeNWSRequest<T>(url: string): Promise<T | null> {
      const headers = {
          "User-Agent": USER_AGENT,
          Accept: "application/geo+json",
      };
  
      try {
          const response = await fetch(url, { headers });
          if (!response.ok) {
              throw new Error(`HTTP error! status: ${response.status}`);
          }
          return (await response.json()) as T;
      } catch (error) {
          console.error("Error making NWS request:", error);
          return null;
      }
  }