MCP 날씨 어시스턴트

Model Context Protocol(MCP)로 구축된 대화형 날씨 어시스턴트입니다. 호스트가 두 개의 로컬 MCP 서버에 연결하고, 해당 서버의 도구를 OpenRouter 호환 언어 모델에 게시하며, 모델이 날씨 정보를 검색할 시점을 스스로 결정하도록 합니다.

기능

• National Weather Service API를 통한 미국 내 위치의 날씨 예보.

• 미국 주(州)의 활성 기상 특보.

• weather2day.co.il 웹사이트와 Playwright로 제어되는 가시적 Chromium 브라우저를 통한 이스라엘 날씨 예보.

• 대화형 터미널 채팅 인터페이스 1개.

• stdio로 연결되는 여러 MCP 서버.

• 서버 간 충돌을 방지하기 위한 자동 도구 검색 및 네임스페이스 지정.

Related MCP server: MCP Weather Assistant

프로젝트 구조

요구 사항

• Windows, macOS 또는 Linux.

• Python 3.13 이상.

• OpenRouter API 키.

• OpenRouter, api.weather.gov, weather2day.co.il에 대한 인터넷 접근.

• 이스라엘 날씨 조회를 위한 Playwright로 설치된 Chromium.

• 가상 환경을 권장합니다.

설치

uv 사용 시

프로젝트 디렉터리에서:

uv sync
uv run playwright install chromium

프로젝트는 현재 httpx를 직접 임포트합니다. 잠긴 환경에 아직 없다면 다음으로 설치하세요:

uv add httpx

표준 Python 도구 사용 시

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install anthropic mcp python-dotenv playwright openai google-genai httpx
python -m playwright install chromium

macOS 또는 Linux에서는 다음으로 환경을 활성화하세요:

source .venv/bin/activate

선언된 의존성에는 현재 host.py에서 사용되지 않는 여러 공급자 SDK가 포함되어 있습니다. 이들은 템플릿과의 호환성을 위해 프로젝트 메타데이터의 일부로 유지됩니다.

구성

프로젝트 루트에 .env 파일을 만드세요:

OPENROUTER_API_KEY=your_openrouter_api_key

host.py는 python-dotenv로 이 파일을 로드하고 키를 Bearer 토큰으로 OpenRouter에 전송합니다. .env를 커밋하거나 소스 제어, 로그, 스크린샷, 오류 보고서에 키를 노출하지 마세요.

현재 모델은 host.py에 구성되어 있습니다:

MODEL = "nvidia/nemotron-3-super-120b-a12b:free"

도구 호출을 지원하는 다른 OpenRouter 모델을 사용하려면 이 상수를 변경하세요.

어시스턴트 실행

uv 사용 시:

uv run python host.py

활성화된 가상 환경 사용 시:

python host.py

시작 메시지 다음에 Query: 프롬프트가 표시됩니다. 질문을 입력하고 Enter를 누르세요. quit를 입력하면 애플리케이션이 종료됩니다.

예시 질문:

What is the forecast for 34.05, -118.25?
Are there any active weather alerts in California?
What is the weather forecast in Tel Aviv?

호스트는 도구 호출이 발생할 때마다 출력한 다음 모델의 최종 응답을 출력합니다.

MCP 서버 및 도구

미국 서버

weather_USA.py는 weather-USA라는 MCP 서버를 시작하며 다음을 제공합니다:

• get_alerts_in_USA(state)

  • state: CA 또는 NY와 같은 두 글자 주 코드.

  • NWS 활성 특보 엔드포인트를 사용합니다.

• get_forecast_in_USA(latitude, longitude)

  • latitude: 십진수 위도.

  • longitude: 십진수 경도.

  • NWS points 엔드포인트를 통해 위치를 확인한 다음 처음 5개 예보 기간을 반환합니다.

NWS API 요청은 Accept: application/geo+json과 사용자 지정 User-Agent를 사용합니다.

이스라엘 서버

weather_Israel.py는 weather-Israel이라는 MCP 서버를 시작하며 다음을 제공합니다:

1. open_weather_forecast_israel()

   • 비헤드리스(비은폐) Chromium 브라우저를 열고 이스라엘 예보 웹사이트로 이동합니다.

2. enter_weather_forecast_city_israel(city)

   • 도시 이름을 입력하고 자동 완성 제안을 기다립니다.

3. select_weather_forecast_city_israel()

   • 첫 번째 자동 완성 제안을 선택하고 예보 페이지를 기다립니다.

4. get_forecast_content_israel()

   • 로드된 페이지에서 표시되는 텍스트를 추출하고, 빈 줄을 정리하며, 결과를 4,000자로 제한합니다.

