🌤️ MCP 날씨 에이전트

OpenAI와 Model Context Protocol (MCP) 기반의 지능형 다중 지역 날씨 어시스턴트입니다.

자연어 채팅 인터페이스를 통해 이스라엘과 미국의 실시간 날씨 예보와 경보를 받아보세요. 에이전트는 질문을 적절한 데이터 소스로 지능적으로 라우팅하고, 실시간 웹 데이터와 공식 날씨 API에서 답변을 수집합니다.

✨ 주요 기능

• 🤖 AI 기반 채팅: GPT-4o-mini를 사용한 대화형 날씨 질의

• 🌍 이중 데이터 소스:

  • 🇮🇱 이스라엘: Playwright를 통한 Weather2day 실시간 웹 스크래핑

  • 🇺🇸 미국: 공식 National Weather Service API

• 🔄 스마트 도구 라우팅: 질문에 따라 적절한 도구를 자동으로 선택

• 💬 자연어 처리: 일반 영어로 질문하세요. 에이전트가 맥락과 의도를 이해합니다

• 🔐 보안: API 키는 .env에 저장되며 버전 관리에서 제외됩니다

• 🎯 대화형: 이스라엘 질의 시 브라우저 자동화가 표시되는 실시간 채팅 루프

Related MCP server: Weather MCP Agent

📋 목차

• 빠른 시작

• 요구 사항

• 설정

• 에이전트 실행

• 아키텍처

• 예시 질문

• 문제 해결

• FAQ

• 보안

🚀 빠른 시작

3분 안에 시작하세요:

# 1. Install dependencies
uv sync
uv run playwright install chromium

# 2. Create .env file with your OpenAI API key
copy .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-...

# 3. Run the agent
uv run .\host.py

# 4. Ask a weather question!
# Example: "What is the weather forecast for Jerusalem?"

📦 요구 사항

🔧 설정

1. 의존성 설치

프로젝트 디렉터리에서 터미널을 열고 실행하세요:

# Install Python dependencies
uv sync

# Download Chromium browser for Playwright (required for Israel weather)
uv run playwright install chromium

처음에 시간이 오래 걸리나요? 네—Playwright가 Chromium(~300 MB)을 다운로드합니다. 이는 일회성 작업입니다.

2. OpenAI API 키 구성

프로젝트 루트에 .env 파일을 생성하세요:

# Option A: Copy the template
copy .env.example .env

# Option B: Create manually
echo OPENAI_API_KEY=your_openai_api_key > .env

your_openai_api_key를 platform.openai.com/account/api-keys에서 받은 실제 OpenAI API 키로 교체하세요.

⚠️ 중요: .env를 커밋하거나 API 키를 공유하지 마세요. .gitignore에 이미 제외되어 있습니다.

3. 설치 확인

설정을 테스트하세요:

uv run .\host.py

다음과 같은 화면이 보여야 합니다:

Connected to server with tools: [...]

MCP Client Started!
Type your queries or 'quit' to exit.

Query:

Ctrl+C를 누르거나 quit을 입력하여 종료하세요.

▶️ 에이전트 실행

대화형 채팅 시작:

uv run .\host.py

에이전트가 대화형 모드로 실행됩니다. 날씨 질문을 입력하고 Enter를 누르세요. 에이전트는 다음을 수행합니다:

1. ✅ 질문을 파싱합니다

2. 🔍 적절한 날씨 도구(이스라엘 또는 미국)로 라우팅합니다

3. 🌐 실시간 데이터를 가져옵니다(이스라엘의 경우 브라우저 창이 열릴 수 있음)

4. 📊 응답을 처리하고 형식화합니다

5. 💬 답변을 반환합니다

quit을 입력하여 종료하세요.

이스라엘 질의의 경우: Chromium 브라우저 창이 자동으로 열립니다. 이는 정상입니다—에이전트가 Playwright를 사용하여 Weather2day와 상호작용하기 때문입니다. 쿼리가 완료되면 창이 닫힙니다.

