Skip to main content
Glama
deenesjakoruzh
kingshuknandy2016

weather

by kingshuknandy2016
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-weather-ts

Ein TypeScript-MCP-Server, der US-Wetterdaten von der National Weather Service API für Hosts wie Cursor bereitstellt.

Der Host startet node build/index.js und kommuniziert per JSON-RPC über stdio. Das Modell ruft NWS nie selbst auf; es ruft die Tools dieses Servers auf (und kann eine Ressource lesen oder eine Prompt verwenden).

So funktioniert MCP (Tools, Ressourcen, Prompts, Transport): docs/create-mcp.readme.md.

Voraussetzungen

  • Node.js 22+ (dieses Repo verwendet ESM und fetch)

  • npm

  • Netzwerkzugriff auf https://api.weather.gov (nur US-Standorte)

Related MCP server: weather

Einrichtung

npm install
npm run build

tsc schreibt JavaScript nach build/. Cursor muss die erstellte Datei ausführen, nicht src/index.ts.

Skripte

Befehl

Was er macht

npm run build

Kompiliert src/ → build/

npm test

Smoke-Test der NWS: /points, dann Forecast- und Hourly-URLs

In Cursor einbinden

  1. Build ausführen (npm run build).

  2. Füge in diesem Projekt .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"]
    }
  }
}

Verwende für alle Cursor-Projekte %USERPROFILE%\.cursor\mcp.json und einen vollständigen Pfad zu build\index.js anstelle von ${workspaceFolder}.

  1. Öffne Customize → MCP (oder Cursor Settings → MCP) und aktiviere weather.

  2. Nachdem du src/ geändert hast, führe npm run build erneut aus und schalte den Server aus und wieder ein, damit Cursor den Prozess neu startet.

Verwende nach dem Verbinden des Servers kein console.log: stdout ist der MCP-Kanal. Nutze console.error für Logs.

Was du aufrufen kannst

Tools

Das Modell (oder du, indem du im Agent-Chat fragst) ruft diese mit tools/call auf.

Name

Eingaben

Was es tut

get_alerts

state — 2-Buchstaben-US-Code (CA, NY)

Aktive Warnungen für diesen Bundesstaat

get_forecast

latitude, longitude

12-Stunden-Vorhersage (NWS /points, dann properties.forecast)

test_tool

name

Übung: Hello, {name}!

Beispiel-Chat:

  • „Gibt es Wetterwarnungen für CA?“

  • „Vorhersage für 39.7456, -97.0892“

Beispiel-Argumente:

{ "state": "CA" }
{ "latitude": 39.7456, "longitude": -97.0892 }

Ressource

Name

URI

Was es tut

nws_guide

weather://nws-guide

Kurze statische Beschreibung der Tools und des NWS-Nachschlageablaufs

Bitte den Agenten, weather://nws-guide zu lesen, oder verwende resources/read in einem Client.

Prompt

Name

Argumente

Was es tut

check_weather

place — z. B. Boston MA oder CA

Benutzernachrichten-Vorlage, die das Modell anweist, get_forecast / get_alerts zu verwenden

Wähle in Cursor die Prompt Check weather und fülle place aus.

Projektstruktur

src/index.ts              Create McpServer, register, connect stdio
src/tools.ts              get_alerts, get_forecast, test_tool
src/resources.ts          weather://nws-guide
src/prompts.ts            check_weather
src/weather-api-call.ts   NWS fetch + types + alert formatting
src/createTransport.ts    StdioServerTransport + connect
tests/weather-api-call.test.ts
docs/create-mcp.readme.md How to design MCP servers

Startreihenfolge in src/index.ts:

  1. new McpServer({ name: "weather", version: "1.0.0" })

  2. registerWeatherTools / registerWeatherResources / registerWeatherPrompts

  3. connectStdioTransport(server)

Hinweise zu NWS

  • Vorhersagen liegen nicht unter /points/{lat},{lon}/forecast. Lade /points/{lat},{lon} (vier Nachkommastellen) und folge dann properties.forecast oder properties.forecastHourly.

  • NWS verlangt einen User-Agent-Header (gesetzt in weather-api-call.ts).

  • Die Abdeckung umfasst die USA (und einige Territorien). Andere Koordinaten schlagen oft fehl.

Fehlerbehebung

Symptom

Was du versuchen kannst

Server rot / keine Tools

Neu erstellen, prüfen, dass build/index.js existiert, MCP umschalten

Handshake schlägt fehl

Stelle sicher, dass du stdio per connect verbindest und nicht nach stdout loggst

Leere oder fehlgeschlagene Vorhersage

Nur US-Breitengrad/Längengrad; MCP-Logs prüfen

npm test schlägt fehl

Netzwerk-/NWS-Ausfall

Cursor: Output → MCP Logs.

Lizenz

ISC

Available Tools

3 tools
get_alertsWeather AlertsB

