brainCloud MCP Helper

本地服务

github.com/getbraincloud开发工具116 周前更新

代码仓库

关于 brainCloud MCP Helper

brainCloud MCP Helper 是本地 stdio MCP 服务，为 AI 客户端提供文件系统访问，以同步 brainCloud 云代码。它使用托管版 braincloud-mcp 发放的短期票据，并支持双向同步和三方合并。

主要功能

01只读分类同步状态
02拉取或推送无冲突变更
03双向同步与三方合并
04用 Git 风格标记记录合并冲突

适用场景

01应用前检查云代码变更
02同步本地脚本与 brainCloud
03处理云脚本的并发编辑

MCP 相关

本地 stdio MCP 服务提供 status、pull、push 和 sync 工具。它需配合托管版 `braincloud-mcp` 使用，由后者发放调用 Builder API 所需的短期票据。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "com-braincloudservers-braincloud-mcp-helper": {
      "command": "npx",
      "args": [
        "-y",
        "@braincloud/mcp-helper"
      ]
    }
  }
}

启动命令npx -y @braincloud/mcp-helper

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@braincloud/mcp-helper6.0.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
branch	string	否	要同步的 Git 分支。默认为 .git/HEAD 中的当前分支；如果文件夹不是 Git 仓库，则使用保留的 no-branch 键，之后可将其迁移到真实分支。
ticket	object	是	由托管 MCP getSyncTicket 工具提供的短期票据。
ticket.appName	string	是	目标应用名称（来自 getSyncTicket）。
ticket.baseUrl	string	是	应用专属的 Builder 基础 URL（来自 getSyncTicket）。
ticket.expiresAt	string	否	票据过期时间，采用 ISO-8601 格式（来自 getSyncTicket）。
ticket.authorization	string	是	Authorization 标头值（来自 getSyncTicket）。
rootDir	string	否	本地 cloud-code 同步文件夹的绝对路径（.ccjs 树和 .bcsync）。可选：如果省略，辅助程序会在其工作目录及其上级目录中查找最近的 .bcsync 文件夹。对于全新文件夹，请在首次同步前显式传入此值。
confirmAppName	string	否	安全确认。仅当此前已同步的文件夹没有已提交的 .bcsync 应用映射时才需要（例如由较旧的辅助程序同步）：将其设为票据的 appName，以确认你打算将此文件夹与该应用同步。.bcsync 存在后便不再需要。
adoptNoGitBranch	boolean	否	确认将无 Git 同步状态和应用映射迁移到当前 Git 分支（移除 no-branch 条目）。当文件夹首次在没有 Git 的情况下完成同步、如今位于真实分支上时，需要确认一次；工具会要求确认，以免之前的状态成为孤立状态。

详细介绍

@braincloud/mcp-helper

一个本地 stdio MCP 服务，为 AI 客户端（Claude Code、Cursor、Codex，……）提供用于 brainCloud cloud-code 同步的文件系统访问权限。

它特意设计为零信任：它不会自行向 brainCloud 进行身份验证，也不会存储凭据。每次 Builder API 调用都由 AI 从托管的 braincloud-mcp 的 getSyncTicket 工具获取并传入的短期、限定应用范围的票据驱动。批量脚本数据直接从 helper 流向 Builder API，不会经过 AI 的上下文。

格式和同步逻辑来自 @braincloud/cloudsync-core；此包则是围绕它构建的 Node 文件系统 + MCP 外壳。

工具

工具	票据	功能
`status`	read	试运行：对每个脚本进行分类（同步 / 拉取 / 推送 / 冲突 / 新增 / 删除）。不进行写入。
`pull`	read	对不存在冲突的更改应用 brainCloud → 本地同步。仅在设置 `allowDeletes` 时删除本地文件。
`push`	write	通过一次批量导入（`addAndUpdateOnly`），将不存在冲突的更改应用为本地 → brainCloud 同步。
`sync`	write	完整双向同步：拉取 + 推送，并对两侧都已更改的脚本进行三方合并（从 brainCloud 版本历史中恢复合并基准）。应用并推送无冲突的合并；将类似 git 的 `<<<<<<<` 标记写入本地，并在 `conflicted` 中报告真正的冲突。仅在设置 `allowDeletes` 时才会双向删除。

所有工具都接受 rootDir（本地同步文件夹）、ticket（从 getSyncTicket 获取），以及可选的 branch（默认为从 .git/HEAD 获取的当前 git 分支）。pull/status 使用 read 票据即可；push/sync 需要 write 票据。在 pull/push 中，冲突和反向更改绝不会自动应用——只有 sync 会协调两个方向并执行合并。

配置为 MCP 服务

{
  "mcpServers": {
    "braincloud-helper": {
      "command": "npx",
      "args": ["-y", "@braincloud/mcp-helper@latest"]
    }
  }
}

npx @latest 会在每次启动时确保 helper 保持最新；CI 环境请固定版本。请将它与托管的 braincloud-mcp 配合使用（该服务负责提供票据并执行实时锁定策略）。

开发

npm install
npm run build --workspace @braincloud/cloudsync-core   # helper depends on the built core
npm test  --workspace @braincloud/mcp-helper
npm run build --workspace @braincloud/mcp-helper

支持 Markdown

登录后评论