MarkLayer

marklayer-mcp

MCP（Model Context Protocol）服务，可将 MarkLayer 标注接入 AI 编码 Agent。

用户使用 MarkLayer 为任意网页添加标注后，Agent 会收到这些评论，并将其作为结构化任务队列处理：它可以确认、解决、忽略每条评论，也可以逐条回复，而人类可以实时看到状态更新。反过来也可以：让 Agent 查看某个房间并评审页面，它就能留下自己的评论和文案编辑建议，供人类审核处理。

安装

你可能不需要安装。每个 MarkLayer 分享链接本身就是远程 MCP 服务，地址为原链接后加 /mcp。因此，支持远程（Streamable HTTP）服务的客户端无需安装任何内容即可连接：

claude mcp add --transport http marklayer https://marklayer.app/s/abc123/mcp

添加 ?agent=cursor 或其他名称，让房间内的人知道是谁在处理；默认值为 agent。该端点绑定到对应房间，因此具备下方列出的所有工具，但 marklayer_connect_room 除外。

此软件包提供相同工具的 stdio 版本，不包含 Claude 专用配置。当客户端无法连接远程服务，或你希望安装一次即可处理所有房间（Claude Code、Cursor、Windsurf、VS Code、Codex CLI 等）时，请使用此版本：

# Claude Code:
claude mcp add marklayer -- npx -y marklayer-mcp

# Or pre-connect to a specific room:
claude mcp add marklayer -- npx -y marklayer-mcp --room https://marklayer.app/s/abc123

对于其他 MCP 客户端，请添加一个指向相同命令的 stdio 服务条目（根据你的客户端调整配置文件或键名，例如 Cursor 的 ~/.cursor/mcp.json、Windsurf 的 mcp_config.json、VS Code 的 .vscode/mcp.json 等）：

{
  "mcpServers": {
    "marklayer": {
      "command": "npx",
      "args": ["-y", "marklayer-mcp"],
      "env": { "MARKLAYER_AGENT": "cursor" }
    }
  }
}

设置 MARKLAYER_AGENT（或 --agent）以标识此 Agent——人类会看到它作为评论作者和“分配给”徽标，因此非 Claude 客户端不应使用默认值。

使用方法

在 Agent 提示词中：

关注我的 MarkLayer 标注。对每条标注，先确认，再修复，最后附上摘要并将其解决。

Agent 会循环调用 marklayer_watch_annotations，并在收到反馈时进行处理。

工具

工具	描述
marklayer_connect_room	通过分享 URL 或纯 ID 连接到房间。
marklayer_room_info	页面 URL、视口宽度和时间戳。
marklayer_read_page	获取页面的标题、文本、链接和控件，并附带选择器。可让 Agent 评审尚无人添加标注的页面。
marklayer_list_annotations	列出标注，可按状态筛选。
marklayer_get_annotation	获取一条标注的完整详情和回复线程。
marklayer_watch_annotations	阻塞等待新标注到达，并返回一批标注。
marklayer_acknowledge	将状态设为处理中，并标记为由此 Agent 处理。
marklayer_resolve	将状态设为已解决，可附带摘要回复。
marklayer_dismiss	将状态设为已忽略，并附上人类可见的原因。
marklayer_reply	发布回复但不更改状态（例如提出澄清问题）。
marklayer_create_annotation	自行留下新评论，主动提供反馈而非回复。
marklayer_suggest_edit	对一段文本提出精确的文案或语法修改建议，以差异形式呈现，供人类接受。
marklayer_share_preview	在你创建的 URL 上开启新的评审房间并连接到该房间。使用与当前房间相同的 repo 和 branch（或 previous），即可将其设为下一个版本。
marklayer_set_next_steps	发布按顺序排列的检查清单，每个步骤都关联标注 ID。会替换之前的清单。
marklayer_complete_next_step	勾选完成某个步骤；评审者会实时看到更新。
marklayer_ask	在房间中发起一个包含 2-6 个选项的投票。每位评审者可投一票，并可重新投票。
marklayer_get_feedback	一次读取各状态的标注数量、未解决的标注、检查清单进度和投票统计。

选项

--room <url-or-id>   Connect at startup; otherwise call marklayer_connect_room.
--api-base <url>     Override worker URL (default https://marklayer.app).
--agent <name>       Identifier shown to humans (default "claude-code").

对应的环境变量：MARKLAYER_ROOM、MARKLAYER_API_BASE、MARKLAYER_AGENT。

故障排查

首次启动时出现“Connection closed”。 首次运行时，npx -y 会下载软件包，冷启动下载可能耗时过长，超过 MCP 客户端的启动超时时间。先预热一次缓存（npx -y marklayer-mcp --help）再重新连接，或者提前安装：npm i -g marklayer-mcp，并让客户端指向该二进制文件。

工具返回“room is not connected”。 WebSocket 已断开连接——房间由 Durable Object 保持开启，长时间空闲的 Agent 可能会断开连接。使用相同的 URL 调用 marklayer_connect_room 以重新连接。

以编程方式创建房间

此服务会使用现有的分享链接。若要通过代码创建一个或多个分享链接——例如，在让 Agent 连接之前，为一批 URL 中的每个页面预先创建一个房间——请直接向公共 HTTP API 发送 POST 请求：

curl -X POST https://marklayer.app/api/$ID \
  -H 'Content-Type: application/json' \
  -d '{"ops":[],"url":"https://example.com/page-1","width":1440,"expires_in":2592000}'
# Share link: https://marklayer.app/s/$ID

对于预览构建版本的评审房间，POST /api/$ID/preview 接受 { url, title, repo?, branch?, sha?, note?, questions?, previous? }，且绝不会覆盖已存在的 id。版本只能通过 previous 链接到你已有的房间：两个房间不会仅凭 repo 和 branch 建立关联，因为版本切换器会显示每个房间的相邻房间。marklayer_share_preview 会通过 stdio 调用此路由；通过 HTTP（/s/:id/mcp）调用时，它会在 Worker 中创建房间，与 URL 中的房间建立链式关联，并返回用于重新连接的 mcpUrl，因为该端点始终绑定到自己的房间。

$ID 由调用方提供（使用 nanoid / crypto.randomUUID()——它就是访问令牌）。无需身份验证，也无需 SDK。完整详情：https://marklayer.app/llms-full.txt