# 台灣FDA藥品查詢MCP服務器

這是一個基於FastMCP框架開發的台灣FDA藥品查詢服務器，提供了完整的藥品資訊查詢和仿單下載功能。

## 功能特色

### 🔍 核心查詢功能
- **英文品名查詢** (`search_drugs_by_english_name`)
  - 根據英文品名關鍵字查詢藥品
  - 返回詳細的藥品資訊包括許可證號、中文品名、英文品名、申請商等
  - 自動提取仿單GUID供下載使用

- **進階多條件查詢** (`advanced_drug_search`)
  - 支援許可證號、中文品名、英文品名、申請商、有效成分等多種查詢條件
  - 可組合使用多個查詢條件進行精確搜索
  - 支援模糊搜索和部分匹配

### 🔐 驗證碼處理
- **驗證碼圖片獲取** (`get_captcha_image`)
  - 自動獲取台灣FDA網站的4位數字驗證碼
  - 返回Base64編碼的圖片和識別提示
  - 支援重新獲取驗證碼功能

### 📄 仿單下載功能
- **單個仿單下載** (`download_insert`)
  - 使用藥品GUID下載對應的PDF仿單
  - 自動檢查文件完整性和格式
  - 支援自定義輸出路徑

- **批量仿單下載** (`batch_download_inserts`)
  - 批量下載多個藥品的仿單
  - 自動生成有序的文件名
  - 提供詳細的下載結果統計

### 🛠️ 輔助工具
- **結果格式化** (`format_search_results_tool`)
  - 將原始查詢結果轉換為易讀的格式
  - 結構化展示藥品資訊
  - 便於數據分析和處理

## 技術架構

### 依賴庫
- **FastMCP** - MCP框架
- **requests** - HTTP請求處理
- **beautifulsoup4** - HTML解析
- **Pillow** - 圖像處理
- **uv** - 項目管理和依賴安裝

### 網站端點
- 查詢API: `https://mcp.fda.gov.tw/q_insert/qcase_01A1.asp` (POST)
- 驗證碼: `https://mcp.fda.gov.tw/CheckCode.aspx` (GET)
- 仿單下載: `https://mcp.fda.gov.tw/insert/pdfcasefile/{guid}` (GET)

## 安裝與部署

### 前置要求
- Python 3.10+
- uv包管理器

### 部署步驟

1. **克隆或下載項目**
   ```bash
   # 項目目錄
   /workspace/fda-taiwan-mcp/
   ```

2. **啟動MCP服務器**
   ```bash
   # 自動創建虛擬環境並安裝依賴
   sh run.sh
   ```

3. **配置MCP客戶端**
   ```json
   {
     "name": "agent_generated_fda_taiwan_drug_search",
     "command": "sh /workspace/fda-taiwan-mcp/run.sh"
   }
   ```

## 使用指南

### 基本使用流程

1. **獲取驗證碼**
   ```
   工具: get_captcha_image
   返回: Base64編碼的驗證碼圖片
   ```

2. **識別驗證碼**
   - 查看返回的驗證碼圖片
   - 手動識別圖片中的4位數字

3. **查詢藥品**
   ```
   工具: search_drugs_by_english_name
   參數:
   - english_name: "aspirin"
   - captcha: "1234"  # 剛才識別的驗證碼
   ```

4. **下載仿單**
   ```
   工具: download_insert
   參數:
   - guid: "從查詢結果中獲得的GUID"
   - output_path: "/path/to/save/drug_insert.pdf"
   ```

### 範例使用場景

#### 場景1：查詢常見藥品
```
# 1. 獲取驗證碼
get_captcha_image()

# 2. 查詢阿斯匹林
search_drugs_by_english_name("aspirin", "1234")

# 3. 下載仿單（如果有結果）
download_insert("GUID_FROM_RESULTS", "/tmp/aspirin_insert.pdf")
```

#### 場景2：進階查詢
```
# 組合多個條件查詢
advanced_drug_search(
    ename="metformin",
    agent_name="默沙東",
    captcha="5678"
)
```

#### 場景3：批量處理
```
# 批量下載多個仿單
batch_download_inserts(
    guids=["guid1", "guid2", "guid3"],
    output_dir="/tmp/drug_inserts"
)
```

## 錯誤處理

### 常見錯誤及解決方案

1. **驗證碼錯誤**
   - 錯誤：`驗證碼必須是4位數字`
   - 解決：重新獲取驗證碼圖片並仔細識別

2. **查無結果**
   - 錯誤：`未找到符合條件的藥品資訊`
   - 解決：檢查查詢條件，嘗試使用更寬鬆的搜索條件

3. **網路連接問題**
   - 錯誤：`網路請求失敗`
   - 解決：檢查網路連接，稍後重試

4. **仿單下載失敗**
   - 錯誤：`下載的內容不是有效的PDF文件`
   - 解決：檢查GUID是否正確，確認網路連接

## 注意事項

### 使用限制
- 每次查詢需要4位數字驗證碼
- 查詢頻率建議間隔1-2秒避免被封鎖
- 大量查詢建議使用批量處理功能

### 安全考量
- 驗證碼需要人工識別，無法自動化
- 適當的請求延遲避免對服務器造成壓力
- 下載的PDF文件建議進行安全檢查

### 性能優化
- 使用批量下載功能提高效率
- 合理設置請求延遲
- 及時清理臨時文件

## 開發與貢獻

### 項目結構
```
fda-taiwan-mcp/
├── src/
│   └── fda_taiwan_mcp/
│       ├── __init__.py
│       └── tools.py          # 核心工具實現
├── server.py                 # MCP服務器主程序
├── run.sh                    # 啟動腳本
├── mcp-server.json          # MCP配置文件
├── README.md                # 項目文檔
└── examples/                # 使用示例
```

### 擴展開發
- 可以在 `tools.py` 中添加新的查詢功能
- 支持擴展新的網站端點
- 可以添加更多的數據處理和格式化功能

## 版本信息

- **版本**: 1.0.0
- **作者**: MiniMax Agent
- **更新日期**: 2025-11-05
- **Python版本**: 3.10+
- **MCP版本**: FastMCP 2.13+

## 許可證

此項目遵循MIT許可證。

## 技術支持

如有問題或建議，請通過以下方式聯繫：
- 創建Issue描述問題
- 提交Pull Request貢獻代碼
- 查看文檔尋找解決方案