# FT260Q MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)](https://python.org)

**FT260Q MCP Server** 是一個遵循 **Model Context Protocol (MCP)** 標準的硬體橋接伺服器。
透過 FTDI 官方 **LibFT260**（USB HID 協定），讓 AI Agent 與開發者能直接控制
FT260 / FT260Q 晶片的 **I2C Master**、**UART**、**GPIO**（14 支腳位）與 **外部中斷** 硬體介面。

---

## 晶片特性與架構

FT260 是 FTDI 推出的 USB 2.0 Full-Speed HID 轉 I2C / UART / GPIO 橋接控制器：
- **免驅動（Driverless HID）**：採用標準 USB HID Class 協定，在 Windows、Linux、macOS 上隨插即用，不需額外安裝 VCP 或 D2XX 核心驅動。
- **雙介面複合裝置（Composite Device）**：
  - **Interface 0**：I2C Master 控制器（最高 3.4 Mbps）與 GPIO 0~5。
  - **Interface 1**：全功能 UART 控制器（最高 12 Mbps）與 GPIO A~H / 外部中斷通報。
- **14 支 GPIO 腳位**：支援靈活的引腳多工配置（I2C/GPIO、UART/GPIO、喚醒中斷、開漏輸出 Open-Drain、上拉/下拉配置）。

---

## 硬體接線配置（本實驗環境）

| FT260 腳位 | 預設/配置功能 | 連接目標 | Saleae 邏輯分析儀 | 說明 |
| :--- | :--- | :--- | :--- | :--- |
| **IO0** | I2C SCL | 雷達 SCL | **Channel 0 (D0)** | I2C 時脈線（已驗證波形與協定） |
| **IO1** | I2C SDA | 雷達 SDA | **Channel 1 (D1)** | I2C 資料線（已驗證波形與協定） |
| **IO2** | GPIO IN | 雷達輸出中斷 | **Channel 2 (D2)** | 中斷狀態輸入讀取 |
| **IO3** | GPIO OUT | — | **Channel 3 (D3)** | GPIO 輸出驗證（方波產生與閉環驗證） |

---

## 安裝與執行

```bash
# 建立虛擬環境
python -m venv .venv

# 啟動虛擬環境 (Windows)
.venv\Scripts\activate

# 安裝本專案 (Editable 模式)
pip install -e .
```

### 啟動方式
- CLI 入口：`ft260q-mcp` 或 `ft260-mcp`
- Python 模組：`python -m ft260_mcp`

---

## MCP 整合配置 (mcp_config.json)

在任何支援 MCP 的 Agent（例如 Cline、Claude Desktop、Antigravity）中配置：

```json
{
  "mcpServers": {
    "ft260-bridge": {
      "command": "ft260q-mcp",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

> 💡 **提示**：若未將 CLI 加入系統 PATH，亦可使用 Python 模組形式啟動：
> ```json
> {
>   "mcpServers": {
>     "ft260-bridge": {
>       "command": "python",
>       "args": ["-m", "ft260_mcp"],
>       "env": {
>         "PYTHONUNBUFFERED": "1"
>       }
>     }
>   }
> }
> ```

---

## Tool Catalog（MCP 工具清單）

### 1. 裝置管理 (Device Management)
| 工具名稱 | 說明 |
| :--- | :--- |
| `ft260_list_devices()` | 列出系統中所有 FT260 裝置與 HID 介面路徑 |
| `device_select(device_index)` | 切換預設操作的 FT260 實體晶片 (0, 1, ...) |
| `device_get_version()` | 查詢晶片版本與 LibFT260 函式庫版本 |
| `device_set_clock(clk_mhz)` | 設定系統時脈 (12MHz / 24MHz / 48MHz) |

### 2. I2C Master 控制器
| 工具名稱 | 說明 |
| :--- | :--- |
| `i2c_init(kbps)` | 初始化 I2C Master（常見速率：100, 400, 1000, 3400 Kbps） |
| `i2c_scan()` | 掃描 I2C 匯流排 7-bit 位址 (0x08 ~ 0x77) |
| `i2c_write(addr, data_hex, send_stop)` | 向 7-bit Slave 寫入十六進位資料 |
| `i2c_read(addr, length, send_stop, timeout_ms)` | 從 7-bit Slave 讀取指定長度資料 |
| `i2c_write_read(addr, tx_hex, rx_length, timeout_ms)` | **原子化 Repeated START** 寫入後讀取 |
| `i2c_read_register(addr, reg_addr, length, timeout_ms)` | 讀取 Slave 內部暫存器資料 |
| `i2c_write_register(addr, reg_addr, data_hex)` | 寫入 Slave 內部暫存器 |
| `i2c_get_status()` | 查詢匯流排與控制器狀態（busy, nack, idle, etc.） |
| `i2c_reset()` | 軟體重置 I2C Master 控制器 |

### 3. UART 控制器
| 工具名稱 | 說明 |
| :--- | :--- |
| `uart_init(baud_rate, flow_control, data_bits, stop_bits, parity)` | 初始化 UART 介面 |
| `uart_config(...)` | 動態調整鮑率、資料位元、同位元與停止位元 |
| `uart_write(data)` | 傳送資料（支援 Hex 或 ASCII） |
| `uart_read(length, timeout_ms)` | 從接收佇列讀取資料 |
| `uart_write_read(tx_data, rx_length, timeout_ms)` | 傳送並等待回覆 |
| `uart_get_status()` | 查詢目前通訊參數與 RX 佇列狀態 |
| `uart_reset()` | 重置 UART 控制器 |

### 4. GPIO 控制器 (14 支腳位)
| 工具名稱 | 說明 |
| :--- | :--- |
| `gpio_set_direction(pin, direction)` | 設定腳位方向（IN / OUT） |
| `gpio_write(pin, value)` | 輸出數位電位 (HIGH / LOW) |
| `gpio_read(pin)` | 讀取目前腳位電位 |
| `gpio_get_all()` | 查詢全 14 支腳位電位與方向報告 |
| `gpio_set_function(pin, function)` | 多工引腳切換 (GPIO/I2C/UART/WAKEUP/etc.) |
| `gpio_pulse(pin, count, high_time_s, low_time_s)` | 在指定腳位產生方波/脈波列（用於儀器量測） |
| `gpio_set_open_drain(pins_mask)` | 設定 GPIO0~5 開漏輸出 |
| `gpio_reset_open_drain()` | 重置開漏輸出為推挽輸出 |

### 5. 外部中斷 (Interrupt)
| 工具名稱 | 說明 |
| :--- | :--- |
| `interrupt_config(trigger_type, delay_ms)` | 設定外部中斷觸發模式 (rising/falling/high/low) |
| `interrupt_get_flag()` | 讀取中斷觸發旗標 |
| `interrupt_clear_flag()` | 清除中斷旗標 |