weather-alert-mcp v2 – ein MCP-Tool, zwei Implementierungen

Ein MCP (Model Context Protocol)-Server, der Live-Warnungen des U.S. National Weather Service als aufrufbares Tool bereitstellt, sodass jeder MCP-Client – Claude Desktop, Claude Code oder ein SDK-Client – aktive Wetterwarnungen nach Bundesstaat abfragen kann.

Zweimal implementiert: einmal in Python, einmal in TypeScript, gegen denselben Tool-Vertrag. Ein Client kann nicht erkennen, mit welchem er spricht. Das ist der Sinn davon, gegen ein Protokoll statt gegen eine API zu entwickeln, und die beiden Implementierungen zeigen die interessanten Teile von MCP.

v1 (nur Python) befindet sich unter weather-alert-mcp und bleibt unverändert. Dieses Repo ist die Fortsetzung.

Das Tool

Datenquelle: https://api.weather.gov/alerts/active – öffentlich, kein API-Schlüssel, keine Anmeldung.

Derselbe Vertrag, auf zwei Arten abgeleitet

Beide leiten das JSON-Schema, das der Client sieht, aus der Implementierung ab, anstatt es separat zu pflegen, sodass der Vertrag nicht vom Code abweichen kann.

Der TypeScript-Server validiert zusätzlich an der Protokollgrenze. {"state": "Illinois"} wird als Fehler auf Protokollebene zurückgegeben, bevor eine Netzwerkanfrage gestellt wird, sodass ein fehlerhafter Tool-Aufruf nichts kostet:

MCP error -32602: Input validation error: Invalid arguments for tool get_alerts

Python

pip install -r requirements.txt
python server.py                    # speaks MCP over stdio; a client launches this

Überprüfen – test_client.py ist ein echter MCP-Client: Er startet den Server als Unterprozess, führt den initialize-Handshake durch, listet die beworbenen Tools auf und ruft eines auf.

python test_client.py               # live
WX_MOCK=1 python test_client.py     # protocol only, no network

TOOLS:   ['get_alerts']
DESC:    Get active National Weather Service alerts for a US state.
SCHEMA:  {'properties': {'state': {'title': 'State', 'type': 'string'}}, 'required': ['state'], ...}

RESULT for IL:
Severe Thunderstorm Warning (Severe) — Lake County, IL
Severe Thunderstorm Warning issued for Lake County until 7:15 PM CDT

TypeScript

cd ts
npm install
npm run build
node build/index.js                 # speaks MCP over stdio

Überprüfen – ts/test-client.mjs führt denselben Roundtrip durch und stellt zusätzlich sicher, dass ein fehlerhaftes Argument abgelehnt wird:

cd ts
WX_MOCK=1 node test-client.mjs      # protocol only, no network
node test-client.mjs TX             # live NWS data

TOOLS:   [ 'get_alerts' ]
SCHEMA:  {"type":"object","properties":{"state":{"type":"string","minLength":2,"maxLength":2,
          "pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code, e.g. \"IL\" or \"CA\""}},
          "required":["state"],"additionalProperties":false}

RESULT:
Severe Thunderstorm Warning (Severe) — Lake County, IL
Severe Thunderstorm Warning issued for Lake County until 7:15 PM CDT

VALIDATION: rejected bad input as expected — MCP error -32602: Input validation error

Siehe ts/README.md für Details zur TypeScript-Implementierung.

Verwendung mit Claude Desktop

Fügen Sie eines (oder beide) zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "weather-alerts": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    },
    "weather-alerts-ts": {
      "command": "node",
      "args": ["/absolute/path/to/ts/build/index.js"]
    }
  }
}

Beide registrieren denselben Tool-Namen, also führen Sie jeweils nur eines aus, es sei denn, Sie möchten sie vergleichen.

Hinweise

• stdout ist der Protokollkanal. Alles, was dort geschrieben wird, beschädigt den JSON-RPC-Stream, weshalb Startprotokollierung nach stderr geht.

• Fehler werden sichtbar gemacht, nicht verschluckt. Ein Fehler der vorgelagerten API wird an den Client weitergegeben, anstatt „keine Warnungen“ zurückzugeben, was von einem wirklich ruhigen Zustand nicht zu unterscheiden wäre.

• WX_MOCK=1 führt den vollständigen Pfad ohne Netzwerkaufruf aus – nützlich in CI und um bei einem Fehler einen Protokollfehler von einem vorgelagerten API-Fehler zu unterscheiden.

• Warnungen werden auf die ersten 5 Features gekürzt, um die Tool-Ausgabe innerhalb eines angemessenen Kontextbudgets zu halten.

Bekannte Einschränkungen

• Ein schreibgeschütztes Tool. Keine Ressourcen, keine Prompts, kein Sampling – die Teile von MCP jenseits der Tool-Registrierung werden hier nicht genutzt.

• Nur stdio-Transport; kein HTTP/SSE-Transport.

• Der NWS-Endpunkt erfordert einen User-Agent; er wird in beiden Implementierungen auf eine Kontaktzeichenfolge gesetzt, gemäß der angegebenen Richtlinie der API.