ProductBrain

ProductBrain MCP 服务

通过 MCP 客户端——Claude Desktop、Cursor、Claude Code——管理 ProductBrain 方案，使用搜索、读取、修改、方法论工作流和实时视图工具。

设计——刻意保持轻量

此服务是 ProductBrain 版本化 v1 REST API 的轻量传输层。每个工具都会调用一个现有的 /api/v1 端点。REST 契约始终是权威标准：

• 当 MCP 规范频繁变动时，它仍然保持稳定——你所依赖的是冻结的 v1 API 契约，而不是协议。
• 你可以随时改用原始 HTTP 或使用自己的 LLM；MCP 只是一个入口，并非唯一入口。
• 响应会携带 API 返回的同一份带内 _meta 指导信息，让你的 Agent 能够自行纠正。

安装

// Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain-com/mcp"],
      "env": {
        "PRODUCTBRAIN_API_KEY": "pb_your_key",
        "PRODUCTBRAIN_PROJECT_ID": "your-project-id"
      }
    }
  }
}

# Claude Code
claude mcp add productbrain \
  -e PRODUCTBRAIN_API_KEY=pb_your_key \
  -e PRODUCTBRAIN_PROJECT_ID=your-project-id \
  -- npx -y @productbrain-com/mcp

Cursor 和其他客户端：添加一个包含相同 command/args/env 的 mcpServers 条目。

配置（环境变量）

变量	必填	默认值
PRODUCTBRAIN_API_KEY	是	—（从应用的 API Key 弹窗获取你的 pb_ 密钥）
PRODUCTBRAIN_PROJECT_ID	否	—（工具也接受 projectId 参数）
PRODUCTBRAIN_API_URL	否	https://productbrain.com/api/v1

工具

每个面向 Agent 的 /api/v1 端点都有一个工具。一个工具对应一个端点，并原样传回相同的 _meta 指导信息。

计划

工具	对应端点	用途
search	GET /search	语义搜索——任何查询都先用它
list_nodes	GET /nodes	批量读取，可选按类型/迭代筛选
get_tree	GET /tree	在上下文中查看节点（祖先/同级节点/子节点/子树）
mutate	POST /mutate	创建/更新/删除节点和阶段；传入 idempotencyKey，确保重试安全
list_iterations	GET /iterations	阶段；使用 current:true 获取当前阶段
run_workflow	POST /workflow	Story-Mapping 方法（add / task-curate / phase-assign）
export_okf	GET /export-okf	以可移植的 OKF 文件包形式导出计划
get_changelog	GET /changelog	计划历史：每次添加/更新/删除/恢复操作，并注明是由应用还是指定的 Agent 执行

视图

工具	对应端点	用途
set_view / read_view	POST /view-command, GET /view-state	控制/读取实时画布

项目

工具	对应端点	用途
list_projects	GET /projects	你拥有或参与的项目；使用 includeArchived 获取其余项目
create_project	POST /mutate {addProject}	初始化一个 Brain——并创建系统预设的 “Later” 阶段。请传入明确的 id：addProject 会在 mutate 读取 Idempotency-Key 之前运行，因此重试不安全
rename_project	POST /mutate {renameProject}	更改显示名称；ID 不可更改
archive_project	PATCH /projects	隐藏/取消隐藏项目，不会删除（可撤销）

Webhooks

工具	对应端点	用途
list_webhooks	GET /webhooks	查看已注册的 Hook 及其 lastStatus——发现故障接收端
create_webhook	POST /webhooks	注册 Hook；签名密钥仅返回一次
update_webhook	PATCH /webhooks	原地更改 url/events，或设置 rotateSecret:true。优先使用此方式，而非删除后重建
delete_webhook	DELETE /webhooks	移除注册项

分享链接

工具	对应端点	用途
create_share_link	POST /share	创建公开只读链接；通过 expiresInDays 设置 TTL
list_share_links	GET /share	审核所有已创建的令牌，并查看其 active 标记
revoke_share_link	DELETE /share	作废泄露或过期的链接

成员和预算

工具	对应端点	用途
list_members	GET /members	查看项目中的成员和 Agent 席位
add_agent_seat	POST /members	创建 Agent 席位；pb_ 密钥仅返回一次（Team 层级）
invite_contributor	POST /members	邀请无需密码的访客，并限定其可访问的项目（Team 层级）
revoke_member	DELETE /members	移除席位；Agent 的最后一个成员关系移除后，其密钥也会失效
tier_status	GET /tier-status	查看你的层级、API 访问权限、信用额度余额和限制——大规模运行前请先检查
submit_feedback	POST /feedback	告诉 PB 团队需要改进的地方：功能请求、使用障碍、Bug、备注

完整 API 参考文档：https://productbrain.com/docs/llm-guide.md。

源码、许可证、注册表

• 源码：https://github.com/moxzas/productbrain-mcp（MIT）。欢迎在此提交问题和拉取请求。
• npm：@productbrain-com/mcp。每次发布均基于仓库中相同版本号的标签。
• MCP 注册表名称：io.github.moxzas/productbrain（本仓库中的 server.json 是注册表清单）。
• 服务会发送 User-Agent: productbrain-mcp/<version>，因此你可以在自己的日志中区分 MCP 流量和原始 REST 调用。

验证效果

仓库中有两个无头脚本（src/spike-proof.ts、src/parity-proof.ts；不会随 npm 包发布），两者都会针对真实部署运行。请在自己的账号中使用一个临时项目：

PRODUCTBRAIN_API_KEY=pb_your_key \
PRODUCTBRAIN_PROJECT_ID=your-sandbox-project \
npm run spike     # transport + auth + one read + one write

PRODUCTBRAIN_API_KEY=pb_your_key \
npm run parity    # every non-plan tool once, on a throwaway project

parity 会创建自己的临时项目，并在运行结束后清理（最后会将其归档——没有删除项目的端点）。

Team 层级的工具（add_agent_seat、invite_contributor）使用 Builder 密钥时会返回 403 team_tier_required，这也算通过——但有一点值得注意：这能证明 shim 调用了正确的路由，并原样传递了错误及其 _meta 提示；但不能验证请求正文，因为层级门禁会在读取正文之前运行。使用 Team 层级密钥运行 parity，即可正确检查这两个工具。