Get weather alerts for a US state

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYesTwo-letter state code (e.g. CA, NY)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description alone must carry behavioral disclosure. It only says 'get', which suggests a read-only operation, but it does not state whether any side effects occur, whether auth is required, rate limits, or what happens on error. For a simple getter, this is a notable gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the core action and object. While it is brief, it is efficient and avoids fluff, earning a high score for conciseness without sacrificing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description provides a minimal but adequate foundation. It does not describe the return format or any special conditions, but for a straightforward alert retrieval, the current description may suffice. However, it could be improved by mentioning that it returns a list of alerts or any date relevance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter fully: 'Two-letter state code (e.g. CA, NY)' with length constraints. The description adds no additional meaning beyond what the schema provides. With 100% schema description coverage, the baseline of 3 is appropriate; the description does not enhance understanding of the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'get' and the resource 'weather alerts for a US state', which clearly distinguishes it from sibling tools (get_forecast for forecasts, test_tool for testing). It is specific about the domain (weather) and geographic scope (US state), so an agent can understand the primary function without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for any US state but does not explicitly contrast with get_forecast or mention any alternatives. There is no explicit when-not-to-use guidance or relationship to siblings. However, the context of 'US state' implies the parameter scope, so usage is reasonably clear but leaves room for ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecastWeather ForecastC

Get weather forecast for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYesLatitude of the location
longitudeYesLongitude of the location

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get', implying a read-only operation, but does not mention what the forecast contains, whether authentication is required, potential rate limits, or the format of the response. The lack of any behavioral details beyond the obvious is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core action. While it is appropriately concise, it is also so minimal that it misses opportunities to add value through structure, such as listing key output or usage notes. Overall, it is concise but not optimally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, annotations, and any additional description, the tool is incomplete for an agent to call it correctly. There is no indication of what the forecast data looks like, how to interpret the response, or any caveats about precision or coverage. For a simple tool with two parameters, the description should at least mention typical return fields (e.g., temperature, conditions) to provide sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the schema documenting latitude and longitude ranges and simple descriptions. The tool description adds nothing beyond the schema, but since the schema already defines both parameters adequately, a baseline score of 3 is appropriate. No additional semantic meaning is supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'weather forecast', which is specific and unambiguous. However, it does not differentiate from the sibling tool get_alerts, which might also relate to weather, leaving some ambiguity about the precise distinction between forecast and alert retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_alerts or test_tool. The description provides no context about conditions that would make this tool preferable, nor any exclusion criteria or alternative suggestions. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test_toolTest ToolD

Test tool

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the person to greet

TDQS

D1.6/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It says nothing about side effects, return values, or operational details, offering no insight beyond the tool's existence. This is a complete failure to convey behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is short (one word), this is under-specification rather than conciseness. It lacks any substantive content, so while it is minimal, it does not earn credit for efficient wording because it provides no value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, the description is grossly incomplete. It omits the purpose, expected behavior, output, and any conditions or prerequisites. Even with a well-documented schema, the tool cannot be used correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the 'name' parameter is described as 'The name of the person to greet'), so per the rubric the baseline is 3. The description adds no additional parameter semantics, but the schema already documents the parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tautological: description restates name/title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the siblings (get_alerts, get_forecast). The description gives no context, no conditions, and no exclusions, leaving the agent with zero direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedget_alerts
    • First observedget_forecast
    • First observedtest_tool
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.4/5.0

Scored across 3 tools

Disambiguation4/5

get_alerts and get_forecast are clearly distinct in purpose, but test_tool is ambiguous and could be mistaken for a generic utility, though it doesn't overlap with the weather tools. An agent can easily differentiate the two weather tools, and test_tool is separate enough to avoid confusion.

Naming Consistency3/5

Two tools follow a consistent 'get_<noun>' pattern (get_alerts, get_forecast), but test_tool breaks this convention with a different verb and structure. The naming is still readable, but the inconsistency is noticeable given only three tools.

Tool Count3/5

Three tools is borderline for a weather server, which typically needs more operations like current conditions or location search. The presence of test_tool, which does not serve a core weather purpose, makes the count feel less purposeful and slightly thin.

Completeness2/5

The server covers alerts and forecasts but lacks fundamental weather operations like current conditions or historical data. The test_tool is irrelevant to the domain, leaving notable gaps that would require agents to work around missing functionality.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • weather

    qurioskill
    F
    license
    C
    quality
    C
    maintenance
    Exposes US weather data as MCP tools, resources, and prompts via the National Weather Service API, enabling clients like Claude Desktop to get alerts, forecasts, and weather briefings.
    2
    1
    -

  • Weather MCP Demo

    huanhuang1
    F
    license
    Not graded
    quality
    C
    maintenance
    This MCP server provides tools to get current weather, forecasts, and weather alerts from the US National Weather Service via REST APIs, enabling AI agents to query live weather data.
    1
    -

  • Weather MCP Server

    Krishna-Dhawangale
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural-language weather queries for U.S. states and coordinates, returning real-time alerts and forecasts from the National Weather Service API via MCP tools.
    -