@braincloud/mcp-helper

@braincloud/mcp-helper

A local stdio MCP server that gives AI clients (Claude Code, Cursor, Codex, …) filesystem access for brainCloud cloud-code sync.

It is deliberately trustless: it never authenticates to brainCloud on its own and stores no credential. Every Builder API call is driven by a short-lived, app-scoped ticket the AI obtains from the hosted braincloud-mcp's getSyncTicket tool and passes in. Bulk script data flows helper → Builder API directly — never through the AI's context.

Format and sync logic come from @braincloud/cloudsync-core; this package is the Node filesystem + MCP shell around it.

Tools

Tool	Ticket	What it does
status	read	Dry-run: classify every script (in-sync / pull / push / conflict / new / delete). No writes.
pull	read	Apply brainCloud → local for non-conflicting changes. Local deletes only with allowDeletes.
push	write	Apply local → brainCloud for non-conflicting changes via one bulk import (addAndUpdateOnly).
sync	write	Full two-way sync: pull + push + 3-way merge for scripts changed on both sides (merge base recovered from brainCloud version history). Clean merges are applied + pushed; real conflicts get git-style <<<<<<< markers written locally and reported in conflicted. Deletes both ways only with allowDeletes.

All take rootDir (the local sync folder), ticket (from getSyncTicket), and an optional branch (defaults to the current git branch from .git/HEAD). pull/status work with a read ticket; push/sync need a write ticket. In pull/push, conflicts and opposite-direction changes are never auto-applied — only sync reconciles both directions and merges.

Configure as an MCP server

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

npx @latest keeps the helper current on each launch; pin a version for CI. Pair it with the hosted braincloud-mcp (which vends the tickets and runs the live-lock policy).

Develop

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