weather-alert-mcp v2 — una herramienta MCP, dos implementaciones

Un servidor MCP (Model Context Protocol) que expone alertas meteorológicas activas de U.S. National Weather Service como una herramienta invocable, de modo que cualquier cliente MCP —Claude Desktop, Claude Code o un cliente SDK— pueda consultar las alertas meteorológicas activas por estado.

Implementado dos veces: una en Python y otra en TypeScript, con el mismo contrato de herramienta. Un cliente no distingue con cuál de las dos está hablando. Ese es el punto de construir contra un protocolo y no contra una API, y es en las dos implementaciones donde se ven las partes interesantes de MCP.

v1 (solo Python) se encuentra en weather-alert-mcp y se deja intacta. Este repositorio es la continuación.

La herramienta

Fuente de datos: https://api.weather.gov/alerts/active — pública, sin clave de API, sin registro.

El mismo contrato, derivado por dos vías

Ambos derivan el JSON Schema que ve el cliente desde la implementación, en lugar de mantenerlo por separado, de modo que el contrato no puede desviarse del código.

El servidor TypeScript además valida en la frontera del protocolo. {"state": "Illinois"} se devuelve como un error a nivel de protocolo antes de que se haga ninguna solicitud de red, por lo que una llamada de herramienta mal formada no cuesta nada:

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

Verificación — test_client.py es un cliente MCP real: lanza el servidor como subproceso, completa el handshake initialize, enumera las herramientas anunciadas y llama a una de ellas.

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

Verificación — ts/test-client.mjs realiza el mismo recorrido de ida y vuelta y, además, comprueba que se rechaza un argumento mal formado:

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

Consulta ts/README.md para ver los detalles de la implementación en TypeScript.

Uso desde Claude Desktop

Añade uno (o ambos) a 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"]
    }
  }
}

Ambos registran el mismo nombre de herramienta, así que ejecuta uno a la vez, a menos que quieras compararlos.

Notas

• stdout es el canal del protocolo. Todo lo que se escriba ahí corrompe el flujo JSON-RPC; por eso el registro de arranque va a stderr.

• Los errores salen a la superficie en lugar de ser silenciados. Un fallo de la API externa se transmite al cliente en lugar de devolver "no alerts", que sería indistinguible de un estado verdaderamente sin alertas.

• WX_MOCK=1 ejecuta el flujo completo sin llamada de red — útil en CI y para separar un fallo de protocolo de un fallo de la API externa cuando algo se rompe.

• Las alertas se recortan a los primeros 5 elementos para mantener la salida de la herramienta dentro de un presupuesto de contexto razonable.

Limitaciones conocidas

• Una sola herramienta de solo lectura. Sin recursos, sin prompts, sin muestreo: las partes de MCP más allá del registro de herramientas no se ejercitan aquí.

• Solo transporte stdio; sin transporte HTTP/SSE.

• El endpoint de NWS requiere un User-Agent; se establece con una cadena de contacto en ambas implementaciones, según la política declarada por la API.