讓任何靜態網站不用後端，就能成為 MCP 工具伺服器。

MCP Pages 定義了靜態網站提供前端 WebMCP 工具的開放規範；ai-proxy 是跑在使用者本機上的零依賴參考轉送，將瀏覽器分頁安全地接上 Claude Code 與各類 MCP 客戶端。

快速開始指令

零外部 npm 套件依賴

直接複製以下指令到終端機執行（網址已於執行期自動替換為本站目前的部署路徑）：

# 1. 啟動本機 ai-proxy 轉送服務（預設監聽 127.0.0.1:8788）
npx ai-proxy serve

# 2. 將本站的 MCP 頁加入允許清單並註冊到 Claude Code
npx ai-proxy add https://<host>/<org>/<repo>/mcp --name ai-proxy

# 3. 開啟帶管理金鑰的本機儀表板分頁
npx ai-proxy open dashboard

想為自己的 GitHub Pages 加上 MCP 頁？匯出零依賴前端模組並執行靜態檢查：

npx ai-proxy vendor --out ./vendor/ai-proxy-web
npx ai-proxy doctor --dir .

ai-proxy 本機轉送管理儀表板

開啟獨立儀表板頁

正在偵測本機 ai-proxy 轉送服務...

MCP Pages 運作架構

GitHub Pages 等純靜態託管只提供檔案下載，無法執行常駐後端程序。MCP Pages 反轉了連線方向：工具邏輯在使用者自己的瀏覽器分頁內透過 navigator.modelContext 註冊，並主動連向本機的 127.0.0.1:8788。

sequenceDiagram participant CC as Claude Code / MCP 客戶端 participant Relay as 本機 ai-proxy (127.0.0.1:8788) participant Tab as 瀏覽器分頁 (mcp.html) CC->>Relay: POST /mcp?url=https://.../mcp.html (tools/call) alt 分頁尚未連線（自動喚醒） Relay->>Tab: 開啟分頁並於 fragment 帶入 mcp-key=...&mcp-port=8788 Tab->>Tab: 將 mcp-key 移入 history.state 並抹除網址列 Tab->>Relay: POST /tab/v1/hello (Bearer pageKey, tools[]) end Tab->>Relay: GET /tab/v1/poll?sessionId=sid Relay-->>Tab: 200 OK { callId, rpc } Tab->>Relay: POST /tab/v1/ack { sessionId, callId } Tab->>Relay: POST /tab/v1/reply { sessionId, callId, response } Relay-->>CC: JSON-RPC 2.0 回應 { id: 1, result }

針對共用 Origin 的七條安全底線

同一個 GitHub 帳號或組織下的所有 https://<user>.github.io/<repo>/ 專案網站共用同一個瀏覽器 Origin。若本機橋接直接信任 Origin 或把金鑰存進 localStorage，同帳號下的惡意專案即可劫持轉送。ai-proxy 強制實作七條底線：

規則	防禦威脅	規範機制
`規則一`	同 Origin 惡意鄰居專案	路徑邊界網址前綴允許清單（`https://u.github.io/a/` 絕不匹配 `/a-evil/`）。
`規則二`	同 Origin 儲存空間金鑰外洩	每頁獨立隨機金鑰由 URL fragment (`#mcp-key=`) 傳入，立即移入分頁專屬 `history.state` 並抹除網址列。
`規則三`	網頁偽造 `/mcp` 請求	`POST /mcp` 若帶有瀏覽器 `Origin` 標頭，一律回傳 `403 Forbidden`。
`規則四`	`/v1` 提示詞注入越權呼叫工具	`/v1/chat/completions` 預設零工具；僅允許由 `--allow-tool` 逐一點名且 `readOnlyHint === true` 的唯讀工具。
`規則五`	未授權頁面竊取管理金鑰	`POST /admin/v1/open-dashboard` 僅由本機開啟新分頁，絕不在 HTTP 回應內回傳金鑰，並限制每 10 秒最多一次。
`規則六`	背景隱形執行	工具必須在肉眼可見的瀏覽器分頁中執行，並顯示工具清單與呼叫次數。
`規則七`	遺忘關閉萬用字元 `*`	`/v1` 萬用字元 `*` 強制鎖死為零工具純對話、預設 15 分鐘自動到期，並在儀表板顯示醒目警告。

規範文件目錄

總覽與架構說明 (docs/zh-TW/index.md)

為什麼靜態網站需要前端 WebMCP，以及三大組件如何協作。

English

MCP Pages 規範 (docs/zh-TW/spec.md)

頁面結構、網址正規化、navigator.modelContext 相容層與工具標註。

English

轉送通訊協定 (docs/zh-TW/protocol.md)

/tab/*、/mcp、/v1 與 /admin/v1/* 端點、JSON-RPC ID 改寫與重連寬限期。

English

安全模型與威脅分析 (docs/zh-TW/security.md)

深入解析共用 GitHub Pages Origin 下的七條安全底線。

English