Skyelight

@skyelight/mcp

npm · 源代码 · 文档

一个 MCP 服务，让编码 Agent 读取用户在运行中的应用上留下的反馈——包括讨论串、页面，以及他们指向的元素——并在工作完成后报告处理结果。

完整指南：skyelight.ai/docs/mcp。本地服务背后的 REST API 文档见 skyelight.ai/docs/api。

有两种连接方式，两种方式都提供相同的 18 个工具：

• 远程连接，使用 OAuth —— 默认方式。你的 Agent 通过 HTTP 与 Skyelight 通信，你只需在浏览器中登录一次。无需粘贴任何内容，也不会在磁盘上存储密钥。
• 本地连接，使用令牌 —— 此软件包会在你的 计算机上作为 stdio 服务运行，并携带个人令牌。适用于无法通过浏览器登录的客户端或计算机。

所有方案都包含全部工具，Free 方案也不例外，适用于所有者、管理员和协作者。Free 方案每月为你的 Agent 提供 25 个 Agent 讨论串；Pro 及以上方案不设限制。审阅者可以在 Web 应用中阅读和评论，但无法使用 Agent 工具。

简便方式

npx @skyelight/mcp init

查找你的编码 Agent，为其注册 Skyelight 远程服务，并通过 OAuth 完成登录——Agent 首次连接时会打开浏览器，你可在浏览器中批准。它会显示将要进行的更改并等待确认；阅读后可使用 --yes 跳过确认。

它支持 Claude Code、Cursor、Grok、Codex 和 Windsurf。安装了多个客户端时，它会询问你选择哪一个；使用 --client cursor 或 --client all 可预先指定。运行 npx @skyelight/mcp remove 可移除该配置。通过 SKYELIGHT_URL=https://… 指定其他部署；部署会通过 /mcp/install-config 告知安装程序其 MCP URL 和 OAuth 客户端，因此此软件包不包含特定环境的常量。

Skyelight Web 应用的账户设置 → Coding Agents 中也提供相同的设置方式，并针对每个客户端提供配置片段。

作为 Claude Code 插件使用

/plugin marketplace add plastrlab/skyelight-mcp
/plugin install skyelight@skyelight

此插件将 Claude Code 连接到 Skyelight 远程服务（登录方式同上，为 OAuth），并添加一个用于处理反馈的技能，以及两个命令：/skyelight:whats-new 和 /skyelight:fix-feedback。此仓库中的插件文件位于 .claude-plugin/marketplace.json 和 plugin/。

使用令牌

获取个人访问令牌。 在 Skyelight Web 应用中，前往账户设置 → API Keys → 创建一个令牌。该令牌只显示一次，属于创建它时所在的组织，也可以设置过期时间。

然后将服务添加到客户端：

{
  "mcpServers": {
    "skyelight": {
      "command": "npx",
      "args": ["-y", "@skyelight/mcp"],
      "env": {
        "SKYELIGHT_API_URL": "https://app.skyelight.ai",
        "SKYELIGHT_API_TOKEN": "sky_..."
      }
    }
  }
}

Claude Code 用户可以跳过配置文件：

claude mcp add skyelight \
  --env SKYELIGHT_API_URL=https://app.skyelight.ai \
  --env SKYELIGHT_API_TOKEN=sky_... \
  -- npx -y @skyelight/mcp

SKYELIGHT_API_URL 为 https://app.skyelight.ai，与 Coding Agents 页面上的 MCP URL（https://app.skyelight.ai/mcp）使用相同的主机，但不包含 /mcp。部署的 .convex.site 主机也可以使用。

凭据

按以下顺序检查，因此现有设置仍可正常使用：

1. 环境中的 SKYELIGHT_API_TOKEN / SKYELIGHT_API_URL
2. 工作目录中的 .env.local，然后是 .env
3. ~/.skyelight/credentials — {"apiUrl": "...", "token": "sky_..."}

将仓库绑定到项目

使用本地服务时，如果你可以访问多个项目，可在仓库根目录下添加 .skyelight.json：

{ "projectId": "j57abc...", "projectName": "Checkout rebuild" }

随后，工具会默认使用该项目，无需任何人传入 ID。若没有该文件（以及始终使用远程服务时），list_items 会要求指定项目，Agent 会先调用 list_projects，而不是自行猜测。

工具

工具	用途
list_workspaces	此凭据可以访问哪些工作区，以及你的身份。
list_projects	这些工作区中的项目，以及其他工具所需的 ID。
list_items	当前有哪些待处理事项。可按页面、类型、状态、受派人和交接情况筛选。
search_items	查找讨论串中提及特定文本的事项，包括回复。
get_item	处理某个事项所需的所有信息：讨论串、页面、锚点、代码和图片。
post_update	在收到反馈的讨论串中汇报进展。
create_item	提出新事项，例如审查发现或你注意到的问题。
set_status	将事项状态改为待处理、延期或已解决。
list_members	查看工作区成员，以便指定受派人或提及某人。
assign	将事项交给某人处理，或取消指派。
whats_new	查看自上次查看以来的变更，依据你自己的书签。
project_review	查看项目的最终情况，用于撰写总结或交接文档。
decision_log	查看团队在讨论串中作出的决定及引用内容，以及当前规则。
save_rule	将达成一致的规则保存在项目上下文中（所有者和管理员）。
find_by_source	编辑文件或组件前查看相关反馈，或查找问题热点。
find_similar	创建新事项前检查是否已有类似报告。
merge_items	将重复事项合并为一个。
publish_review_link	分享内容以供审查：由 Skyelight 托管的代码，或已部署应用的地址。

