# Japanese Weather MCP

日本の天気情報を提供するModel Context Protocol (MCP) サーバーのサンプルプログラムです。

## 🌟 特徴

- 🌤️ **日本全国対応**: 全国110都市の天気情報を提供
- 🗣️ **自然言語対応**: 地名の漢字・ひらがな・カタカナ入力に対応
- 🤖 **MCP準拠**: Claude DesktopなどのMCPクライアントで使用可能
- 🌐 **HTTP対応**: HTTPトランスポートでWeb経由でも利用可能
- 🐳 **Docker対応**: 簡単なデプロイメント

## 🛠️ 技術スタック

- [FastMCP](https://gofastmcp.com/) - MCPサーバーフレームワーク
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) - Python依存関係管理（推奨）
- [OpenMeteo API](https://open-meteo.com/) - 天気データソース
- pandas（地名データ処理）
- httpx（HTTP通信）

## ⚡ クイックスタート

```bash
# リポジトリをクローン
git clone https://github.com/tsukiyama85/japanese-weather-mcp.git
cd japanese-weather-mcp

# MCPサーバーを起動
docker compose build
docker compose up -d

# MCPクライアントを起動
uv sync
uv run -m examples.gemini_mcp_client
```

## 📦 インストール

### 1. リポジトリのクローン

```bash
git clone https://github.com/tsukiyama85/japanese-weather-mcp.git
cd japanese-weather-mcp
```

### 2. 依存関係のインストール

#### uv使用（推奨）

```bash
# 依存関係のインストール
uv sync

# 開発用依存関係も含む場合
uv sync --dev
```

#### pip使用

```bash
pip install -e .
```

### 3. 動作確認

#### uv使用

```bash
uv run -m src.japanese_weather_mcp.main
```

#### pip使用

```bash
python -m src.japanese_weather_mcp.main
```

### Docker Composeを使用

```bash
docker-compose up --build
```

## 🚀 使用方法

### Claude Desktopでの使用

Claude Desktopの設定ファイル（`claude_desktop_config.json`）に追加：

#### uv使用

```json
{
  "mcpServers": {
    "japanese-weather": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.japanese_weather_mcp.main"],
      "cwd": "/path/to/japanese-weather-mcp"
    }
  }
}
```

#### pip使用

```json
{
  "mcpServers": {
    "japanese-weather": {
      "command": "python",
      "args": ["-m", "src.japanese_weather_mcp.main"],
      "cwd": "/path/to/japanese-weather-mcp"
    }
  }
}
```

### HTTPサーバーとして実行

#### uv使用

```bash
uv run -m src.japanese_weather_mcp.main
```

#### pip使用

```bash
python -m src.japanese_weather_mcp.main
```

## 🔧 利用可能なツール

| ツール名 | 説明 | パラメータ |
|---------|------|-----------|
| `get_weather` | 天気予報を取得 | `location`: 地域名, `days`: 日数(1-7) |
| `get_current_weather` | 現在の天気を取得 | `location`: 地域名 |
| `search_locations` | 地域を検索 | `query`: 検索クエリ |

## 💬 使用例

### Claude Desktopでの質問例

```
「東京の明日の天気は？」
「大阪の3日間の予報を教えて」
「札幌の現在の気温は？」
```

### 🤖 Gemini AIクライアントでの動作確認

`examples/gemini_mcp_client.py`を使って、Gemini AIと連携した自然言語での動作確認ができます：

#### 準備

1. **Google AI Studio**でAPIキーを取得
   - https://makersuite.google.com/app/apikey

2. **環境変数設定**
```bash
cd examples
cp .env.example .env
# .envファイルにGEMINI_API_KEYを設定
```

3. **依存関係インストール**
```bash
# uvの場合
uv sync

# pipの場合
pip install -r examples/requirements.txt
```

#### 実行手順

1. **MCPサーバーを起動**（別ターミナル）
```bash
   # uvの場合
   uv run -m src.japanese_weather_mcp.main
   uv run -m examples.gemini_mcp_client
```
```bash
   # pipの場合
   python -m src.japanese_weather_mcp.main
   python -m examples.gemini_mcp_client
```

#### 使用イメージ

```
💬 質問: 東京の今日の天気はどうですか？
🤖 回答: 東京の今日の天気は晴れで、気温は22℃です。湿度は65%、降水確率は10%となっています。
```

このクライアントは自然言語での質問を理解し、適切なMCPツールを自動選択して実行します。

## 🌍 対応地域

全国110都市に対応：
- 北海道: 札幌、函館、旭川
- 東北: 仙台、青森、盛岡 など
- 関東: 東京、横浜、さいたま など  
- 中部: 名古屋、静岡、金沢 など
- 関西: 大阪、京都、神戸 など
- 中国・四国: 広島、岡山、高松 など
- 九州・沖縄: 福岡、熊本、那覇 など

## ⚙️ 環境変数

| 変数名 | デフォルト値 | 説明 |
|--------|-------------|------|
| `MCP_TRANSPORT` | `streamable-http` | トランスポート方式 |
| `MCP_HOST` | `127.0.0.1` | HTTPサーバーのホスト |
| `MCP_PORT` | `8000` | HTTPサーバーのポート |
| `MCP_PATH` | `/mcp/` | HTTPエンドポイントパス |
| `LOG_LEVEL` | `INFO` | ログレベル |

## 🤝 開発・貢献

### examples フォルダについて

`examples/` フォルダには開発・テスト用のクライアントが含まれています：

- `gemini_mcp_client.py` - Gemini AIを使用したインテリジェントクライアント
- `.env.example` - 環境変数のテンプレート

これらは参考実装として提供 \
本体のMCPサーバーとは独立しています。

## 📝 ライセンス

MIT License

## 🙏 謝辞

- [OpenMeteo](https://open-meteo.com/) - 無料の天気データAPI
- [FastMCP](https://gofastmcp.com/) - MCPサーバーフレームワーク