Yocoolab

@yocoolab/mcp-server

MCP（Model Context Protocol）服务，可将 Yocoolab 反馈讨论串和设计选区作为工具提供给 Claude Code 和其他兼容 MCP 的客户端。

安装后，你的 AI 编码助手可以：

• 列出并分类处理仓库中未解决的设计反馈讨论串
• 获取讨论串的丰富上下文（选区、截图、对话、涉及的文件）
• 回复设计师并将讨论串标记为已处理
• 创建 PR 以关闭反馈讨论串
• 检查 Yocoolab Chrome 扩展中的元素上下文和选区历史记录
• 阅读相关聊天消息、AI 对话和 Pendo 产品分析数据

推荐：托管版 Yocoolab MCP（无需安装）

大多数人现在都不需要此软件包。Yocoolab 在 https://app.yocoolab.com/mcp 托管了 MCP 服务。你的 Agent 首次使用时会在浏览器中登录 Yocoolab，因此无需粘贴令牌：

claude mcp add --transport http --scope user yocoolab https://app.yocoolab.com/mcp

然后在 Claude Code 中输入 /mcp，选择 yocoolab，并进行身份验证。Cursor、VS Code、Claude 应用和无头 Agent（在标头中使用 Agent 令牌）的设置说明见 app.yocoolab.com/connect。

**始终在线的 Agent：**如需让一台电脑自动处理工作区中每一条发送给 Agent 的消息（通过 Claude Code 运行），请在该电脑上运行：

curl -fsSL https://app.yocoolab.com/agent/install.sh | sh

要从此软件包切换到托管服务？请先移除旧配置（claude mcp remove yocoolab，重复运行直到找不到为止）。否则 Claude 可能会继续使用旧配置。

只有在需要在自己的电脑上运行的功能时才使用此软件包：用于从 Chrome 扩展实时获取选区的本地桥接服务（:9800）。

安装（本地软件包）

只需一条命令：

npx -y @yocoolab/mcp-server@3 setup

setup 向导会自动检测已安装的 AI Agent（Claude Code、Cursor、Cline、Roo Code、Windsurf），并为每个 Agent 写入正确的 MCP 配置。重启 Agent 后，yocoolab 服务便会出现，并提供所有工具。

为了兼容 v1.0.x 的安装说明，init 仍作为 setup 的别名保留。

如果你更愿意手动配置，等效的 ~/.mcp.json 如下：

{
  "mcpServers": {
    "yocoolab": {
      "command": "npx",
      "args": ["-y", "@yocoolab/mcp-server@3"],
      "env": {
        "YOCOOLAB_API_URL": "https://app.yocoolab.com",
        "YOCOOLAB_TOKEN": "<your-yocoolab-jwt>",
        "GITHUB_TOKEN": "<your-github-pat>",
        "YOCOOLAB_BRIDGE_PORT": "9800",
        "YOCOOLAB_BRIDGE_WORKSPACE": "/absolute/path/to/your/workspace"
      }
    }
  }
}

@3 版本固定可确保你使用 v3 主版本系列——你会自动收到错误修复和新功能，但未来带有不兼容变更的 v4 不会影响你的配置。v3.0.0 移除了活动监视器，并且不再向 ~/.claude/settings.json 写入 Claude Code 钩子；如果你要从 v2 升级，请参阅 CHANGELOG.md。

要求

• Node.js 20 或更高版本。 我们在 CI 中使用 Node 20 和 22 进行测试。我们支持当前处于Active LTS 或 Maintenance LTS状态的 Node.js 版本，并在版本终止支持前 30 天内停止支持。Node 18 已在 v2.0.0 中停止支持（于 2025 年 4 月终止支持）。
• Yocoolab 账号和 JWT 令牌——可在 Yocoolab Chrome 扩展的设置中获取，也可通过你的账号在 app.yocoolab.com 获取。
• GitHub 个人访问令牌，需具有 repo 范围，若要使用 PR 创建工具（create_pr_for_thread）。如果已安装并通过身份验证（gh auth login）的 GitHub CLI，系统会自动检测令牌。这种情况下无需设置 GITHUB_TOKEN 环境变量。否则，请在 github.com/settings/tokens/new?scopes=repo 创建令牌。

配置