会更改内容的工具。 list_workspaces、list_projects、 list_items、search_items、get_item、list_members、project_review、 find_by_source、find_similar 和 decision_log 只会读取数据。post_update、 create_item、set_status、assign、save_rule、merge_items、 publish_review_link 和 whats_new（它会移动你的“上次查看”书签）会进行更改。每个工具都带有 MCP 注解，说明其类型；merge_items 标记为破坏性操作，因此你的客户端可以在执行写入操作前询问确认。

发布内容以供审查。 publish_review_link 接受以下两种内容之一：

• code：一个 HTML 页面，或一个带有 export default 的 React 组件（Claude 原型、v0 代码片段）。Skyelight 会将其托管在 skyelight.page 上的专属链接中，并附上审查徽章；可发布到你指定的项目或新项目。再次发布会在同一链接下创建新版本。
• url：已部署的应用，例如 *.lovable.app 或 *.vercel.app 上的 Lovable、v0 或 Bolt 项目。该地址会添加到项目的 Review Links 中，返回结果会包含一个供应用 <head> 使用的脚本标签，以及可供分享的审查链接（即附带 ?skyelight=1 的地址）。

如果代码导入了应用的其他部分，则不会托管；返回结果会提示你改为提供应用的 url。它也会响应 publish_prototype，这是 0.7.0 之前的名称。

list_items 会先提供摘要，包括总数以及按类型和页面分类的明细，让 Agent 在提取具体事项前了解工作概况。列表行是简要信息；讨论串和锚点位于 get_item 中。 “分配给我的内容。” list_workspaces 会返回你自己的用户 ID，而 list_items 接受 assignee: "me"，因此，任何人最常向 Agent 提出的普通问题， 都不需要手动查找 ID。

“我被要求修复什么。” 用户可以在应用中将一个线程交给 Agent 处理 （交接：调查、规划或修复）。list_items 接受 task，值可以是其中之一， 也可以是 "none"，每一行都会标明交接内容。使用 assignee: "me" 时， 你看到的就是自己的待修复队列。

合并的重复项不会重复出现。 有人在 Web 应用中合并了同一问题的五份报告后， 这些重复项会从列表中消失，被合并到的条目会显示 5 reports。如果列表显示 全部五份报告，看起来就像有五个 Bug。

Agent 看到的内容

Alpha: 21 items total — 15 open, 3 deferred, 3 resolved, 19 unassigned.
By type: bug (7), idea (4), feedback (10).
Busiest pages: /checkout (8), /settings (4).

2 matches:
- The pay button does nothing on the second click
  bug · open · /checkout · unassigned · 2 replies · 5 reports — id i1

特意采用散文形式，而不是 JSON。返回裸数组的工具会让模型照着数组念出来； 这个工具则会引导它进行总结。

如果 Skyelight 的分类器为某一行撰写了摘要，该行就会显示这句摘要，而不是某人 输入内容的前 140 个字符——四段被截断的文字，并不适合拿来做选择。

一次调用会读取项目中最近的 2,000 个条目。超过这个范围时，结果会用文字说明， 而不会把部分内容呈现为全部内容。

图片

get_item 会返回留下标记时拍摄的屏幕截图，以及用户附加到线程的任何图片， 并以图片内容块的形式呈现——模型可以实际查看，而不是无法打开的链接。

Screenshot of the page when this was pinned: attached below.
2 images attached to this thread: also below.

每次调用最多返回四张。太大而无法内嵌的图片会连同链接和原因一起返回，因此图片 不会悄无声息地消失。

其他人已经做了什么

get_item 还会标明线程被交接处理的 Linear 问题，以及受委派的对象，因此 Agent 不会重复处理由 Linear 托管的 Agent 正在完成的工作。反应会按表情符号计数—— 有一条评论和九个赞的线程，不只是有一条评论。

代码在哪里

如果应用是用 @skyelight/build 构建的，get_item 会以一行能改变 Agent 下一步行动的信息结尾：

Written by components/Card.tsx, line 88, in build a1b2c3d on branch feat/checkout.

文件信息省去了 grep 操作。提交和分支信息能帮助 Agent 区分“仍然有问题”和 “已经修复，这个标记已过时”——在预览部署中，还能确认所需代码实际位于哪个分支。

谁来署名写入内容

每次写入都属于某个人。你的登录信息或令牌携带你的访问权限，因此 Agent 发布的 回复会署上你的名字。在远程服务上，回复来自哪个编辑器，会作为标记显示在时间戳旁， 而不会显示为作者。

没有服务账户模式，工作区 API 密钥（sk_live_...）也已无法使用。API 接受两种 凭据，但两者都属于你：OAuth 登录和个人令牌（sky_...）。

权限

服务端不执行权限检查，API 会执行。Agent 在该工作区中能做的事与你的账户权限相同， 不会更多：

• Agent 工具适用于所有套餐，包括 Free，但仅限所有者、管理员和协作者使用。 审阅者会收到拒绝访问及原因——工作区会显示并标记出来，而不会被隐藏，因此你会 知道是哪道权限门槛挡住了你，而不是被告知它不存在。
• Free 套餐下，你的 Agent 每月可处理 25 个 Agent 线程。两类操作会计数： 每段对话仅在首次调用任意工具时计一次，列出内容也包括在内；每个线程在当月首次 被 get_item、post_update、set_status、assign 或 merge_items 操作时也计一次。 因此，先问“我有哪些反馈？”，再说“修复那个”，会计为 2 次。已计数的额度不会退还。 list_workspaces 会说明剩余次数；达到上限后，任何新操作都会被拒绝，并告知重置日期。 Free 套餐可托管一个原型。
• 将已部署应用的地址添加到 Review Links 仅限所有者和管理员操作。
• 所有者、管理员和协作者可以读取、回复、创建条目，并更改任意线程的状态。
• 令牌只能访问创建该令牌的组织中的工作区。