exray
exray 是一個遠端 MCP 伺服器，能夠渲染網頁，並讓您以 TypeScript 註冊自訂的擷取與萃取程式碼，作為可重複使用的命名工具。
您不需要執行或安裝 exray。 它是一個託管服務，位置在 https://mcp.exray.dev/mcp。使用者需提供 bearer token；您則透過 MCP 呼叫工具。
首要事項：是否已連線？
如果 exray 工具未出現在您的工具清單中，表示 MCP 伺服器尚未設定。請告知使用者：
- 在
https://app.exray.dev/sign-in註冊 —/welcome頁面會發放一個 token（僅顯示一次） - 在用戶端新增伺服器 — 設定方式請見 https://docs.exray.dev/docs/mcp-clients
- 重新啟動用戶端 — MCP 設定在啟動時讀取
請不要嘗試用 fetch 或 shell 工具繞過連線問題。直接說明缺少什麼並停止。
選用工具
| 情境 | 工具 |
|---|---|
| 單一頁面，需要內容 | scrape |
| 單一頁面，需要特定欄位 | extract 搭配扁平綱要 |
| 在網站下爬取多個頁面 | crawl，然後 get_crawl_results |
| 反覆執行相同萃取，或邏輯複雜到無法用扁平綱要表達 | 撰寫 define_extractor |
| 頁面需要點擊/滾動才能渲染 | 撰寫 define_fetcher |
| 使用者想查看結果 | 撰寫 define_handler（結果頁面） |
優先使用 scrape / extract。只有當內建工具確實無法表達需求時，才撰寫程式碼 — 註冊的資產代表使用者後續需要維護。
僅接受扁平綱要
extract 僅接受四種型別：string、number、boolean、string[]。不得巢狀。
{ "title": "string", "price": "number", "tags": "string[]" }
巢狀或條件式形狀需要改用 define_extractor。
撰寫程式碼資產
共三種，均為 TypeScript，且都會在接收前進行靜態驗證：
- fetcher — 入口
fetch(ctx)，驅動瀏覽器，回傳PageSnapshot - extractor — 入口
extract(snapshot, ctx?)，將快照轉為 JSON - handler — 入口
handle(request, ctx)，提供公開網頁
嚴格限制 — 違反下列規則的程式碼會在註冊時被拒絕：
- 唯一允許的匯入是
import typefrom@exray/exray-api。不允許執行時期匯入。 如果需要進行 DOM 查詢，請從snapshot.html以字串處理，或是在 fetcher 中透過ctx.page.evaluate()進行 DOM 操作。 - 不得使用
eval/new Function，不得有頂層副作用 - 沙盒內部不可進行網路存取
註冊後資產會處於 draft 狀態 — 無法立即執行。 使用前必須呼叫 publish_definition。這點常常造成混淆；請不要在 define_* 之後就回報成功。
結果頁面 — 讀取 next_action 並據此行動
當您發布 handler 時，回應中會攜帶一個 site 物件。發布成功並不表示頁面可達。 請務必讀取 site.next_action 並告知使用者具體缺少什麼：
next_action | 應告知使用者的內容 |
|---|---|
set_username | 「請在 app.exray.dev/settings/profile 設定使用者名稱 — 網址會是 `<使用者名稱>-<專案>.exray.app」 |
enable_site | 「您的頁面會在 <site.url>。請啟用它：exray site enable，或透過儀表板操作。」 |
shorten_slug | 「<使用者名稱>-<slug> 超過 63 位元組。請使用較短的專案 slug。」 |
contact_support | 伺服器端設定問題；請據此回報 |
null | 頁面已上線，網址為 site.url — 提供連結給使用者 |
絕對不要在 handler 發布完成時不說明頁面位置或阻礙原因。 使用者沒有其他方式可以得知，而「發布成功」會被解讀為「已完成」。
Handler 能與不能做的事：
- 可以讀取此專案的作業資料（透過
ctx.data列出作業、取得結果）、回傳 HTML 或 JSON、根據路徑路由 - 不能儲存任何資料、存取網路、接受表單提交、讀取其他專案的資料
它是一個呈現層，不是後端。
儲存綁定
代理程式碼預設無持續性。如果專案已啟用綁定，fetcher 可以取得 ctx.kv / ctx.db / ctx.storage；extractor 只能取得 ctx.kv；handler 能取得三者但唯讀。
如果呼叫時拋出 binding_not_enabled，表示綁定未開啟 — 這需要管理員 token（exray bindings set --kv on）。請告知使用者；您無法自行啟用。
值得辨識的錯誤
| 錯誤 | 意義 |
|---|---|
403 forbidden | token 缺少某個作用域。執行需要 tools.execute，註冊需要 tools.define，發布需要 tools.publish，帳號操作需要 admin |
402 | 每月配額已用完。請停止並告知使用者 |
definition_incompatible_api | 資產是針對不同 major 版本的 @exray/exray-api 編譯的。請重新註冊 |
extractor_invalid / fetcher_invalid | 靜態驗證拒絕了程式碼 — 通常是執行時期匯入或頂層副作用 |
binding_not_enabled | 請見上方儲存綁定說明 |
concurrent_exceeded | 同時進行的呼叫過多。請等候；不要在緊密迴圈中重試 |
遇到 budget_exceeded 或 402 時，請停止。重試只會消耗使用者配額而沒有進展。
作用域
第一次擷取的工作流程只需要 tools.read + tools.execute。註冊與發布需要 tools.define / tools.publish。任何涉及帳號的操作 — 發放 token、啟用結果頁面、切換綁定 — 都需要 admin，且那是使用者的責任，不是您的。
完整文件
https://docs.exray.dev — 快速入門、用戶端設定、CLI 參考、結果頁面、工具參數，以及萃取器合約。