环境变量	必填	默认值	说明
YOCOOLAB_TOKEN	否	—	你的 Yocoolab JWT（来自 Chrome 扩展）。未设置时，线程反馈工具将被禁用，但桥接 / 配套 / 选区工具仍可使用。
YOCOOLAB_API_URL	否	https://app.yocoolab.com	Yocoolab API 基础 URL
GITHUB_TOKEN	仅 PR 工具需要	—	具有 repo 范围的 GitHub PAT。自动检测——如果已安装并通过身份验证（gh auth token）的 gh CLI，则无需设置环境变量。系统会检测并安全忽略 <your GitHub PAT> 之类的占位值。
YOCOOLAB_BRIDGE_PORT	否	9800	用于连接 Chrome 扩展的本地 HTTP 桥接端口
YOCOOLAB_BRIDGE_WORKSPACE	否	process.cwd()	项目工作区的绝对路径，用于解析选区中的文件引用
YOCOOLAB_AGENT_NAME	否	Claude Code	Chrome 扩展 Agent 选择器中显示的名称
YOCOOLAB_PROJECT_PR_LINKS	否	1	设为 0 可恢复 2.5 之前的行为：mark_thread_addressed 不包含 PR / 预览链接字段，提示词仅提供 GitHub PR 指引
YOCOOLAB_AGENT_TYPE	否	claude-code	Agent 类型标识符（claude-code、roo、cline、cursor、windsurf 或 custom）

CLI

yocoolab-mcp           Run the MCP server (used by your agent via .mcp.json)
yocoolab-mcp setup     Interactive setup — auto-detects agents and writes their configs
yocoolab-mcp init      Alias for `setup` (backwards compatible with v1.0.x)
yocoolab-mcp --help    Show this help

mcp-server 命令是 yocoolab-mcp 的同义命令，两者均可使用。

工具

该服务提供多个类别的工具：

• 线程 — list_open_threads、get_thread_context、add_thread_message、mark_thread_addressed、create_pr_for_thread
  • 对于仅包含链接的项目（未连接 GitHub App），请使用你自己的 git / gh 创建 PR，然后调用 mark_thread_addressed，并传入 pr_url（如果有，也可传入 pr_branch、preview_url）。PR 字段会添加到线程中，预览链接会出现在评审消息里；get_thread_context 会输出项目的仓库链接，方便你确认它指向哪个仓库。create_pr_for_thread 仍适用于已连接 GitHub 的 owner/name 工作区。
• 选区 / 桥接 — get_latest_selection、get_selection_history、get_element_context、find_source_for_selection、ai_analyze_page
• 配套功能 — get_companion_messages、reply_to_companion
• AI — get_ai_conversations
• 部署 — get_deployment_preview
• Pendo（可选） — pendo_list_guides、pendo_page_analytics、pendo_feature_usage、pendo_track_event

服务启动后，你的 MCP 客户端会列出完整的工具说明和参数。

故障排除

yocoolab-mcp: command not found — 请确保你使用的是 v1.0.1 或更高版本。运行 npx -y @yocoolab/mcp-server@latest setup 以获取当前版本。

[yocoolab] Warning: YOCOOLAB_TOKEN not set — 未设置令牌时，线程反馈工具将被禁用，但 bridge / companion / selection 工具仍可正常使用。若要启用所有功能，请运行 yocoolab-mcp setup，使用你的 JWT（重新）生成配置。

安装后，Agent 中未显示工具 — 请完全重启 Agent（退出并重新打开）。MCP 服务会在启动时加载。

Port 9800 is already in use — 另一个 MCP 服务实例正在运行，或者其他应用占用了该端口。请在 .mcp.json 中将 YOCOOLAB_BRIDGE_PORT 设置为其他值（例如 9801）。

详细诊断日志 — 在环境变量块中设置 DEBUG=yocoolab:*。所有诊断输出都会发送到 stderr（因此不会干扰 stdout 上的 MCP stdio 协议）。

创建 PR 时提示“GitHub token not configured” — create_pr_for_thread 工具需要 GitHub 令牌。可通过以下两种方式解决：

1. 自动检测（最简单）： 安装 GitHub CLI，然后运行 gh auth login。服务会自动获取令牌。
2. 手动设置： 创建一个具有 repo 范围的个人访问令牌，并将 GITHUB_TOKEN: "ghp_..." 添加到 MCP 配置的 env 块中。 如果你的配置包含 <your GitHub PAT> 之类的占位值，服务会检测到该值并显示有用的提示，而不会因 401 错误而崩溃。

支持

• 文档： 本 README，以及 MCP 客户端中显示的内联工具说明
• Bug 报告： github.com/Yocoolab/mcp-server/issues（请使用 Bug 模板）
• 安全问题： 请参阅 SECURITY.md — 请勿公开提交问题
• 其他问题： [email protected]

开发

git clone https://github.com/Yocoolab/mcp-server.git
cd mcp-server
npm install
npm run build       # compile TypeScript to dist/
npm test            # run the vitest suite
npm run dev         # tsc --watch

完整的贡献工作流请参阅 CONTRIBUTING.md。

安全与供应链

• 使用 npm provenance 发布 — 每个已发布版本均由 GitHub Actions OIDC 进行加密签名，可追溯到确切的提交和工作流运行记录。
• 每次发布都会附带一份 CycloneDX SBOM，并将其附加到 GitHub Release。
• 我们会在 CI 中对每个 PR 运行 npm audit signatures 和 CodeQL 静态分析。
• 漏洞报告请参阅 SECURITY.md。

许可证

Apache 2.0 — © 2026 Yocoolab