weather-alert-mcp v2 — один MCP-инструмент, две реализации

MCP-сервер (Model Context Protocol), который предоставляет актуальные оповещения Национальной метеорологической службы США в виде вызываемого инструмента, так что любой MCP-клиент — Claude Desktop, Claude Code или SDK-клиент — может запрашивать активные погодные оповещения по штатам.

Реализован дважды: один раз на Python, один раз на TypeScript, по одному и тому же контракту инструмента. Клиент не может определить, с какой из них он общается. В этом и заключается смысл разработки под протокол, а не под API, и именно в двух реализациях становятся видны интересные части MCP.

v1 (только Python) находится в weather-alert-mcp и остаётся нетронутой. Этот репозиторий — продолжение.

Инструмент

Источник данных: https://api.weather.gov/alerts/active — публичный, без API-ключа, без регистрации.

Один и тот же контракт, полученный двумя способами

Обе реализации выводят JSON Schema, которую видит клиент, из самой реализации, а не поддерживают её отдельно, поэтому контракт не может разойтись с кодом.

TypeScript-сервер дополнительно проверяет данные на границе протокола. {"state": "Illinois"} возвращается как ошибка уровня протокола до выполнения любого сетевого запроса, поэтому некорректный вызов инструмента ничего не стоит:

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

Проверка — test_client.py — это настоящий MCP-клиент: он запускает сервер как подпроцесс, выполняет рукопожатие initialize, перечисляет объявленные инструменты и вызывает один из них.

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

Проверка — ts/test-client.mjs выполняет тот же полный цикл и дополнительно проверяет, что некорректный аргумент отклоняется:

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

Подробности о TypeScript-реализации см. в ts/README.md.

Использование из Claude Desktop

Добавьте один (или оба) в 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"]
    }
  }
}

Оба регистрируют одно и то же имя инструмента, поэтому запускайте по одному, если не хотите их сравнивать.

Примечания

• stdout — это канал протокола. Всё, что туда записывается, повреждает поток JSON-RPC, поэтому журналирование при запуске идёт в stderr.

• Ошибки всплывают, а не проглатываются. Сбой вышестоящего API передаётся клиенту вместо возврата «нет оповещений», что было бы неотличимо от действительно спокойного состояния.

• WX_MOCK=1 выполняет полный путь без сетевого вызова — полезно в CI и для отделения сбоя протокола от сбоя вышестоящего API, когда что-то ломается.

• Оповещения обрезаются до первых 5 элементов, чтобы вывод инструмента оставался в рамках разумного бюджета контекста.

Известные ограничения

• Один инструмент только для чтения. Нет ресурсов, нет промптов, нет сэмплирования — части MCP за пределами регистрации инструментов здесь не задействованы.

• Только транспорт stdio; нет транспорта HTTP/SSE.

• Конечная точка NWS требует User-Agent; в обеих реализациях он задан как контактная строка, согласно заявленной политике API.