🏗️ 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        OpenAI (GPT-4o-mini)                     │
│                      (Tool Selection & Reasoning)               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
        ┌───────▼────────┐       ┌───────▼────────┐
        │  MCP Host      │       │   MCP Host     │
        │  (client.py)   │       │   (client.py)  │
        └───────┬────────┘       └───────┬────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │ weather_Israel.py    │  │ weather_USA.py    │
        │ (Playwright + Web)   │  │ (NWS API)         │
        └───────┬──────────────┘  └──────┬─────────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │   Weather2day.co.il  │  │    api.weather.gov│
        │  (Live Web Browser)  │  │   (REST API)      │
        └──────────────────────┘  └───────────────────┘

데이터 흐름:

1. 채팅에서 질문을 입력합니다

2. 호스트가 사용 가능한 도구와 함께 OpenAI로 전송합니다

3. OpenAI가 질문에 따라 호출할 도구를 선택합니다

4. 적절한 MCP 서버가 실행되고 데이터를 반환합니다

5. 호스트가 답변을 형식화하여 반환합니다

💬 예시 질문

🇮🇱 이스라엘 날씨

What is the weather forecast for Jerusalem?
Give me the forecast for Tel Aviv.
What is the weather like in Haifa today?
Show me the forecast for Eilat.
What is the weather in Beer Sheva?
Is it going to rain in Kfar Saba tomorrow?
Tell me about the weather in Nazareth.
What's the forecast for Tiberias?

지원 도시: 예루살렘, 텔아비브, 하이파, 에일랏, 베르셰바, 크파르사바, 티베리아스, 나사렛 및 Weather2day가 인식하는 대부분의 주요 이스라엘 도시.

🇺🇸 미국 날씨

What is the weather forecast for New York City? (40.7128, -74.0060)
What's the weather at latitude 34.0522, longitude -118.2437? (Los Angeles)
Are there any active weather alerts in California?
What weather alerts are in effect in New York?
Give me the forecast for Chicago coordinates. (41.8781, -87.6298)
Are there any severe weather warnings in Texas?

형식:

• 예보: 위도/경도 좌표 사용

• 경보: 두 글자 주 코드 사용 (CA, NY, TX 등)

🎯 스마트 에이전트 동작

에이전트는 맥락을 이해합니다:

• ✅ "예루살렘 날씨는 어때?" → 이스라엘 도구 사용

• ✅ "뉴욕에 방문 중인데 예보가 어때?" → 미국 도구 사용 (40.71, -74.01)

• ✅ "텔아비브와 로스앤젤레스 날씨 알려줘" → 두 도구 모두 호출

• ✅ "지금 시카고에 비가 오고 있어?" → 미국 도구로 라우팅

📂 프로젝트 구조

MCP Weather/
├── host.py                  # Main chat host (OpenAI + tool orchestration)
├── client.py                # MCP client connector
├── weather_Israel.py        # Israel MCP server (Playwright + Web)
├── weather_USA.py           # USA MCP server (NWS API)
├── pyproject.toml           # Dependencies and project metadata
├── uv.lock                  # Locked dependency versions
├── .env.example             # Template for environment variables
├── .env                     # Your API keys (git-ignored)
├── README.md                # This file
└── .gitignore               # Git exclusion rules

🐛 문제 해결

❌ OPENAI_API_KEY is missing

문제: 에이전트가 API 키를 찾을 수 없습니다.

해결 방법:

1. 프로젝트 루트(host.py와 같은 폴더)에 .env가 있는지 확인하세요

2. 파일에 OPENAI_API_KEY=sk-your-actual-key-here가 포함되어 있는지 확인하세요

3. 호스트를 다시 시작하세요: uv run .\host.py

❌ Chromium 브라우저가 실행되지 않음

문제: "Failed to launch browser" 오류.

해결 방법:

uv run playwright install chromium

여전히 실패하면 디스크 공간을 확인하세요(Chromium은 ~500 MB 필요).

❌ 연결 시간 초과 또는 API 오류

문제: "net::ERR_CONNECTION_RESET" 또는 요청 실패.

해결 방법:

• 인터넷 연결을 확인하세요

• OpenAI API 키가 platform.openai.com에서 유효한지 확인하세요

