@physictim/mcp-server-thsrc/README.md

🚄 MCP Server for Taiwan High Speed Rail - Real-time train schedules, station info, and seat availability. Cross-platform support with automatic Python detection. 台灣高鐵即時資訊查詢服務，支援 Windows/macOS/Linux，提供時刻表、班次狀態、座位查詢等功能。

# MCP Server THSRC - 台灣高鐵資訊查詢服務

這是一個基於 Model Context Protocol (MCP) 的台灣高鐵資料查詢服務器，提供即時的高鐵時刻表、車站資訊、班次狀態和座位查詢功能。

## 功能特色

- 🚄 **完整的高鐵資料查詢**：時刻表、即時班次、座位狀態
- 🌐 **多語言支援**：支援中文站名、英文站名及ID查詢
- 🔄 **即時資料**：整合 TDX (運輸資料流通服務) API
- 📱 **MCP 標準**：相容所有支援 MCP 的應用程式

## 安裝方式

### 🚀 快速開始（推薦）

**適用所有平台（Windows/macOS/Linux）**

直接使用 npx，無需複雜安裝步驟：

```bash
npx @physictim/mcp-server-thsrc --help
```

### 📋 系統需求

- **Node.js** 14.0+ 
- **Python** 3.8+ 
- **TDX API 金鑰**（免費申請）

## Windows 完整安裝指南

### 步驟 1：安裝 Node.js

