weather-alert-mcp v2 — one MCP tool, two implementations

An MCP (Model Context Protocol) server that exposes live U.S. National Weather Service alerts as a callable tool, so any MCP client — Claude Desktop, Claude Code, or an SDK client — can query active weather alerts by state.

Implemented twice: once in Python, once in TypeScript, against the same tool contract. A client cannot tell which one it is talking to. That is the point of building against a protocol rather than an API, and the two implementations are where the interesting parts of MCP become visible.

v1 (Python only) lives at weather-alert-mcp and is left untouched. This repo is the continuation.

The tool

Tool	Argument	Returns
get_alerts	state — two-letter US state code (e.g. IL)	Up to 5 active alerts: event, severity, affected area, headline

Data source: https://api.weather.gov/alerts/active — public, no API key, no signup.

The same contract, derived two ways

	Python (server.py)	TypeScript (ts/src/index.ts)
Schema source	generated from type hints	generated from a zod schema
Argument validation	trusts the client's schema conformance	validates at the boundary, rejects before any HTTP call
Transport	stdio	stdio
Offline mode	WX_MOCK=1	WX_MOCK=1
Tool contract	get_alerts(state)	get_alerts(state) — identical

Both derive the JSON Schema the client sees from the implementation rather than maintaining it separately, so the contract cannot drift from the code.

The TypeScript server additionally validates at the protocol boundary. {"state": "Illinois"} comes back as a protocol-level error before any network request is made, so a malformed tool call costs nothing:

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

Verify — test_client.py is a real MCP client: it spawns the server as a subprocess, completes the initialize handshake, lists the advertised tools, and calls one.

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

Verify — ts/test-client.mjs drives the same round trip and additionally asserts that a malformed argument is rejected:

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

See ts/README.md for detail on the TypeScript implementation.

---

Use from Claude Desktop

Add either (or both) to claude_desktop_config.json:

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

Both register the same tool name, so run one at a time unless you want to compare them.

Notes

• stdout is the protocol channel. Anything written there corrupts the JSON-RPC stream, which is why startup logging goes to stderr.
• Errors surface rather than being swallowed. An upstream API failure is raised to the client instead of returning "no alerts", which would be indistinguishable from a genuinely quiet state.
• WX_MOCK=1 runs the full path with no network call — useful in CI, and for separating a protocol failure from an upstream API failure when something breaks.
• Alerts are truncated to the first 5 features to keep tool output inside a reasonable context budget.

Known limitations

• One read-only tool. No resources, no prompts, no sampling — the parts of MCP beyond tool registration are not exercised here.
• stdio transport only; no HTTP/SSE transport.
• The NWS endpoint requires a User-Agent; it is set to a contact string in both implementations, per the API's stated policy.