• API 사용량과 결제 상태를 확인하세요

❌ 이스라엘 브라우저가 열리지만 검색이 실패함

문제: 도시 검색이 추천 결과를 반환하지 않습니다.

설명: Weather2day 자동 완성은 /forecast 페이지에서만 작동합니다. 도구는 각 검색 전에 자동으로 해당 페이지로 돌아가지만, 실패할 수 있습니다:

해결 방법:

• Chromium이 최신인지 확인하세요: uv run playwright install --with-deps chromium

• weather2day.co.il에 인터넷 연결이 가능한지 확인하세요

• 브라우저 팝업 또는 쿠키 배너를 확인하세요(에이전트가 처리하지만, 매우 느린 연결은 시간 초과될 수 있음)

❌ "A server fails to connect"

문제: MCP 서버 연결 오류.

해결 방법:

# Run from the project directory
Set-Location .\project-template
uv run .\host.py

❓ FAQ

Q: 에이전트는 어떤 도구를 사용할지 어떻게 결정하나요?
A: OpenAI의 GPT-4o-mini가 질문을 읽고 맥락(언급된 국가/지역, 제공된 좌표 등)에 따라 최상의 도구를 선택합니다. 규칙 기반이 아니라 언어 이해를 사용합니다.

Q: 하나의 질문으로 여러 지역을 물어볼 수 있나요?
A: 네! 에이전트는 여러 도구를 호출할 수 있습니다. "텔아비브와 뉴욕 날씨는 어때?"라고 시도해 보세요.

Q: 이스라엘 브라우저가 왜 눈에 보이게 열리나요?
A: Playwright가 라이브 검색에 입력하고, 결과를 선택하고, 페이지를 읽어 Weather2day를 자동화합니다. 헤드리스 모드(보이지 않음)는 이 사이트의 JavaScript 기반 자동 완성과 작동하지 않으므로 브라우저가 눈에 보이게 실행됩니다.

Q: 비용은 얼마인가요?
A: OpenAI에서 API 호출에 따라 청구됩니다. 각 쿼리는 응답 길이에 따라 ~$0.001–$0.01입니다. 이스라엘 웹 스크래핑은 무료이고, 미국 API는 무료입니다(NWS는 공개 API).

Q: 더 많은 지역을 추가하려면 어떻게 하나요?
A: 새 MCP 서버(예: weather_Europe.py)를 만들고 host.py의 self.mcp_clients에 등록하세요. 기존 서버에서 패턴을 참조하세요.

Q: API 키는 안전한가요?
A: 네. .env는 Git에서 제외되고 로컬에만 저장됩니다. 코드나 공개 채팅에 키를 절대 붙여넣지 마세요.

Q: 프로덕션에서 사용할 수 있나요?
A: 이는 데모 프로젝트입니다. 프로덕션의 경우:

• 비동기 요청 큐 사용

• 로깅 및 오류 복구 추가

• 예보 캐싱(날씨는 쿼리마다가 아니라 시간 단위로 변경됨)

• 모니터링 및 알림 설정

• 환경 기반 구성 사용

🔒 보안

API 키가 노출된 경우:

1. OpenAI 대시보드에서 즉시 폐기하세요

2. 새 키를 생성하세요

3. .env를 업데이트하세요

📝 라이선스

이 프로젝트는 교육 목적으로 있는 그대로 제공됩니다. 자세한 내용은 LICENSE를 참조하세요.

🤝 기여

에이전트를 개선할 아이디어가 있으신가요? 기여를 환영합니다!

1. 저장소를 포크하세요

2. 기능 브랜치를 생성하세요 (git checkout -b feature/amazing-feature)

3. 변경 사항을 커밋하세요 (git commit -m 'Add amazing feature')

4. 브랜치에 푸시하세요 (git push origin feature/amazing-feature)

5. Pull Request를 여세요

📞 지원

• 🐛 GitHub Issues를 통해 버그를 보고하세요

• 💡 Discussions에서 기능을 제안하세요

• 📧 보안 문제는 비공개로 이메일을 보내세요(공개 이슈를 열지 마세요)

즐거운 예보 되세요! 🌦️☀️