@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