# 松本バス MCP サーバー

松本市コミュニティバス情報を提供するModel Context Protocol (MCP)サーバーです。

## 概要

このMCPサーバーは、松本市が公開するGTFS-JP形式のバス情報を活用し、LLMが自然言語でバス情報を照会・提供できるようにします。観光客や市民が効率的にバスを利用できるよう支援します。

## 特徴

- **バス停検索**: 名前による部分一致検索
- **次発バス検索**: 指定バス停からの次のバス発車時刻を取得
- **近隣バス停検索**: GPS座標から最寄りのバス停を検索
- **路線情報**: 路線の詳細と経由バス停の一覧
- **自動更新**: GTFSデータの定期的な自動更新

## インストール

### 必要要件

- Python 3.10以上
- pip

### セットアップ

```bash
# リポジトリのクローン
git clone https://github.com/Takamasa045/matsumoto-buss-mcp.git
cd matsumoto-buss-mcp

# 依存関係のインストール
pip install -e .
```

## 使用方法

### MCPサーバーとして起動

```bash
python -m matsumoto_bus_mcp
```

### MCP設定ファイル

Claude Desktopやその他のMCPクライアントで使用する場合、設定ファイルに以下を追加してください：

```json
{
  "mcpServers": {
    "matsumoto-bus": {
      "command": "python",
      "args": ["-m", "matsumoto_bus_mcp"],
      "cwd": "/path/to/matsumoto-buss-mcp"
    }
  }
}
```

## 利用可能なツール

### 1. search_bus_stops

バス停を名前で検索します（部分一致可）。

**パラメータ:**
- `stop_name` (string, 必須): バス停名
- `limit` (integer, オプション): 最大返却件数（デフォルト: 10）

**例:**
```json
{
  "stop_name": "松本駅",
  "limit": 5
}
```

### 2. get_next_departures

指定バス停から指定時刻以降に出発する次のバスを検索します。

**パラメータ:**
- `stop_id` (string, 必須): バス停ID
- `departure_time` (string, オプション): 基準時刻（ISO 8601形式）
- `limit` (integer, オプション): 返却件数（デフォルト: 5）
- `route_filter` (string, オプション): 路線名フィルタ

**例:**
```json
{
  "stop_id": "STOP_001",
  "limit": 3
}
```

### 3. find_nearby_stops

指定座標から最寄りのバス停を検索します。

**パラメータ:**
- `latitude` (number, 必須): 緯度
- `longitude` (number, 必須): 経度
- `radius` (integer, オプション): 検索半径（メートル、デフォルト: 500）
- `limit` (integer, オプション): 最大返却件数（デフォルト: 5）

**例:**
```json
{
  "latitude": 36.2380,
  "longitude": 137.9723,
  "radius": 1000
}
```

### 4. get_route_info

路線の詳細情報と経由バス停一覧を取得します。

**パラメータ:**
- `route_id` (string, 必須): 路線ID
- `direction` (integer, オプション): 方向（0 or 1）

**例:**
```json
{
  "route_id": "ROUTE_001",
  "direction": 0
}
```

### 5. list_all_routes

運行中の全路線一覧を取得します。

**パラメータ:** なし

## データソース

- **プライマリデータ**: [GTFSデータポータル](https://gtfs-data.jp/)
- **ライセンス**: CC-BY 4.0（松本市オープンデータ利用規約）
- **更新頻度**: 松本市による更新タイミングに準拠

## 技術スタック

- **MCP SDK**: Model Context Protocol実装
- **データベース**: SQLite
- **GTFS処理**: Python標準ライブラリ
- **地理計算**: Haversine公式による距離計算

## プロジェクト構造

```
matsumoto-buss-mcp/
├── src/
│   └── matsumoto_bus_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCPサーバーメイン
│       ├── config.py          # 設定管理
│       ├── database.py        # データベース管理
│       ├── gtfs_loader.py     # GTFSデータローダー
│       └── bus_service.py     # バス情報検索サービス
├── data/                      # データディレクトリ
├── logs/                      # ログディレクトリ
├── pyproject.toml            # プロジェクト設定
└── README.md
```

## 環境変数

- `MATSUMOTO_GTFS_URL`: GTFSデータのダウンロードURL（デフォルト: gtfs-data.jp）
- `LOG_LEVEL`: ログレベル（DEBUG/INFO/WARNING/ERROR、デフォルト: INFO）

## 制約事項

- リアルタイム位置情報は含まれません（GTFS Realtime未対応）
- 遅延情報は提供できません
- データ更新は松本市の公開タイミングに依存します

## ライセンス

MIT License

データソース: 松本市オープンデータ（CC-BY 4.0）

## 貢献

プルリクエストを歓迎します。大きな変更の場合は、まずissueを開いて変更内容を議論してください。

## サポート

問題が発生した場合は、[GitHubのIssues](https://github.com/Takamasa045/matsumoto-buss-mcp/issues)で報告してください。