# 模型接入 (MCP/Agent)

本文為您介紹如何將 FIRERPA 與大型語言模型進行對接（基於 MCP 或命令），FIRERPA 已在底層實現了 MCP 伺服器端協議以及 OpenAI 原生的 tool-call 功能，支援您自行編寫 MCP 插件並透過 65000 標準連接埠進行服務，或者繼承 Agent 類別實現全自動的 tools 呼叫。

## 內建 Agent 命令

透過內建的 `agent` 命令，您可以快速透過大型語言模型完成完全口語化的任務，支援任何相容 OpenAI API + toolcall 的服務供應商或是自建服務。配合內建的 crontab，您可以實現口語化任務的定時執行。

```{hint}
`agent` 命令需要在內建的終端機內使用，同時需要您提供有效的 API 以及金鑰。各個大型語言模型的使用表現可能不一致，請選擇最適合您的模型。我們推薦 gemini、openai、deepseek、glm 等。
```

| 參數名稱 | 類型 | 必填 | 預設值 | 說明 |
| :--- | :--- | :--- | :--- | :--- |
| `--api` | 字串 (str) | 是 | - | API 端點 |
| `--model` | 字串 (str) | 是 | - | 模型名稱 |
| `--temperature` | 浮點數 (float) | 否 | `0.2` | 模型取樣溫度 |
| `--key` | 字串 (str) | 是 | - | 用於身分驗證的 API 金鑰 |
| `--vision` | 布林值 (bool) | 否 | `False` | 是否啟用視覺模式 |
| `--imsize` | 整數 (int) | 否 | `1000` | 視覺模式下的圖像尺寸 |
| `--prompt` | 字串 (str) | 是 | - | 代理（Agent）執行的指令 |
| `--max-tokens` | 整數 (int) | 否 | `16384` | 生成的最大 Token 數量 |
| `--step-delay` | 浮點數 (float) | 否 | `0.0` | 步驟之間的延遲時間 |

```{attention}
需要注意的是，參數 API 的位址是完整的位址，而不是 base_url，通常需要在 base_url 後擴充 `/chat/completions` 來拼接出完整的 API 位址。
```

準備好所需的資訊後，您可以透過在遠端桌面的終端機中輸入以下命令，讓 AI 自動操作您的裝置。

```bash
agent --api https://generativelanguage.googleapis.com/v1beta/openai/chat/completions --key YOUR_API_KEY --model gemini-2.5-flash --prompt "幫我打開設定 APP，套件名稱為 com.android.settings，找到網路設定，開啟飛航模式"
```

如果您的任務提示過長，也可以透過檔案的方式提供模型提示詞。

```bash
agent --api https://generativelanguage.googleapis.com/v1beta/openai/chat/completions --key YOUR_API_KEY --model gemini-2.5-flash --prompt /path/to/prompt.txt
```

## Claude & Cursor 接入（MCP）

此部分為您介紹如何將 FIRERPA 的 MCP 功能接入您的大型語言模型用戶端，我們僅以 Claude 及 Cursor 作為範例，您也可以在任何其他支援 MCP 協議的地方使用它。

```{note}
FIRERPA 內建的 MCP 服務支援 tool-call、resource-read、prompts、進度通知及日誌。
```

```{attention}
請注意 8.0 伺服器端和 9.0 伺服器端的通訊協議不同，9.x 為 streamable-http，8.x 為 sse。
```

### 安裝官方擴充

我們為您提供了一個官方 MCP 服務，您可以在 <a href="https://github.com/firerpa/lamda/blob/HEAD/extensions/firerpa.py" target="_blank">extensions/firerpa.py</a> 下載此擴充模組，您也可以參考其編寫方法自行編寫或擴充插件功能。下載擴充插件腳本後，透過遠端桌面或手動 push 將其上傳到裝置的 `/data/usr/modules/extension` 目錄中，重新啟動裝置或 FIRERPA 服務即可。

```{attention}
8.0 的擴充腳本與 9.0 的擴充腳本不相容，請嚴格確認您的伺服器端版本，並從 GitHub 分支拉取對應的腳本。
```

### 使用官方擴充

對於 **Claude**，您需要先找到 Claude 的設定頁面，並依照下圖所示的步驟進行操作。並根據提示，編輯 Claude 的 `claude_desktop_config.json` 設定檔，然後寫入以下的 MCP JSON 服務設定。


```json
{"mcpServers": {"firerpa": {"command": "npx", "args": ["-y", "supergateway", "--streamableHttp", "http://192.168.0.2:65000/firerpa/mcp/"]}}}
```

<p align="center">
<img src="/assets/images/claude-settings.png" alt="示例" width="auto">
</p>

對於 **Cursor**，您需要打開 Cursor Settings，並依照圖示進行操作，然後輸入以下設定。

```json
{"mcpServers": {"firerpa": {"url": "http://192.168.0.2:65000/firerpa/mcp/"}}}
```

<p align="center">
<img src="/assets/images/cursor-settings.png" alt="示例" width="auto">
</p>

```{attention}
請注意，需將設定中的連結替換為您自己裝置的 IP 位址。
```

### 編寫 MCP 擴充

```{hint}
說明文件即將推出，敬請期待。
```