使用说明

产品大脑

产品知识的唯一真实来源——术语表、业务规则、紧张关系、决策、标签和关系——可作为MCP服务器访问克劳德桌面, 光标，以及任何兼容MCP的AI助手。

ProductBrain将您的AI助手与团队的知识库连接起来。在不离开编辑的情况下，提问、捕捉决策并构建一个生动的知识图谱。

快速入门（云）

选项A：引导式设置（推荐）

npx @productbrain/mcp setup

这将打开SynergyOS→ 设置→ API密钥，提示您粘贴密钥，并为Cursor或Claude Desktop编写配置。

选项B：手动配置

1.获取API密钥

首选 SynergyOS→ 设置→ API密钥 然后单击 生成密钥.复制 pb_sk_... 钥匙。

2.配置您的AI助手

克劳德桌面 --编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
      }
    }
  }
}

光标 --编辑 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here"
      }
    }
  }
}

3.重新启动助手并验证

问：

“使用健康工具检查ProductBrain连接”

您应该看到您的工作区ID、集合计数和延迟。

自托管设置

如果您正在运行自己的Converx部署，请使用三个变量配置：

{
  "mcpServers": {
    "productbrain": {
      "command": "npx",
      "args": ["-y", "@productbrain/mcp"],
      "env": {
        "CONVEX_SITE_URL": "https://your-deployment.convex.site",
        "MCP_API_KEY": "your-shared-api-key",
        "WORKSPACE_SLUG": "your-workspace-slug"
      }
    }
  }
}

变量	在哪里可以找到它
`CONVEX_SITE_URL`	凸形仪表板→ 设置→ URL（使用 `.convex.site`，不 `.convex.cloud`)
`MCP_API_KEY`	必须匹配 `MCP_API_KEY` Convex部署中的env-var
`WORKSPACE_SLUG`	SynergyOS URL中的工作区图标

开发vs生产

集 PRODUCTBRAIN_URL 在环境之间切换：

{
  "env": {
    "PRODUCTBRAIN_API_KEY": "pb_sk_your_key_here",
    "PRODUCTBRAIN_URL": "http://localhost:3210"
  }
}

省略 PRODUCTBRAIN_URL 默认为生产。

你能做什么

搜索和探索

“在术语表中搜索‘张力’”
“列出治理域中的所有业务规则”
“‘供应商’的规范定义是什么？”

获取知识

“捕捉紧张情绪：我们的MCP条目创建需要太多步骤”
“起草选择Converx而非Supabase的决定记录”
“创建关于API密钥轮换的业务规则”

浏览知识图谱

“收集FEAT-001的完整背景”
“哪些条目与GT-019有关？”
“为这种新的紧张局势提供链接建议”

检查质量

“对TEN图形数据库进行质量检查”
“审查AI和MCP集成领域的业务规则”
“根据代码库验证术语表”

工具（20+）

工具	它做什么
`health`	验证连接并获取工作区统计信息
`kb-search`	在所有知识条目中进行全文搜索
`list-collections`	浏览所有集合架构
`list-entries`	使用可选筛选器浏览条目
`get-entry`	包含数据、标签、关系和历史的完整记录
`smart-capture`	一次呼叫条目创建，具有自动链接和质量评分功能
`create-entry`	使用完整的字段控制进行创建
`update-entry`	部分更新（与现有数据合并）
`gather-context`	围绕条目的多跳图遍历
`suggest-links`	发现潜在的联系
`relate-entries`	在条目之间创建类型化关系
`find-related`	列出条目的直接关系
`quality-check`	根据特定收藏标准对条目进行评分
`review-rules`	域的表面业务规则
`verify`	对照实际代码库检查知识条目
`list-labels`	浏览工作区标签
`manage-labels`	创建、更新或删除标签
`label-entry`	在条目中应用或删除标签
`quick-capture`	最少的仪式入口创建
`mcp-audit`	带有呼叫统计信息的会话审核日志

资源

URI	内容
`productbrain://orientation`	系统图：架构、数据模型、规则、分析
`productbrain://terminology`	术语表+标准摘要
`productbrain://collections`	所有具有字段定义的集合架构
`productbrain://{slug}/entries`	给定集合中的所有条目
`productbrain://labels`	带层次结构的工作区标签

提示

提示	目的
`review-against-rules`	根据业务规则进行结构化合规审查
`name-check`	对照术语表检查变量/字段名称
`draft-decision-record`	根据上下文起草决定记录
`draft-rule-from-context`	根据观察起草业务规则

安全

您的数据始终属于您。 MCP服务器仅连接到经过身份验证的Converx部署。数据不会与第三方共享。
API密钥处理。 云密钥(pb_sk_...)在存储之前进行SHA-256散列。仅保留前缀以供显示。密钥作为承载令牌通过HTTPS发送。
工作空间范围。 每个API键都绑定到一个工作区。无法跨工作区访问。

故障排除

“缺少API密钥”或“无效的API密钥”

你的 PRODUCTBRAIN_API_KEY 缺失或不正确。从SynergyOS设置生成新密钥→ API密钥。

“CONVEX_SITE_URL环境变量是必需的”

您正在使用自托管模式，但缺少 env 块。确保所有三个变量都已设置。

“找不到工作区”

对于自托管：请检查您的 WORKSPACE_SLUG.对于云：您的API密钥可能已被吊销。

“MCP呼叫网络错误”

后端无法访问。如果使用 PRODUCTBRAIN_URL，验证URL是否正确以及服务器是否正在运行。

服务器未出现在Claude桌面/光标中

编辑配置文件后重新启动应用程序。在光标中，检查MCP面板（Cmd+Shift+P→ “MCP:显示面板”）显示启动错误。

启用调试日志记录

集 MCP_DEBUG=1 在您的配置中 env 阻止查看stderr中的审核日志。

发展

# Clone and install
git clone https://github.com/synergyai-os/productbrain.git
cd productbrain
# Or install: npm install @productbrain/mcp
npm install

# Copy env template and fill in your values
cp .env.mcp.example .env.mcp

# Run in dev mode (TypeScript, hot reload)
npm run dev

# Build for production
npm run build

# Run the built version
npm start

# Typecheck
npm run typecheck

# Publish beta
npm run publish:beta
# (Maintainers: set SYNERGYOS_POSTHOG_KEY=phc_... for usage tracking)

许可证

麻省理工学院