이스라엘 도구는 상태를 유지하므로 순서대로 호출해야 합니다. 도시를 입력하기 전에 브라우저를 열어야 하며, 예보를 추출하기 전에 도시를 선택해야 합니다.

아키텍처

User terminal
    |
    v
host.py (ChatHost)
    |-- OpenRouter chat-completions API
    |
    |-- client.py -> weather_USA.py -> api.weather.gov
    |
    `-- client.py -> weather_Israel.py -> Playwright -> weather2day.co.il

시작 시 ChatHost는 각 날씨 서버에 대해 하나의 MCPClient를 생성합니다. 각 클라이언트는 호스트와 동일한 Python 인터프리터를 사용하여 자체 서버를 하위 프로세스로 시작합니다. 호스트는 모든 MCP 도구를 검색하고 함수 호출 스키마를 사용하여 OpenRouter에 노출합니다.

중복 이름을 방지하기 위해 도구는 모델에 다음과 같이 노출됩니다:

<server_script_name>__<tool_name>

예를 들어, 미국 특보 도구는 weather_USA__get_alerts_in_USA로 노출됩니다. OpenRouter가 도구를 요청하면 호스트는 해당 공개 이름을 소유 MCP 클라이언트와 원래 도구 이름에 매핑하고, 이를 실행하고, 결과를 모델 대화에 다시 전송합니다.

개별 MCP 서버 실행

각 서버는 MCP 호환 클라이언트용 또는 기본 스모크 테스트용으로 직접 시작할 수 있습니다:

python weather_USA.py
python weather_Israel.py

이 프로그램들은 MCP stdio 전송을 사용하므로 일반 웹 페이지나 명령 프롬프트를 표시하는 대신 MCP 클라이언트와 통신하도록 설계되었습니다.

문제 해결

ModuleNotFoundError: No module named 'httpx'

누락된 의존성을 설치하세요:

uv add httpx

또는:

python -m pip install httpx

Chromium이 시작되지 않음

Playwright 브라우저 바이너리를 설치하세요:

python -m playwright install chromium

이스라엘 서버는 의도적으로 headless=False로 Chromium을 실행하므로 해당 공급자에는 데스크톱 세션이 필요합니다.

OpenRouter 인증 실패

.env가 host.py와 같은 디렉터리에 있는지, 변수 이름이 정확히 OPENROUTER_API_KEY인지, 키가 활성 상태인지 확인하세요. 파일을 변경한 후 호스트를 다시 시작하세요.

사용 가능한 도구가 없음

두 서버 스크립트가 프로젝트 루트에 존재하고 호스트가 해당 디렉터리에서 시작되는지 확인하세요. 호스트는 현재 상대 경로 ./weather_USA.py와 ./weather_Israel.py를 사용합니다.

날씨 요청 실패

애플리케이션은 외부 서비스에 의존합니다. 인터넷 접근, 요청된 좌표 또는 주에 대한 NWS 응답, 이스라엘 웹사이트의 HTML 선택자가 변경되었는지 확인하세요.

보안 및 운영 참고 사항

• host.py와 NWS 클라이언트는 verify=False로 TLS 인증서 검증을 비활성화합니다. 현재 네트워크 환경에서는 필요할 수 있지만 전송 보안을 약화시키므로 프로덕션에서는 일반 인증서 검증으로 대체해야 합니다.

• OpenRouter는 사용자의 질문과 날씨 도구가 반환한 결과를 수신합니다.

• 이스라엘 공급자는 가시적 브라우저를 열고 페이지의 본문 텍스트를 스크래핑합니다. 웹사이트 레이아웃 변경은 선택자를 깨뜨리거나 추출된 콘텐츠를 변경할 수 있습니다.

• 애플리케이션에는 영구 대화 기록이 없습니다. 각 터미널 질문은 새 모델 메시지 목록으로 시작됩니다.

• 오류는 터미널에 출력되며 로깅 서비스에 기록되지 않습니다.

개발 참고 사항

MCP 서버 스크립트는 FastMCP 데코레이터를 통해 도구를 노출하고 네트워크 및 브라우저 작업에 비동기 함수를 사용합니다. 서버를 수정할 때 stdio 채널을 MCP 프로토콜 트래픽 전용으로 유지하세요. 진단 출력은 프로토콜 통신을 손상시키지 않도록 주의 깊게 처리해야 합니다.

현재 저장소에는 자동화된 테스트가 없습니다. 유용한 다음 테스트 계층은 NWS 응답, OpenRouter 도구 호출 응답, Playwright 페이지 상호 작용을 모킹하여 네트워크 접근이나 브라우저 없이 오케스트레이션을 검증할 수 있게 하는 것입니다.

라이선스

현재 이 저장소에는 라이선스 파일이 포함되어 있지 않습니다.