@contentrain/mcp

@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 AI-generated content governance infrastructure:

• 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/{operation}/{model}/{locale}/{timestamp}-{suffix})
• auto-merge: feature merges into contentrain, baseBranch advanced via update-ref, .contentrain/ files selectively synced to developer's working tree
• 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
• 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

24 MCP tools — 19 core + 5 media — 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 19 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, validate. The requirement map lives in TOOL_REQUIREMENTS (@contentrain/mcp/tools/availability).

Tool	Purpose	Read-only	Destructive
contentrain_status	Project status, config, models, branch health, context	Yes	—
contentrain_describe	Full schema and sample data for a model	Yes	—
contentrain_describe_format	File-format and storage contract reference	Yes	—
contentrain_doctor	Project health report (env, structure, models, orphans, local + remote branches, SDK)	Yes	—
contentrain_init	Create .contentrain/ structure and base config	—	—
contentrain_scaffold	Apply a starter template such as blog, docs, landing, saas	—	—
contentrain_model_save	Create or update a model definition	—	—
contentrain_model_delete	Delete a model definition	—	Yes
contentrain_content_save	Save content entries for any model kind	—	—
contentrain_content_delete	Delete content entries	—	Yes
contentrain_content_list	Read content entries	Yes	—
contentrain_validate	Validate project content, optionally auto-fix structural issues	—	—
contentrain_submit	Push cr/* branches to remote, then lazily prune merged local + remote leftovers	—	—
contentrain_merge	Merge a review-mode branch into contentrain locally (by exact branch or model); deletes its remote copy	—	—
contentrain_branch_list	List pending cr/* branches with merge status (remote: true adds remote view)	Yes	—
contentrain_branch_delete	Delete a stale/failed cr/* branch locally and on the remote (contentrain branch protected)	—	Yes
contentrain_scan	Graph- and candidate-based hardcoded string scan	Yes	—
contentrain_apply	Normalize extract/reuse execution with dry-run support	—	—
contentrain_bulk	Bulk locale copy, status updates, and deletes	—	—
contentrain_media_list	List media assets (search, tag filter, cursor pagination)	Yes	—
contentrain_media_get	Get one media asset by id	Yes	—
contentrain_media_ingest	Ingest an asset from a source URL (provider fetches server-side)	—	—
contentrain_media_update	Update asset metadata (alt, tags, filename)	—	—
contentrain_media_delete	Delete an asset from the media stack	—	Yes

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 contentrain-mcp

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

Embed the server in your own process

import { createServer } from '@contentrain/mcp/server'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = createServer(process.cwd())
const transport = new StdioServerTransport()

await server.connect(transport)

createServer also accepts an options object: { provider, projectRoot?, instructions? }. instructions sets the MCP instructions string clients receive at initialize (defaults to a built-in DEFAULT_INSTRUCTIONS, kept under 512 characters; pass '' to omit).

Example MCP Flow

Typical agent workflow:

• Call contentrain_status
• If needed, call contentrain_init
• Create models with contentrain_model_save or contentrain_scaffold
• Save content with contentrain_content_save
• Validate with contentrain_validate
• For hardcoded strings, use contentrain_scan then contentrain_apply
• Push review branches with contentrain_submit

Normalize Flow

Normalize is intentionally split into two phases:

1. Extract

contentrain_scan finds candidate strings.

contentrain_apply with mode: "extract":

• creates or updates models
• writes content entries
• records source tracking
• creates a review branch (cr/normalize/extract/{domain}/{timestamp})

2. Reuse

contentrain_apply with mode: "reuse":

• patches source files using agent-provided expressions
• adds imports when needed
• enforces patch path safety and scope checks
• creates a separate review branch (cr/normalize/reuse/{model}/{locale}/{timestamp})

This split keeps content extraction separate from source rewriting.

Transport / provider requirements

Normalize (contentrain_scan and contentrain_apply) requires local disk access — AST scanners walk the source tree and patch files in place. It runs only on a LocalProvider (stdio transport, or HTTP transport configured with a LocalProvider).

Remote providers such as GitHubProvider expose astScan: false, sourceRead: false, and sourceWrite: false. Calling these tools over a remote provider returns a uniform capability error:

{
  "error": "contentrain_scan requires local filesystem access.",
  "capability_required": "astScan",
  "hint": "This tool is unavailable when MCP is driven by a remote provider (e.g. GitHubProvider). Use a LocalProvider or the stdio transport."
}

Agents driving a remote transport should fall back to a local transport (or a local checkout) before invoking normalize.

Remote Providers

MCP supports three backends behind the same RepoProvider contract:

• LocalProvider — simple-git + worktree. Every tool (normalize included) works on it. Stdio transport defaults to this.
• GitHubProvider — Octokit over the Git Data + Repos APIs. No clone, no worktree. @octokit/rest ships as an optional peer dependency.
• GitLabProvider — gitbeaker over the GitLab REST API. No clone, no worktree. @gitbeaker/rest ships as an optional peer dependency. Supports gitlab.com and self-hosted CE / EE.

Each remote provider implements the same surface: reader (readFile / listDirectory / fileExists), writer (applyPlan — one atomic commit), branch ops (list / create / delete / diff / merge / isMerged / getDefaultBranch). mergeBranch goes straight through on GitHub; on GitLab it opens an MR and immediately accepts it so the final MergeResult shape matches either way.

GitLab — installation & usage

pnpm add @gitbeaker/rest

import { createGitLabProvider } from '@contentrain/mcp/providers/gitlab'
import { createServer } from '@contentrain/mcp/server'

const provider = await createGitLabProvider({
  auth: { type: 'pat', token: process.env.GITLAB_TOKEN! },
  project: {
    projectId: 'acme/site',             // or numeric project ID
    host: 'https://gitlab.company.com', // omit for gitlab.com
  },
})

const server = createServer({ provider })
// serve over stdio or the HTTP transport from @contentrain/mcp/server/http

Capabilities: sourceRead, sourceWrite, astScan, localWorktree are all false; pushRemote, branchProtection, pullRequestFallback are true. Normalize / scan / apply reject with a capability error on GitLabProvider — fall back to a local transport for those flows.

Bitbucket — coming soon

Bitbucket Cloud + Data Center support is on the roadmap. Until the provider ships, use the contentrain_describe_format tool to drive Contentrain content operations manually from a Bitbucket checkout via the LocalProvider path.

Core Exports

The package also exposes low-level modules for embedding and advanced use:

• @contentrain/mcp/server
• @contentrain/mcp/server/http
• @contentrain/mcp/core/config
• @contentrain/mcp/core/context
• @contentrain/mcp/core/model-manager
• @contentrain/mcp/core/content-manager
• @contentrain/mcp/core/validator
• @contentrain/mcp/core/scanner
• @contentrain/mcp/core/graph-builder
• @contentrain/mcp/core/apply-manager
• @contentrain/mcp/core/scan-config
• @contentrain/mcp/core/doctor
• @contentrain/mcp/core/contracts
• @contentrain/mcp/core/ops — plan APIs plus content-root-relative path helpers: contentDirPath, contentFilePath, documentFilePath, metaFilePath
• @contentrain/mcp/core/overlay-reader
• @contentrain/mcp/util/detect
• @contentrain/mcp/util/fs
• @contentrain/mcp/git/transaction
• @contentrain/mcp/git/branch-lifecycle — branch health/cleanup plus the remote cr/* lifecycle: deleteRemoteBranch, listRemoteCrBranches, pruneMergedRemoteBranches, isRefMerged, classifyMergedBranches
• @contentrain/mcp/tools/annotations
• @contentrain/mcp/templates
• @contentrain/mcp/providers/local
• @contentrain/mcp/providers/github
• @contentrain/mcp/providers/gitlab

These are intended for Contentrain tooling and advanced integrations, not for direct manual editing of .contentrain/ files.

Design Constraints

Key design decisions in this package:

• local-first by default — stdio transport + LocalProvider works without any network dependency
• provider-agnostic engine — the same core tools run over LocalProvider, GitHubProvider, or GitLabProvider behind a single RepoProvider contract; media tools ride the provider's optional media facet
• remote provider SDKs (@octokit/rest, @gitbeaker/rest) are optional peer dependencies — pulled in only when their provider is used
• JSON-only content storage
• git-backed write workflow (worktree transaction locally, single atomic commit over the Git Data / REST APIs remotely)
• canonical serialization — byte-deterministic output, sorted keys, trailing newline
• framework-agnostic MCP layer
• agent decides content semantics, MCP enforces deterministic execution
• capability gates — tools that need source-tree access (normalize, scan, apply, doctor) reject with a uniform capability_required error on remote providers

Development

From the monorepo root:

pnpm --filter @contentrain/mcp build
pnpm --filter @contentrain/mcp test
pnpm --filter @contentrain/mcp typecheck
pnpm exec oxlint packages/mcp/src packages/mcp/tests

Related Packages

• contentrain — CLI and local review tooling
• @contentrain/query — generated runtime query SDK
• @contentrain/rules — IDE/agent rules and prompts
• @contentrain/types — shared schema and model types

Documentation

Full documentation at ai.contentrain.io/packages/mcp.

License

MIT