Contentrain

@contentrain/mcp

Provider-agnostic MCP engine for Contentrain — local-first by default, with optional GitHub and GitLab backends and an HTTP transport for remote drivers such as Studio.

Start here:

• 2-minute product demo
• MCP package docs
• Normalize guide

Contentrain is a content governance ecosystem for teams and AI agents. In it, this engine works like this:

• agent produces content decisions
• MCP applies deterministic filesystem and git workflow
• humans review and merge
• the system keeps schema, locale, and serialization consistent

This package is the runtime core behind Contentrain's MCP integration. It can be used as:

• a stdio MCP server (contentrain-mcp)
• an embeddable server (createServer(projectRoot))
• a low-level toolkit for config, models, content, validation, scanning, and git transaction flow

Install

pnpm add @contentrain/mcp

Requirements:

• Node.js 22+
• git available on the machine

Optional parser support for higher-quality source scanning:

• @vue/compiler-sfc
• @astrojs/compiler
• svelte

They are listed as optional dependencies. The scanner still works without them, but Vue/Astro/Svelte detection is stronger when they are installed.

What It Does

@contentrain/mcp manages a .contentrain/ directory in your project and exposes MCP tools for:

• project initialization
• model creation and deletion
• content save, delete, and list
• validation and auto-fix
• normalize scan and apply flows
• bulk operations
• branch submission, review-mode merge, and branch-health awareness
• project health checking (doctor)

All write operations are designed around git-backed safety:

• a dedicated contentrain branch serves as the content state single source of truth
• each write creates a temporary worktree on a feature branch forked from contentrain (branch name: cr/{scope}/{target}/{timestamp}-{suffix}, e.g. cr/content/blog-post/1730000000-a1b2; bulk locale copies, locale-scoped status changes and scaffold add a {locale} segment before the timestamp)
• auto-merge: feature merges into contentrain, baseBranch advanced via update-ref, .contentrain/ files selectively synced to developer's working tree when the base branch is the one checked out
• baseBranch = CONTENTRAIN_BRANCH env → repository.default_branch → remote HEAD → main → master → checked-out branch → main (fallback). A write made on a feature branch never merges, moves or pushes that branch
• plans are read from the working tree but committed on the fetched contentrain tip: JSON changes are carried over key by key, so entries another writer pushed are kept; a same-value conflict writes nothing and returns CONTENT_WORKING_TREE_STALE
• on a checked-out feature branch, which writes do not update, .contentrain/** is read from the contentrain ref instead (source files still from the working tree); read tools report it as content_source
• review: feature branch pushed to remote for team review; once merged (or deleted), its remote copy is removed too — best-effort, opt out with remoteBranchCleanup: false in config.json
• local mode (git.push: false or CONTENTRAIN_NO_PUSH=1): nothing is ever pushed or deleted on the remote, and every result says so — see Git environment and local mode
• every local write's git block names the resolved base_branch; when it is not the checked-out branch, the result's warning says your working tree was left alone
• commit hooks: skipped on machine commits by default; git.verify: true or CONTENTRAIN_VERIFY=1 runs them, and a rejecting hook fails the write with its output — see Commit hooks
• merged-branch detection survives base-history rewrites (ancestry check with a patch-id fallback), so rebases/squashes don't strand stale branches
• developer's working tree is never mutated during MCP git operations (no stash, no checkout, no merge)
• context.json never lands on feature branches — it is regenerated on the contentrain branch after merge (locally by the transaction layer; in remote flows by the orchestrator that owns the merge)
• canonical JSON output — sorted keys, 2-space indent, trailing newline
• validation + next-step hints surfaced to the caller

Tool Surface

23 MCP tools, plus 5 media tools on a media-capable provider such as Studio, with annotations (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint: false everywhere except contentrain_media_ingest, which fetches a caller-supplied URL server-side) for client safety hints.

Tool listing is capability-aware. tools/list only advertises tools the resolved provider + projectRoot pair can actually satisfy. A local stdio server lists the 23 core tools; a session driven by a remote provider (GitHub/GitLab, no local checkout) lists only the remote-safe subset — status, describe, describe_format, model_save, model_delete, content_save, content_delete, content_list, content_status, vocabulary_save, vocabulary_delete, validate. The requirement map lives in TOOL_REQUIREMENTS (@contentrain/mcp/tools/availability).

The five contentrain_media_* tools are a deterministic passthrough to the provider's optional media facet (RepoProvider.media) and are registered only when the provider exposes one (e.g. Studio MCP Cloud). Local stdio servers and plain GitHub/GitLab providers never list them. Ingest is URL-based (MCP has no binary channel); the provider implementation owns SSRF/MIME/size policy for the fetch.

Quick Start

Configure via CLI (recommended)

npx contentrain setup claude-code   # or: cursor, vscode, windsurf, copilot

This auto-creates the correct MCP config file for your IDE. See CLI docs for details.

Run as a standalone MCP server

CONTENTRAIN_PROJECT_ROOT=/path/to/project npx -y @contentrain/mcp

If CONTENTRAIN_PROJECT_ROOT is omitted, the current working directory is used.

Git environment and local mode

These apply to the local provider (stdio, LocalProvider):

Local mode keeps every write on local branches: no branch push, no review push, no push after an auto-merge, approve or reconcile, and no remote branch delete or prune. Fetching is not a push and still happens when a remote exists. Turn it on for a project with "git": { "push": false } in .contentrain/config.json, or for one run with CONTENTRAIN_NO_PUSH=1.

Precedence: the env wins over the config in both directions. CONTENTRAIN_NO_PUSH=1 turns pushing off even when config allows it; CONTENTRAIN_NO_PUSH=0 turns it back on over git.push: false. With neither, pushing is on.

It is never a silent success. Each write's git block reports remote_push: "disabled" with remote_note: "not pushed (local mode)", and next_steps carries a LOCAL MODE line. contentrain_submit returns an error instead of pushing; land review branches with contentrain_merge. contentrain_merge and contentrain_branch_delete delete the local branch as usual and leave any remote copy untouched; contentrain_branch_delete reports remote_skipped: "local-mode", contentrain_merge reports remote: { deleted: false, skipped: "local-mode" }.

Commit hooks

By default Contentrain's machine commits (the cr/* content commit, the context.json commit, a reconcile merge commit, the seed commit of an empty repo) skip the repository's commit hooks (pre-commit, prepare-commit-msg, commit-msg). That keeps exis