🌤️ MCP Weather Agent

OpenAI と Model Context Protocol (MCP) を搭載した、インテリジェントな多地域対応の天気アシスタントです。

自然言語チャットインターフェースを通じて、イスラエルとアメリカ合衆国のリアルタイムの天気予報と警報を取得できます。エージェントは質問を適切なデータソースにインテリジェントにルーティングし、ライブのウェブデータと公式の天気APIから回答をまとめます。

✨ 特徴

• 🤖 AI搭載チャット: GPT-4o-miniを使用した会話形式の天気クエリ

• 🌍 2つのデータソース:

  • 🇮🇱 イスラエル: 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（約300MB）をダウンロードします。これは一度きりの操作です。

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?

形式：

• 予報: 緯度/経度座標を使用

• 警報: 2文字の州コード（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. .envがプロジェクトルート（host.pyと同じフォルダ）に存在することを確認

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は約500MB必要です）。

❌ 接続タイムアウトまたはAPIエラー

問題: 「net::ERR_CONNECTION_RESET」またはリクエスト失敗。

解決策：

• インターネット接続を確認

• OpenAI APIキーがplatform.openai.comで有効か確認

• APIの使用量と請求を確認

❌ イスラエルのブラウザは開くが検索が失敗する

問題: 都市検索が候補を返しません。

説明: Weather2dayのオートコンプリートは/forecastページでのみ機能します。ツールは各検索の前にそのページに自動的に戻りますが、失敗した場合は：

解決策：

• Chromiumが最新であることを確認: uv run playwright install --with-deps chromium

• weather2day.co.ilへのインターネット接続があることを確認

• ブラウザのポップアップやCookieバナーを確認（エージェントはこれらを処理しますが、非常に遅い接続ではタイムアウトする可能性があります）

❌ 「サーバーに接続できません」

問題: MCPサーバー接続エラー。

解決策：

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

❓ よくある質問

Q: エージェントはどのツールを使うかをどうやって決めますか？
A: OpenAIのGPT-4o-miniが質問を読み取り、文脈（国/地域、提供された座標など）に基づいて最適なツールを選択します。ルールベースではなく、言語理解を使用します。

Q: 1つのクエリで複数の地域について質問できますか？
A: はい！エージェントは複数のツールを呼び出すことができます。例：「テルアビブとニューヨークの天気は？」

Q: なぜイスラエルのブラウザは表示されるのですか？
A: Playwrightはライブ検索に文字を入力し、結果を選択し、ページを読み取ることでWeather2dayを自動化します。ヘッドレスモード（非表示）はこのサイトのJavaScriptを多用したオートコンプリートでは機能しないため、ブラウザは表示された状態で実行されます。

Q: 費用はどのくらいかかりますか？
A: OpenAIからAPI呼び出しに基づいて請求されます。各クエリは応答の長さに応じて約$0.001〜$0.01かかります。イスラエルのウェブスクレイピングは無料、アメリカのAPIは無料です（NWSは公開されています）。

Q: さらに地域を追加したい場合は？
A: 新しいMCPサーバー（例：weather_Europe.py）を作成し、host.pyのself.mcp_clientsに登録します。既存のサーバーをパターンとして参照してください。

Q: APIキーは安全ですか？
A: はい。.envはGitから除外され、ローカルのみに保存されます。キーをコードや公開チャットに貼り付けないでください。

Q: 本番環境で使用できますか？
A: これはデモプロジェクトです。本番用には：

• 非同期リクエストキューを使用

• ロギングとエラーリカバリを追加

• 予報をキャッシュ（天気はクエリごとではなく毎時間変化します）

• 監視とアラートを設定

• 環境ベースの設定を使用

🔒 セキュリティ

APIキーが漏洩した場合：

1. OpenAI Dashboardで直ちに失効させる

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. プルリクエストを開く

📞 サポート

• 🐛 GitHub Issuesでバグを報告

• 💡 Discussionsで機能を提案

• 📧 セキュリティ問題は非公開でメール（公開イシューを開かないでください）

楽しい予報を！🌦️☀️