1. 前往 [nodejs.org](https://nodejs.org/) 下載 LTS 版本
2. 執行安裝程式，確保勾選 "Add to PATH"
3. 重新開啟命令提示字元，驗證安裝：
   ```cmd
   node --version
   npm --version
   ```

### 步驟 2：安裝 Python

**選項 A：從官網安裝（推薦）**
1. 前往 [python.org](https://python.org) 下載最新版本
2. 執行安裝程式，**重要：勾選 "Add Python to PATH"**
3. 驗證安裝：
   ```cmd
   py --version
   python --version
   ```

**選項 B：使用 Microsoft Store**
1. 開啟 Microsoft Store
2. 搜尋 "Python" 並安裝
3. 驗證安裝：
   ```cmd
   python --version
   ```

**選項 C：使用 winget**
```cmd
winget install Python.Python.3.12
```

### 步驟 3：取得 TDX API 金鑰

1. 前往 [TDX運輸資料流通服務平臺](https://tdx.transportdata.tw/)
2. 註冊帳號並登入
3. 前往「會員中心」→「應用服務」→「API金鑰管理」
4. 取得：
   - **Client ID**
   - **Client Secret**

### 步驟 4：設定 Claude Desktop

1. **找到設定檔位置**：
   ```
   Windows: %APPDATA%\Claude\claude_desktop_config.json
   ```

2. **編輯設定檔**（如果檔案不存在，請建立）：
   ```json
   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
           "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
         }
       }
     }
   }
   ```

3. **重啟 Claude Desktop**

### 步驟 5：驗證安裝

在 Claude Desktop 中輸入：
```
請查詢台灣高鐵車站列表
```

如果看到車站資訊，表示安裝成功！

## 替代安裝方法

### 方法 2：使用 pipx（進階用戶）

```bash
# 安裝 pipx
python -m pip install --user pipx
python -m pipx ensurepath

# 從 GitHub 安裝
pipx install git+https://github.com/physictim/thsrc_mcp.git
```

### 方法 3：手動安裝

```bash
# 複製專案
git clone https://github.com/physictim/thsrc_mcp.git
cd thsrc_mcp

# 建立虛擬環境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安裝依賴
pip install -r requirements.txt
```

## 整合到 Claude Desktop

### 1. 取得 TDX API 金鑰

前往 [TDX運輸資料流通服務平臺](https://tdx.transportdata.tw/) 註冊並取得：
- Client ID
- Client Secret

### 2. 配置 Claude Desktop

找到 Claude Desktop 的設定檔：

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

### 3. 編輯設定檔

在 `claude_desktop_config.json` 中加入以下設定：

#### 如果你使用 npx（推薦）：

**Windows/macOS/Linux 通用：**
```json
{
  "mcpServers": {
    "thsrc": {
      "command": "npx",
      "args": ["-y", "@physictim/mcp-server-thsrc"],
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}
```

#### 如果你使用 pipx 安裝：
```json
{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "mcp-server-thsrc",
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}
```

#### 如果你手動安裝：
```json
{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "/path/to/your/python3",
      "args": ["/path/to/your/thsrc.py"],
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}
```

### 4. 重啟 Claude Desktop

重新啟動 Claude Desktop，MCP 服務器將會自動載入。

### 5. 驗證連線

在 Claude Desktop 中輸入：
```
請幫我查詢台灣高鐵車站列表
```

如果設定成功，Claude 將會使用 MCP 工具查詢並返回高鐵車站資訊。

### 使用範例

設定完成後，您可以在 Claude Desktop 中直接使用自然語言查詢：

- "查詢明天台北到左營的高鐵班次"
- "台中車站現在有哪些班次？"
- "823車次明天的詳細資訊"
- "台北到高雄還有座位嗎？"

Claude 會自動調用相應的 MCP 工具來取得即時資料。

## 可用工具

### 1. 車站列表查詢
```python
get_thsr_stations()
```
取得所有台灣高鐵車站資訊。

### 2. 時刻表查詢
```python
get_thsr_timetable("台北", "左營", "2024-01-01")
```
查詢指定路線和日期的班次時刻表。

**參數說明：**
- `origin_station`: 起站（支援中文站名如"台北"或站點ID如"1000"）
- `destination_station`: 迄站（支援中文站名如"左營"或站點ID如"1070"）
- `travel_date`: 乘車日期（YYYY-MM-DD格式）

### 3. 即時班次查詢
```python
get_thsr_live_schedule("台北")
```
取得指定車站的即時班次狀態。

**參數說明：**
- `station`: 車站名稱或ID

### 4. 特定班次資訊
```python
get_thsr_train_info("823", "2024-01-01")
```
查詢特定車次的詳細資訊。

**參數說明：**
- `train_no`: 車次號碼
- `travel_date`: 乘車日期（YYYY-MM-DD格式）

### 5. 剩餘座位查詢
```python
get_thsr_available_seats("台北", "左營", "2024-01-01")
```
查詢指定路線的剩餘座位狀態。

**參數說明：**
- `origin_station`: 起站
- `destination_station`: 迄站  
- `travel_date`: 乘車日期

**更新頻率：**
- 當日查詢：每10分鐘更新
- 其他日期：每日10:00、16:00、22:00更新

## 支援車站

| 中文站名 | 英文站名 | 站點ID |
|---------|---------|--------|
| 南港 | Nangang | 0990 |
| 台北 | Taipei | 1000 |
| 板橋 | Banqiao | 1010 |
| 桃園 | Taoyuan | 1020 |
| 新竹 | Hsinchu | 1030 |
| 苗栗 | Miaoli | 1035 |
| 台中 | Taichung | 1040 |
| 彰化 | Changhua | 1043 |
| 雲林 | Yunlin | 1047 |
| 嘉義 | Chiayi | 1050 |
| 台南 | Tainan | 1060 |
| 左營 | Zuoying | 1070 |

## 資源

### thsr://stations
提供車站資訊的 MCP 資源，可在支援 MCP 的應用程式中直接存取。

## 使用範例

### 查詢台北到左營的班次
```python
# 使用中文站名
result = await get_thsr_timetable("台北", "左營", "2024-01-01")

# 使用英文站名
result = await get_thsr_timetable("Taipei", "Zuoying", "2024-01-01")

# 使用站點ID
result = await get_thsr_timetable("1000", "1070", "2024-01-01")
```

### 查詢台北車站即時班次
```python
result = await get_thsr_live_schedule("台北")
```

### 查詢座位狀態
```python
result = await get_thsr_available_seats("台北", "左營", "2024-01-01")
```

## 注意事項

1. **API 限制**：請遵守 TDX API 的使用限制
2. **認證**：確保正確設定 TDX API 金鑰
3. **日期格式**：日期必須使用 YYYY-MM-DD 格式
4. **站名輸入**：支援中英文站名，大小寫敏感

## 錯誤處理

- 無效站名：會拋出 `ValueError` 錯誤
- API 認證失敗：請檢查環境變數設定
- 網路連線問題：請確認網路連線狀態

## 🛠️ 故障排除

### Windows 常見問題

#### 問題 1：找不到 Python

**症狀**：
```
錯誤：找不到 Python 3.8+ 版本
```

**解決方案**：

1. **重新安裝 Python**：
   ```cmd
   # 檢查當前 Python 版本
   py --version
   python --version
   
   # 如果沒有輸出，需要安裝 Python
   winget install Python.Python.3.12
   ```

2. **手動指定 Python 路徑**：
   在 Claude Desktop 設定中加入 `PYTHON_PATH`：
   ```json
   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "PYTHON_PATH": "C:\\Python313\\python.exe",
           "TDX_CLIENT_ID": "你的 Client ID",
           "TDX_CLIENT_SECRET": "你的 Client Secret"
         }
       }
     }
   }
   ```

   常見 Python 路徑：
   - `C:\Python313\python.exe`
   - `C:\Users\[使用者名稱]\anaconda3\python.exe`
   - `C:\Users\[使用者名稱]\AppData\Local\Programs\Python\Python313\python.exe`

3. **清除 npm 緩存**：
   ```cmd
   npm cache clean --force
   ```

#### 問題 2：權限錯誤

**症狀**：
```
安裝依賴失敗
permission denied
```

**解決方案**：

1. **以管理員身份執行**：
   - 右鍵點擊「命令提示字元」
   - 選擇「以系統管理員身分執行」

2. **使用用戶安裝**：
   ```cmd
   py -m pip install --user httpx fastmcp python-dotenv
   ```

#### 問題 3：編碼問題

**症狀**：
```
UnicodeDecodeError
字元編碼錯誤
```

**解決方案**：

1. **設定環境變數**：
   ```cmd
   set PYTHONIOENCODING=utf-8
   ```

2. **在 Claude Desktop 設定中加入**：
   ```json
   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "PYTHONIOENCODING": "utf-8",
           "TDX_CLIENT_ID": "你的 Client ID",
           "TDX_CLIENT_SECRET": "你的 Client Secret"
         }
       }
     }
   }
   ```

#### 問題 4：防毒軟體阻擋

**症狀**：安裝或執行時被防毒軟體阻擋

**解決方案**：
1. 暫時停用即時保護
2. 將 Python 和 Node.js 加入白名單
3. 將專案資料夾加入排除清單

### macOS/Linux 常見問題

#### Python 版本管理

如果系統有多個 Python 版本：

```bash
# 使用 pyenv 管理版本
pyenv install 3.12.0
pyenv global 3.12.0

# 或直接指定路径
export PYTHON_PATH=/usr/local/bin/python3.12
```

#### 權限問題

```bash
# 使用用戶安裝
python3 -m pip install --user httpx fastmcp python-dotenv

# 或使用 homebrew Python
/opt/homebrew/bin/python3 -m pip install httpx fastmcp python-dotenv
```

### 調試模式

如果仍有問題，可以啟用調試模式：

```json
{
  "mcpServers": {
    "thsrc": {
      "command": "npx",
      "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
      "env": {
        "DEBUG_PYTHON_DETECTION": "1",
        "TDX_CLIENT_ID": "你的 Client ID",
        "TDX_CLIENT_SECRET": "你的 Client Secret"
      }
    }
  }
}
```

這會在 Claude Desktop 的日誌中顯示詳細的 Python 偵測過程。

## 授權

本專案使用 MIT 授權條款。

## 相關連結

- [TDX運輸資料流通服務平臺](https://tdx.transportdata.tw/)
- [台灣高鐵官網](https://www.thsrc.com.tw/)
- [Model Context Protocol](https://modelcontextprotocol.io/)