weather-alert-mcp v2 — 하나의 MCP 도구, 두 가지 구현

MCP(Model Context Protocol) 서버는 실시간 미국 국립기상청(National Weather Service) 경보를 호출 가능한 도구로 노출하므로, 모든 MCP 클라이언트 — Claude Desktop, Claude Code, 또는 SDK 클라이언트 — 가 주(state)별 활성 기상 경보를 조회할 수 있습니다.

동일한 도구 계약을 기준으로 두 번 구현되었습니다. 한 번은 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는 동일한 왕복(round trip)을 수행하고, 추가로 잘못된 형식의 인자가 거부되는지 확인합니다:

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개 feature로 잘립니다.

알려진 제한 사항

• 읽기 전용 도구 하나뿐입니다. 리소스, 프롬프트, 샘플링이 없습니다 — 도구 등록을 넘어서는 MCP의 부분은 여기서 다루지 않습니다.

• stdio 전송만 지원하며, HTTP/SSE 전송은 없습니다.

• NWS 엔드포인트는 User-Agent를 요구합니다. API의 명시된 정책에 따라 두 구현 모두 연락처 문자열로 설정되어 있습니다.