Contentrain MCP
Extract, govern, and ship structured content from your codebase.
@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:
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/compilersvelte
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
contentrainbranch 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
- developer's working tree is never mutated during MCP git operations (no stash, no checkout, no merge)
- context.json is committed together with content changes, not as a separate commit
- canonical JSON output — sorted keys, 2-space indent, trailing newline
- validation + next-step hints surfaced to the caller
Tool Surface
17 MCP tools with annotations (readOnlyHint, destructiveHint, idempotentHint) for client safety hints:
| 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, 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 | — | — |
contentrain_merge | Merge a review-mode branch into contentrain locally | — | — |
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 | — | — |
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)
Example MCP Flow
Typical agent workflow:
- Call
contentrain_status - If needed, call
contentrain_init - Create models with
contentrain_model_saveorcontentrain_scaffold - Save content with
contentrain_content_save - Validate with
contentrain_validate - For hardcoded strings, use
contentrain_scanthencontentrain_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/restships as an optional peer dependency. - GitLabProvider — gitbeaker over the GitLab REST API. No clone, no worktree.
@gitbeaker/restships 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@contentrain/mcp/core/overlay-reader@contentrain/mcp/util/detect@contentrain/mcp/util/fs@contentrain/mcp/git/transaction@contentrain/mcp/git/branch-lifecycle@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 17 tools run over LocalProvider, GitHubProvider, or GitLabProvider behind a single
RepoProvidercontract - 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_requirederror 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
Verwandte Server
Scout Monitoring MCP
SponsorPut performance and error data directly in the hands of your AI assistant.
Alpha Vantage MCP Server
SponsorAccess financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more
即梦AI多模态MCP
A multimodal generation service using Volcengine Jimeng AI for image generation, video generation, and image-to-video conversion.
GoMCP
A Go library for building clients and servers using the Model Context Protocol (MCP).
Code Graph RAG MCP
Code Rag with Graph - local only installation
Tidymodels MCP Server
An MCP server for accessing tidymodels GitHub information and generating code.
ChemMCP
A collection of 19 professional tools for chemical molecular processing based on the Model Context Protocol (MCP).
AgentStamp
Trust intelligence platform for AI agents — identity certification, trust scoring, forensic audit trails, and x402 micropayments. 14 MCP tools.
RandomWeb3MCP
A random element generation service based on EVM block hash for games, finance, testing, and other fields.
SceneView MCP
22 tools for 3D and AR development — generates correct, compilable SceneView code for Android (Jetpack Compose) and iOS (SwiftUI). 858 tests.
conKurrence
AI evaluation toolkit — measure inter-rater agreement (Fleiss' κ, Kendall's W) across multiple LLM providers
Photoshop MCP Server
An MCP server for integrating with and automating Adobe Photoshop using the photoshop-python-api.