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（使用扁平 schema） |
| 抓取同一站点下的多个页面 | crawl，然后 get_crawl_results |
| 需要重复执行相同提取，或逻辑复杂超出扁平 schema | 编写 define_extractor |
| 页面需要点击/滚动才能渲染 | 编写 define_fetcher |
| 用户想要查看结果 | 编写 define_handler（结果页面） |
优先使用 scrape 和 extract。只有当内置工具确实无法表达需求时，才编写代码——注册的资产需要用户后续维护。
仅支持扁平 Schema
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 是
import typefrom@exray/exray-api。不允许运行时 import。 如果需要进行 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 设置用户名——地址格式为 <username>-<project>.exray.app" |
enable_site | "你的页面将在 <site.url> 可用。启用方法：exray site enable，或在仪表盘中操作。" |
shorten_slug | "<username>-<slug> 超过 63 字节。请使用更短的项目 slug。" |
contact_support | 服务端配置问题，请按此上报 |
null | 页面已上线，地址为 site.url——将链接提供给用户 |
发布 handler 后，必须告知用户页面在哪里，或者阻止访问的原因。 用户没有其他途径获知这些信息，而“发布成功”会被误认为是“已完成”。
handler 的能力范围：
- 可以 通过
ctx.data读取当前项目的任务数据（列任务、取结果），返回 HTML 或 JSON，按路径路由 - 不能 存储任何内容、访问网络、接受表单提交，或读取其他项目的数据
它只是一个展示层，而非后端。
存储绑定
默认情况下，Agent 代码没有持久化能力。如果项目已启用绑定，fetcher 可使用 ctx.kv / ctx.db / ctx.storage；extractor 只能使用 ctx.kv；handler 可以只读方式使用所有三种。
如果调用抛出 binding_not_enabled，说明绑定尚未启用——这需要管理员 token（exray bindings set --kv on）。请告知用户；你不能自行启用它。
值得关注的错误
| 错误 | 含义 |
|---|---|
403 forbidden | Token 缺少某个 scope。执行需要 tools.execute，注册需要 tools.define，发布需要 tools.publish，账户操作需要 admin |
402 | 月度配额已用完。请停止操作并告知用户 |
definition_incompatible_api | 资产是针对不同版本 @exray/exray-api 编译的。请重新注册 |
extractor_invalid / fetcher_invalid | 静态验证拒绝了代码——通常是运行时 import 或顶层副作用 |
binding_not_enabled | 见上方存储绑定部分 |
concurrent_exceeded | 同时运行的调用过多。请等待；不要在紧密循环中重试 |
遇到 budget_exceeded 或 402 时，请停止操作。重试会在没有进展的情况下消耗用户配额。
Scopes
首次抓取工作流只需要 tools.read + tools.execute。注册和发布需要 tools.define / tools.publish。任何涉及账户的操作——颁发 token、启用结果页面、切换绑定——都需要 admin，并且应由用户完成，而非你。
完整文档
https://docs.exray.dev —— 快速入门、客户端配置、CLI 参考、结果页面、工具参数以及提取器契约。