内容
# @yocoolab/mcp-server
[](https://www.npmjs.com/package/@yocoolab/mcp-server)
[](https://www.npmjs.com/package/@yocoolab/mcp-server)
[](https://github.com/Yocoolab/mcp-server/actions/workflows/ci.yml)
[](./LICENSE)
[](./package.json)
[](./package.json)
[](https://www.bestpractices.dev/)
MCP（模型上下文协议）服务器，暴露 [Yocoolab](https://yocoolab.com) 的反馈线程、设计选择和活动事件，作为 Claude Code 和其他 MCP 兼容客户端的工具。
安装后，您的 AI 编程助手可以：
- 列出和分类存储库中的开放设计反馈线程
- 拉取线程的丰富上下文（选择、截图、对话、 touched 文件）
- 回复设计师并将线程标记为已解决
- 打开关闭反馈线程的 PR
- 从 Yocoolab Chrome 扩展程序检查元素上下文和选择历史
- 读取活动摘要、AI 对话和 Pendo 产品分析
## 安装
一条命令：
```bash
npx -y @yocoolab/mcp-server@2 setup
```
`setup` 向导会自动检测您已安装的 AI 代理（Claude Code、Cursor、Cline、Roo Code、Windsurf），并为每个代理编写正确的 MCP 配置。重启您的代理，`yocoolab` 服务器就会出现，所有工具都可用。
> `init` 被保留为 `setup` 的别名，以兼容 v1.0.x 的安装说明。
如果您更喜欢手动配置，等效的 `~/.mcp.json` 看起来像这样：
```json
{
"mcpServers": {
"yocoolab": {
"command": "npx",
"args": ["-y", "@yocoolab/mcp-server@2"],
"env": {
"YOCOOLAB_API_URL": "https://app.yocoolab.com",
"YOCOOLAB_TOKEN": "<您的-yocoolab-jwt>",
"GITHUB_TOKEN": "<您的-github-pat>",
"YOCOOLAB_BRIDGE_PORT": "9800",
"YOCOOLAB_BRIDGE_WORKSPACE": "/绝对路径/到/您的/工作空间"
}
}
}
}
```
`@2` 版本固定使您保持在 v2 主线版本上 — 您将自动接收错误修复和新功能，但未来具有破坏性更改的 v3 版本不会破坏您的设置。（如果您需要 Node 18 支持，请固定到 `@1` — v1.x 将在 v2.0 之后 90 天内接收安全补丁。）
## 要求
- **Node.js 20 或更新版本。** 我们在 Node 20 和 22 上进行测试。 我们支持当前处于 [Active LTS 或 Maintenance LTS](https://nodejs.org/en/about/previous-releases) 状态的 Node.js 版本，并在其 EOL 后 30 天内删除版本。 Node 18 在 v2.0.0 中被删除（EOL 2025 年 4 月）。
- **Yocoolab 账户和 JWT token** — 从 Yocoolab Chrome 扩展程序设置或您的 [app.yocoolab.com](https://app.yocoolab.com) 账户中获取。
- **具有 `repo` 范围的 GitHub 个人访问 token**，如果您想使用 PR 创建工具 (`create_pr_for_thread`)。如果您已安装并认证了 [GitHub CLI](https://cli.github.com/)，则会自动检测该 token。 在这种情况下，不需要 `GITHUB_TOKEN` 环境变量。 否则，请在 [github.com/settings/tokens/new?scopes=repo](https://github.com/settings/tokens/new?scopes=repo&description=Yocoolab%20MCP) 处创建一个，并具有 `repo` 范围。
## 配置
| 环境变量 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `YOCOOLAB_TOKEN` | 否 | — | 您的 Yocoolab JWT（来自 Chrome 扩展程序）。未设置时，线程反馈工具将被禁用，但桥 / 同伴 / 活动工具仍可正常工作。 |
| `YOCOOLAB_API_URL` | 否 | `https://app.yocoolab.com` | Yocoolab API 基本 URL |
| `GITHUB_TOKEN` | 仅限 PR 工具 | — | 具有 `repo` 范围的 GitHub PAT。**自动检测** — 如果已安装并认证了 `gh` CLI，则不需要环境变量。 像 `<您的 GitHub PAT>` 这样的占位符值将被检测并安全地忽略。 |
| `YOCOOLAB_BRIDGE_PORT` | 否 | `9800` | 用于与 Chrome 扩展程序通信的 HTTP 桥的本地端口 |
| `YOCOOLAB_BRIDGE_WORKSPACE` | 否 | `process.cwd()` | 您的项目工作空间的绝对路径，用于解析选择中的文件引用 |
| `YOCOOLAB_AGENT_NAME` | 否 | `Claude Code` | Chrome 扩展程序的代理选择器中显示的名称 |
| `YOCOOLAB_AGENT_TYPE` | 否 | `claude-code` | 代理类型标识符 (`claude-code`, `roo`, `cline`, `cursor`, `windsurf`, 或 `custom`) |
## 命令行界面
```
yocoolab-mcp 运行 MCP 服务器（由您的代理通过 .mcp.json 使用）
yocoolab-mcp setup 交互式设置 — 自动检测代理并编写其配置
yocoolab-mcp init `setup` 的别名（与 v1.0.x 向后兼容）
yocoolab-mcp --help 显示此帮助
```
`mcp-server` 命令是 `yocoolab-mcp` 的同义词。两者均可使用。
## 工具
服务器在多个类别中暴露工具：
- **线程** — `list_open_threads`, `get_thread_context`, `add_thread_message`, `mark_thread_addressed`, `create_pr_for_thread`
- **选择 / 桥** — `get_latest_selection`, `get_selection_history`, `get_element_context`, `find_source_for_selection`, `ai_analyze_page`
- **活动** — `get_recent_events`, `get_activity_summary`, `get_files_touched`, `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`** — 没有 token，线程反馈工具将被禁用，但桥 / 同伴 / 活动工具仍可正常工作。要启用所有功能，请运行 `yocoolab-mcp setup` 以（重新）生成包含您的 JWT 的配置。
**安装后，工具在您的代理中不显示** — 完全重启您的代理（退出并重新打开）。MCP 服务器在启动时加载。
**`Port 9800 is already in use`** — 另一个 MCP 服务器实例正在运行，或者另一个应用程序占用了该端口。 在您的 `.mcp.json` 中将 `YOCOOLAB_BRIDGE_PORT` 设置为不同的值（例如 `9801`）。
**详细诊断日志** — 在您的环境块中设置 `DEBUG=yocoolab:*`。所有诊断输出都输出到 stderr（因此它不会干扰 MCP stdio 协议的 stdout）。
**PR 创建显示“GitHub token not configured”** — `create_pr_for_thread` 工具需要 GitHub token。两种解决方法：
1. **自动检测（最简单）：** 安装 [GitHub CLI](https://cli.github.com/) 并运行 `gh auth login`。 服务器会自动获取 token。
2. **手动：** 创建一个具有 `repo` 范围的 [个人访问 token](https://github.com/settings/tokens/new?scopes=repo&description=Yocoolab%20MCP)，并将 `GITHUB_TOKEN: "ghp_..."` 添加到您的 MCP 配置的 `env` 块中。
如果您的配置中有像 `<您的 GitHub PAT>` 这样的占位符值，服务器会检测到它并显示一条有用的消息，而不是使用 401 错误崩溃。
## 支持
- **文档：** 本 README，以及在您的 MCP 客户端中可见的内联工具描述
- **错误报告：** [github.com/Yocoolab/mcp-server/issues](https://github.com/Yocoolab/mcp-server/issues)（使用错误模板）
- **安全问题：** 参见 [SECURITY.md](./SECURITY.md) — **不要** 公开问题
- **其他问题：** support@yocoolab.com
## 开发
```bash
git clone https://github.com/Yocoolab/mcp-server.git
cd mcp-server
npm install
npm run build # 编译 TypeScript 到 dist/
npm test # 运行 vitest 套件
npm run dev # tsc --watch
```
参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 以获取完整的贡献者工作流程。
## 安全与供应链
- 使用 [npm provenance](https://docs.npmjs.com/generating-provenance-statements) 发布 — 每个发布的版本都经过 GitHub Actions OIDC 的加密签名，可追溯到确切的提交和工作流运行。
- 每个版本都附带一个 CycloneDX SBOM，附加到 GitHub Release 中。
- 我们在每个 PR 上运行 `npm audit signatures` 和 CodeQL 静态分析。
- 参见 [SECURITY.md](./SECURITY.md) 以报告漏洞。
## 许可证
[Apache 2.0](./LICENSE) — 2026 Yocoolab 版
