# Ax MCP — 遠端網頁爬蟲 MCP Server

> 💡 **去 AI 味聲明**：本專案文檔使用台灣在地化繁體中文去 AI 味工具 [opencode-speak-human-tw](https://github.com/cawa0505/opencode-speak-human-tw) 進行校對與語感微調，拒絕罐頭套話與空泛修辭。

基於 Node.js 的 MCP Server，封裝 [yusukebe/ax](https://github.com/yusukebe/ax)（「AI 時代的 curl」），
透過 [supergateway](https://github.com/supercorp-ai/supergateway) 橋接為 **遠端 Streamable HTTP（`/mcp`）** 介面，供 OpenCode Interpreter 呼叫（SSE 亦可）。

> ⚠️ **關於 ax 的重要說明**：規格書假設 ax 是「Playwright 爬蟲」並有 `--selector` / `--format` / `--wait` 參數。
> 實際上 ax **不是** Playwright 工具——它是用 Bun + linkedom 做的**非瀏覽器**快速爬蟲，不執行 JavaScript。
> 它的真實參數是 `--md`（markdown）、`--json`、`--row`、`--outline`、positional selector、`-m <secs>`（逾時）等。
> 本專案已把規格的 `scrape_web` 介面**對應到 ax 真實 CLI**（見下方參數對照），因此可正常運作。
> 若你需要抓取 JS 重度渲染的 SPA，請改用瀏覽器型工具（Playwright / playwright-cli MCP），ax 不適用。

## 專案結構

```
├── src/
│   └── index.ts        # MCP Server 核心邏輯
├── build/              # tsc 編譯產物（node build/index.js）
├── package.json        # 依賴（@modelcontextprotocol/sdk, supergateway, zod）
├── tsconfig.json
├── Dockerfile          # ax-mcp: node + bun + supergateway
├── docker-compose.yml  # 單個 service: ax-mcp(3014)
└── README.md
```

## 工具：`scrape_web`

| 參數 | 類型 | 預設 | 說明 | 對應 ax |
|------|------|------|------|---------|
| `url` | string (必填) | — | 目標網址 | positional |
| `selector` | string (選填) | — | CSS selector 精確擷取 | positional + `--text` |
| `format` | `"text"` \| `"json"` | `"text"` | 輸出格式 | `text`→`--md`；`json`→`--json` |
| `wait` | number (選填) | — | 秒數預算 | 對應 ax `-m`（請求逾時）；ax 無瀏覽器等待 |

- 有 `selector`：擷取該 selector 匹配元素的文字（`--text`）。
- 無 `selector` + `format:"text"`：整頁可讀 markdown（`--md`）。
- 無 `selector` + `format:"json"`：結構化抓取報告（`{status, ok, ms, headers, body}`）。
- 輸出會經正則濾除 ANSI color codes，確保 LLM 收到純淨文字。
- 執行失敗回傳 `{ isError: true, content: [...] }`（含 stderr）。

## 傳輸協定與架構說明（SSE vs Streamable HTTP）

### SSE (`http://localhost:8000/sse`) 與 Streamable HTTP (`/mcp`) 的底層差異

標準的 MCP 伺服器大多使用 `SSE (Server-Sent Events)` 傳輸。不過，當你在跨主機、遠端或 Homelab 叢集部署（例如讓 OpenCode Interpreter 跨網連線遠端 MCP）時，這兩種協定在底層運作上有決定性的差別：

1. **`http://localhost:8000/sse` (標準 SSE 協定)**
   * **缺點**：標準 SSE 是有狀態（Stateful）的協定。當 OpenCode 這類用戶端連線時，必須維持一條長連線。一旦跨越外網或經過反向代理（如 Caddy、Nginx），這條長連線很容易因為逾時、網路抖動或代理伺服器的快取限制而斷線，造成 MCP 連線不穩定。
   * **適用場景**：完全在本地端（Localhost）跑 stdio 的開發環境，或用戶端與伺服器位於同一個安全且無代理阻擋的區域網路。

2. **`http://<host>:3014/mcp` (Streamable HTTP 協定)**
   * **優點**：透過 [supergateway](https://github.com/supercorp-ai/supergateway)，將 MCP 伺服器轉換為無狀態（Stateless）的標準 HTTP POST 請求。
   * **特色**：
     * **穿透力強**：每次工具呼叫都是獨立的短 HTTP 連線，能輕鬆穿透 CDN、反向代理、WAF 與 VPN，不會被防火牆或代理伺服器阻擋。
     * **維護簡單**：不需維持 TCP 長連線，自然沒有逾時斷連、需要重連的問題。這正是 OpenCode `type: "remote"` 的原生運作方式。
     * **專案定位**：本專案直接將 supergateway 整合進 Docker，並預設輸出為 `streamableHttp`，提供跨主機、跨網段穩定的遠端連線配置範例。

---

## Docker 部署

本專案支援兩種 Docker 部署方式：**直接從 GitHub Registry 拉取預建映像檔**（最快、免下載原始碼），或 **Clone 專案本機編譯建置**（適合客製化與二次開發）。

### 方式一：直接使用 GitHub Registry 部署（免 Clone）

若您僅需使用服務，無需下載專案原始碼，只需在主機的部署目錄（例如 `$HOME/ax-mcp`）建立一個 `docker-compose.yml` 檔案：

```yaml
services:
  ax-mcp:
    image: ghcr.io/cawa0505/ax-mcp:latest
    container_name: ax-mcp
    restart: unless-stopped
    ports:
      - "3014:8000"
```

並於該目錄執行以下指令拉取並啟動：

```bash
docker compose up -d
```

---

### 方式二：Clone 專案本機編譯部署（適合二次開發）

如果您想自訂或擴充功能，可以進行二次開發：
- **調整爬蟲邏輯**：希望自訂 `ax` 的抓取細節或前處理規則。
- **擴充 MCP 工具**：在 `src/index.ts` 內增加自訂的 MCP Tool。
- **效能調優**：修改 `Dockerfile` 內的快取與編譯設定。

請複製本專案，並依以下步驟建置：

```bash
# 複製專案
git clone https://github.com/cawa0505/ax-mcp.git
cd ax-mcp

# 啟動並於本機編譯建置
docker compose up -d --build
```

#### 本機測試與偵錯步驟

如果不使用 Docker，想在本機直接編譯、修改與測試，請執行以下指令：

```bash
# 1. 安裝套件
npm install

# 2. 本地編譯（tsc -> build/index.js）
npm run build

# 3. 測試執行 stdio 協定（可供標準 MCP client 連線）
node build/index.js
```

本地透過 `supergateway` 進行橋接與協定轉換測試：

```bash
# 預設啟動為 SSE（端點：http://localhost:8000/sse）
npx supergateway --stdio "node build/index.js" --port 8000

# 啟動為 Streamable HTTP（端點：http://localhost:8000/mcp，對應 OpenCode "type: remote"）
npx supergateway --stdio "node build/index.js" --port 8000 --outputTransport streamableHttp
```

---

### 服務說明

啟動後：
- `ax-mcp` 將於 `http://<host>:3014/mcp` 提供 Streamable HTTP 介面（容器內監聽 8000）。
- 內部透過 `supergateway` 將 `node build/index.js`（stdio）包裝為遠端 MCP 介面。
- 建置時已將 `bunx` 快取預熱完畢（原生處理 `yusukebe/ax` 的 git 依賴），因此運行期無需額外聯網下載 `ax`。

> 💡 **關於瀏覽器型爬蟲 (Playwright)**：
>
> 由於 Playwright MCP 是微軟官方維護的成熟標準工具 (`@modelcontextprotocol/server-playwright` / `mcp/playwright`)，本專案定位是基於 `yusukebe/ax` 的輕量、超高速非瀏覽器 HTML/XML 擷取。
> 
> 若你仍需要動態網頁渲染 (SPA) 與瀏覽器自動化，建議直接使用 Microsoft 官方 Playwright MCP。你可透過 `supergateway` 以 `--stateful` 模式橋接官方 stdio 程序以實現遠端 Streamable HTTP：
> ```bash
> npx supergateway --stdio "npx -y @modelcontextprotocol/server-playwright" --port 3015 --stateful
> ```

### 環境變數

| 變數 | 預設 | 說明 |
|------|------|------|
| `AX_COMMAND` | `bunx yusukebe/ax` | 覆寫 ax 呼叫方式。允許 git fetch 的環境可用 `npx -y yusukebe/ax`；若有靜態 `ax` 可用 `ax`。 |

## OpenCode 連線

請在 OpenCode 設定檔 `~/.config/opencode/opencode.json` 的 `"mcp"` 區段中加入本服務。本服務以 **Streamable HTTP** 暴露（路徑 `/mcp`），對應 OpenCode 的 `type: "remote"`：

```json
{
  "mcp": {
    "ax-mcp": {
      "type": "remote",
      "url": "http://<ax-mcp-host>:3014/mcp"
    }
  }
}
```

> 本機部署將容器 8000 對應到 host 的 **3014**（8000 已被佔用）。若你改了 `docker-compose.yml` 的 ports 對應，請同步修改此處的 port。

若 OpenCode 與容器不在同網段 / 需跨網，請在 `docker-compose.yml` 用 `--cors` 限制來源，
並視情況以反向代理（Caddy/Pangolin）加上 TLS 與驗證。