mcpField
B
brainCloud MCP Helper

brainCloud MCP Helper

Local
github.com/getbraincloudDeveloper Tools1Updated 16w ago
Repository

About brainCloud MCP Helper

brainCloud MCP Helper is a local stdio server that gives AI clients filesystem access for syncing brainCloud cloud code. It uses short-lived tickets from the hosted braincloud-mcp and supports two-way sync with three-way merging.

Key features

  1. 01Classify sync status without writes
  2. 02Pull or push non-conflicting changes
  3. 03Two-way sync with three-way merge
  4. 04Git-style markers for merge conflicts

Use cases

  1. 01Review cloud-code changes before applying them
  2. 02Sync local scripts with brainCloud
  3. 03Resolve concurrent edits to cloud scripts

MCP support

The local stdio MCP server exposes status, pull, push, and sync tools. It pairs with the hosted `braincloud-mcp`, which issues the short-lived tickets required for Builder API calls.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "com-braincloudservers-braincloud-mcp-helper": {
      "command": "npx",
      "args": [
        "-y",
        "@braincloud/mcp-helper"
      ]
    }
  }
}
Run commandnpx -y @braincloud/mcp-helper

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@braincloud/mcp-helper6.0.0

Tools

4

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
branchstringNoGit branch to sync. Defaults to the current branch from .git/HEAD; if the folder is not a git repo, a reserved no-branch key is used and can later be adopted onto a real branch.
ticketobjectYesShort-lived ticket from the hosted MCP getSyncTicket tool.
ticket.appNamestringYesTarget app name (from getSyncTicket).
ticket.baseUrlstringYesApp-scoped Builder base URL (from getSyncTicket).
ticket.expiresAtstringNoISO-8601 ticket expiry (from getSyncTicket).
ticket.authorizationstringYesAuthorization header value (from getSyncTicket).
rootDirstringNoAbsolute path to the local cloud-code sync folder (the .ccjs tree + .bcsync). Optional: if omitted, the helper discovers the nearest .bcsync folder at or above its working directory. Pass it explicitly for a brand-new folder, before its first sync.
confirmAppNamestringNoSafety confirmation. Only needed for a previously-synced folder that has no committed .bcsync app mapping (e.g. synced by an older helper): set this to the ticket's appName to confirm you intend to sync this folder with that app. Once .bcsync exists it is not needed.
adoptNoGitBranchbooleanNoConfirm moving the no-git sync state and app mapping onto the current git branch (dropping the no-branch entry). Needed once, when a folder first synced without git is now on a real branch; the tool asks for it rather than orphaning the prior state.

Details

From the project README

@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

ToolTicketWhat it does
statusreadDry-run: classify every script (in-sync / pull / push / conflict / new / delete). No writes.
pullreadApply brainCloud → local for non-conflicting changes. Local deletes only with allowDeletes.
pushwriteApply local → brainCloud for non-conflicting changes via one bulk import (addAndUpdateOnly).
syncwriteFull 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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.