Contentrain MCP server
Commit 7 Nov 2026Mengelola tata kelola konten melalui filesystem deterministik dan workflow git untuk AI agent dan tim.
Juga dikenal sebagai Contentrain/ai, @contentrain/mcp
- Stars
- 7
- Tools
- 23
- Unduhan, 30 hari
- 8.275
- Versi terbaru
- 3.12.3
- Commit terakhir
- 7 Nov 2026
- Lisensi
- MIT
Apa itu Contentrain MCP?
Mengelola tata kelola konten melalui filesystem deterministik dan workflow git untuk AI agent dan tim. Server ini menyediakan 23 tool, seperti contentrain_status, contentrain_describe, contentrain_describe_format.
Ringkasan dibuat dari README proyek
Tentang Contentrain MCP server
Contentrain menyediakan ekosistem tata kelola konten yang dirancang untuk tim dan AI agent guna mengelola data terstruktur melalui filesystem deterministik dan workflow git. Sistem ini memastikan konsistensi di seluruh schema, locale, dan serialisasi dengan menggunakan content branch khusus sebagai single source of truth. Engine ini bersifat provider-agnostic dan dapat dideploy sebagai local stdio server, embeddable server, atau melalui transport HTTP untuk remote driver seperti Studio.
Developer dapat menggunakan server ini untuk mengelola direktori .contentrain di dalam project mereka. Tersedia 23 core tools untuk tugas-tugas seperti inisialisasi project, pembuatan model, penyimpanan konten, dan validasi. Sistem ini memanfaatkan keamanan berbasis git dengan membuat temporary worktrees pada feature branches untuk setiap operasi penulisan, guna mencegah mutasi langsung pada working tree milik developer. Pengguna dapat mengonfigurasi local-only mode untuk mencegah remote push atau mengaktifkan verifikasi commit hook melalui environment variables seperti CONTENTRAIN_VERIFY.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Cara menginstal Contentrain MCP
Format diverifikasi 10 Nov 2026Tambahkan ke CursorTambahkan ke GooseInstal Contentrain MCP di Claude Code
$ claude mcp add contentrain -- npx -y @contentrain/mcpInstal Contentrain MCP di Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"contentrain": {
"command": "npx",
"args": [
"-y",
"@contentrain/mcp"
]
}
}
}Instal Contentrain MCP di VS Code
.vscode/mcp.json
{
"servers": {
"contentrain": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@contentrain/mcp"
]
}
}
}Instal Contentrain MCP di VS Code CLI
$ code --add-mcp '{"name":"contentrain","type":"stdio","command":"npx","args":["-y","@contentrain/mcp"]}'Instal Contentrain MCP di Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"contentrain": {
"command": "npx",
"args": [
"-y",
"@contentrain/mcp"
]
}
}
}Instal Contentrain MCP di Codex
$ codex mcp add contentrain -- npx -y @contentrain/mcpInstal Contentrain MCP di Codex config.toml
~/.codex/config.toml
[mcp_servers.contentrain] command = "npx" args = ["-y", "@contentrain/mcp"]
Instal Contentrain MCP di Gemini CLI
$ gemini mcp add -s user contentrain npx -- -y @contentrain/mcpInstal Contentrain MCP di Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"contentrain": {
"command": "npx",
"args": [
"-y",
"@contentrain/mcp"
]
}
}
}Dijalankan oleh HostedMCP pada 16 Nov 2026
Kami menjalankan perintah ini untuk @contentrain/mcp 3.12.3 di container terisolasi tanpa jaringan dan tanpa key. Server menjawab dan mendaftar 23 tool.
Tool Contentrain MCP 23
Dibaca langsung dari server dengan tools/listcontentrain_statusHanya bacaGet full project status (read-only). Returns config, models, context. Do NOT manually edit .contentrain/ based on this output.
contentrain_describeHanya bacaGet full schema of a single model (read-only). Do NOT manually create content files — use contentrain_content_save instead.
contentrain_describe_formatHanya bacaDescribes the Contentrain content file format for any language/platform. Returns a comprehensive specification of the file structure, JSON formats, markdown conventions, meta files, and locale strategies.
contentrain_initAksiInitialize .contentrain/ structure. Changes are auto-committed to git — do NOT manually create .contentrain/ files.
contentrain_scaffoldAksiTemplate-based project setup. Available templates: blog, landing, docs, ecommerce, saas, i18n, mobile. Changes are auto-committed to git.
contentrain_model_saveAksiCreate or update a model definition. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
contentrain_model_deleteAksiDelete a model and its content/meta. Changes are auto-committed to git — do NOT manually edit .contentrain/ files.
contentrain_content_saveAksiSave content entries. Entry format varies by model kind: DICTIONARY — provide "locale" and "data" (flat key-value, all string values); "id" and "slug" are ignored; data keys are the identities. COLLECTION — provide "locale" and "data"; "id" is optional (auto-generated if omitted); "slug" is ignored. DOCUMENT — provide "slug" (required), "locale", and "data"; use the "body" key inside data for markdown content. SINGLETON — provide only "locale" and "data". MEDIA FIELDS (image/video/file): for a media-library asset, pass its storage path ("media/...") or URL; in cloud mode these are automatically normalized to absolute public delivery URLs on save (in markdown bodies too), so saved content renders in a browser anywhere with no SDK — in local mode the relative path is kept as-is. For external images (e.g. a CDN or Unsplash URL), pass the URL directly; it is saved untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
contentrain_content_deleteAksiDelete content entries. For dictionaries, use "keys" to remove specific keys (omit to delete entire locale file). Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
contentrain_content_listHanya bacaList content entries (read-only). Each entry carries its publish state under "meta" — status, plus publish_at/expire_at when set — read from the listed locale's meta; singletons and dictionaries carry it at the top level. Local and remote sessions return the same shape. Change status with contentrain_content_status. Returns data from .contentrain/ — do NOT manually create or modify content files.
contentrain_content_statusAksiChange the status of content entries — this is how an entry is published, unpublished or archived. Address records the way their meta is laid out: COLLECTION — "entry_ids"; DOCUMENT — "slugs"; SINGLETON and DICTIONARY — neither (one record per locale). i18n models change every supported locale unless "locale" is given. Setting status "published" validates the targeted entries first; if they have errors, nothing is committed. Records already at the requested status are reported as unchanged and not rewritten. contentrain_content_list shows each entry's current status under "meta". Changes are committed to git and follow the project's review or auto-merge workflow — do NOT manually edit .contentrain/meta files.
contentrain_vocabulary_saveAksiAdd or update canonical vocabulary terms. Terms nest as { "term-slug": { "en": "…", "tr": "…" } } — the OUTER key is the term, the INNER key is a locale. Merges with the existing vocabulary: a term you omit is untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/vocabulary.json.
| contentrain_status | Get full project status (read-only). Returns config, models, context. Do NOT manually edit .contentrain/ based on this output. | Hanya baca |
| contentrain_describe | Get full schema of a single model (read-only). Do NOT manually create content files — use contentrain_content_save instead. | Hanya baca |
| contentrain_describe_format | Describes the Contentrain content file format for any language/platform. Returns a comprehensive specification of the file structure, JSON formats, markdown conventions, meta files, and locale strategies. | Hanya baca |
| contentrain_init | Initialize .contentrain/ structure. Changes are auto-committed to git — do NOT manually create .contentrain/ files. | Aksi |
| contentrain_scaffold | Template-based project setup. Available templates: blog, landing, docs, ecommerce, saas, i18n, mobile. Changes are auto-committed to git. | Aksi |
| contentrain_model_save | Create or update a model definition. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool. | Aksi |
| contentrain_model_delete | Delete a model and its content/meta. Changes are auto-committed to git — do NOT manually edit .contentrain/ files. | Aksi |
| contentrain_content_save | Save content entries. Entry format varies by model kind: DICTIONARY — provide "locale" and "data" (flat key-value, all string values); "id" and "slug" are ignored; data keys are the identities. COLLECTION — provide "locale" and "data"; "id" is optional (auto-generated if omitted); "slug" is ignored. DOCUMENT — provide "slug" (required), "locale", and "data"; use the "body" key inside data for markdown content. SINGLETON — provide only "locale" and "data". MEDIA FIELDS (image/video/file): for a media-library asset, pass its storage path ("media/...") or URL; in cloud mode these are automatically normalized to absolute public delivery URLs on save (in markdown bodies too), so saved content renders in a browser anywhere with no SDK — in local mode the relative path is kept as-is. For external images (e.g. a CDN or Unsplash URL), pass the URL directly; it is saved untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool. | Aksi |
| contentrain_content_delete | Delete content entries. For dictionaries, use "keys" to remove specific keys (omit to delete entire locale file). Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool. | Aksi |
| contentrain_content_list | List content entries (read-only). Each entry carries its publish state under "meta" — status, plus publish_at/expire_at when set — read from the listed locale's meta; singletons and dictionaries carry it at the top level. Local and remote sessions return the same shape. Change status with contentrain_content_status. Returns data from .contentrain/ — do NOT manually create or modify content files. | Hanya baca |
| contentrain_content_status | Change the status of content entries — this is how an entry is published, unpublished or archived. Address records the way their meta is laid out: COLLECTION — "entry_ids"; DOCUMENT — "slugs"; SINGLETON and DICTIONARY — neither (one record per locale). i18n models change every supported locale unless "locale" is given. Setting status "published" validates the targeted entries first; if they have errors, nothing is committed. Records already at the requested status are reported as unchanged and not rewritten. contentrain_content_list shows each entry's current status under "meta". Changes are committed to git and follow the project's review or auto-merge workflow — do NOT manually edit .contentrain/meta files. | Aksi |
| contentrain_vocabulary_save | Add or update canonical vocabulary terms. Terms nest as { "term-slug": { "en": "…", "tr": "…" } } — the OUTER key is the term, the INNER key is a locale. Merges with the existing vocabulary: a term you omit is untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/vocabulary.json. | Aksi |
Tampilkan semua 23 toolTampilkan lebih sedikit tool
contentrain_vocabulary_deleteAksiRemove canonical vocabulary terms by slug. Content already using a term is not touched — the vocabulary only advises. Changes are auto-committed to git.
contentrain_validateAksiValidate project content against model schemas. Detects required field violations, type mismatches, broken relations, secret leaks, i18n parity issues, and more. If fix:true, auto-fixes structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout, scheduling keys an older content_save leaked into document frontmatter) and backfills a missing model title_field — do NOT manually edit .contentrain/ files. Content without meta gets meta with status published, matching what delivery already serves. A fix that would change whether an entry is delivered is listed in visibility_changes and left on its branch for review instead of auto-merged.
contentrain_submitAksiPush cr/* branches to remote. MCP is push-only — PR creation is handled by the platform. Do NOT manually push or create PRs.
contentrain_mergeAksiMerge a review-mode branch into contentrain. Local git operation — no external platform needed. Merges the feature branch into the contentrain branch, advances the base branch via update-ref, selectively syncs .contentrain/ files to the working tree, and prunes the merged branch. Target by exact "branch" name, or resolve by "model" (+ optional "locale"/"latest").
contentrain_branch_listHanya bacaList pending contentrain (cr/*) branches with their merge status against the contentrain branch. Use this to discover branch names for contentrain_merge / contentrain_branch_delete, and to monitor branch-health limits (warning at 50, blocked at 80 unmerged).
contentrain_branch_deleteAksiDelete a pending contentrain (cr/*) branch that will not be merged — e.g. a branch left behind by a failed operation, or a superseded draft. Only cr/* branches can be deleted; the contentrain branch is protected. This is destructive: the branch and its unmerged commits are removed.
contentrain_reconcileAksiReconcile a diverged contentrain ↔ base-branch pair with a content-aware three-way merge. DRY RUN (default, dry_run:true): reports what would merge and which conflicts need a decision — touches nothing. EXECUTE (dry_run:false): performs the merge as a two-parent commit on contentrain and fast-forwards the base branch. Everything one side changed merges mechanically (entry-, key-, term+locale-level); only the same item changed differently on both sides becomes a conflict. Answer conflicts by passing resolutions (from the dry-run ids) and running again — a resolution whose values changed since the dry-run is dropped and the conflict re-reported. Recommended workflow: always run dry_run first, review the summary and conflicts, then execute.
contentrain_scanHanya bacaScan project source code for content strings. Three modes: "graph" builds import/component graph for project intelligence, "candidates" extracts string literals with pre-filtering and pagination, "summary" provides quick overview stats. Read-only — no changes to disk or git. MCP finds strings deterministically; the agent decides what is content. Recommended workflow: start with "summary" or "graph" for orientation, then paginate through "candidates" to evaluate strings.
contentrain_applyAksiApply normalize operations. Two modes: "extract" writes agent-approved strings to Contentrain content files (source untouched), "reuse" patches source files with agent-provided replacement expressions. DRY RUN (default, dry_run:true): validates inputs, resolves conflicts, and returns a full preview — NO changes to disk or git. EXECUTE (dry_run:false): writes files to disk, commits to a branch, and requires branch health check to pass. Recommended workflow: always run dry_run first, review the preview, then call again with dry_run:false to execute. Normalize operations always use review workflow (never auto-merge).
contentrain_bulkAksiBatch operations on content entries: copy a locale, or delete many collection entries. All operations are auto-committed to git. To publish or change status, use contentrain_content_status. DRY RUN (dry_run:true): runs the whole operation in a throwaway worktree and reports exactly what would change — nothing is committed and no branch survives. Recommended workflow: preview with dry_run:true, review the counts, then call again to execute.
contentrain_doctorHanya bacaProject health report (read-only). Returns structured checks: git, node, .contentrain/ structure, model parse, orphan content, branch pressure, SDK freshness. Pass `usage: true` for a deeper analysis of content-key references in source files (unused keys, duplicate dictionary values, locale coverage). Local-filesystem only — unavailable over remote providers.
| contentrain_vocabulary_delete | Remove canonical vocabulary terms by slug. Content already using a term is not touched — the vocabulary only advises. Changes are auto-committed to git. | Aksi |
| contentrain_validate | Validate project content against model schemas. Detects required field violations, type mismatches, broken relations, secret leaks, i18n parity issues, and more. If fix:true, auto-fixes structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout, scheduling keys an older content_save leaked into document frontmatter) and backfills a missing model title_field — do NOT manually edit .contentrain/ files. Content without meta gets meta with status published, matching what delivery already serves. A fix that would change whether an entry is delivered is listed in visibility_changes and left on its branch for review instead of auto-merged. | Aksi |
| contentrain_submit | Push cr/* branches to remote. MCP is push-only — PR creation is handled by the platform. Do NOT manually push or create PRs. | Aksi |
| contentrain_merge | Merge a review-mode branch into contentrain. Local git operation — no external platform needed. Merges the feature branch into the contentrain branch, advances the base branch via update-ref, selectively syncs .contentrain/ files to the working tree, and prunes the merged branch. Target by exact "branch" name, or resolve by "model" (+ optional "locale"/"latest"). | Aksi |
| contentrain_branch_list | List pending contentrain (cr/*) branches with their merge status against the contentrain branch. Use this to discover branch names for contentrain_merge / contentrain_branch_delete, and to monitor branch-health limits (warning at 50, blocked at 80 unmerged). | Hanya baca |
| contentrain_branch_delete | Delete a pending contentrain (cr/*) branch that will not be merged — e.g. a branch left behind by a failed operation, or a superseded draft. Only cr/* branches can be deleted; the contentrain branch is protected. This is destructive: the branch and its unmerged commits are removed. | Aksi |
| contentrain_reconcile | Reconcile a diverged contentrain ↔ base-branch pair with a content-aware three-way merge. DRY RUN (default, dry_run:true): reports what would merge and which conflicts need a decision — touches nothing. EXECUTE (dry_run:false): performs the merge as a two-parent commit on contentrain and fast-forwards the base branch. Everything one side changed merges mechanically (entry-, key-, term+locale-level); only the same item changed differently on both sides becomes a conflict. Answer conflicts by passing resolutions (from the dry-run ids) and running again — a resolution whose values changed since the dry-run is dropped and the conflict re-reported. Recommended workflow: always run dry_run first, review the summary and conflicts, then execute. | Aksi |
| contentrain_scan | Scan project source code for content strings. Three modes: "graph" builds import/component graph for project intelligence, "candidates" extracts string literals with pre-filtering and pagination, "summary" provides quick overview stats. Read-only — no changes to disk or git. MCP finds strings deterministically; the agent decides what is content. Recommended workflow: start with "summary" or "graph" for orientation, then paginate through "candidates" to evaluate strings. | Hanya baca |
| contentrain_apply | Apply normalize operations. Two modes: "extract" writes agent-approved strings to Contentrain content files (source untouched), "reuse" patches source files with agent-provided replacement expressions. DRY RUN (default, dry_run:true): validates inputs, resolves conflicts, and returns a full preview — NO changes to disk or git. EXECUTE (dry_run:false): writes files to disk, commits to a branch, and requires branch health check to pass. Recommended workflow: always run dry_run first, review the preview, then call again with dry_run:false to execute. Normalize operations always use review workflow (never auto-merge). | Aksi |
| contentrain_bulk | Batch operations on content entries: copy a locale, or delete many collection entries. All operations are auto-committed to git. To publish or change status, use contentrain_content_status. DRY RUN (dry_run:true): runs the whole operation in a throwaway worktree and reports exactly what would change — nothing is committed and no branch survives. Recommended workflow: preview with dry_run:true, review the counts, then call again to execute. | Aksi |
| contentrain_doctor | Project health report (read-only). Returns structured checks: git, node, .contentrain/ structure, model parse, orphan content, branch pressure, SDK freshness. Pass `usage: true` for a deeper analysis of content-key references in source files (unused keys, duplicate dictionary values, locale coverage). Local-filesystem only — unavailable over remote providers. | Hanya baca |
Konfigurasi
CONTENTRAIN_PROJECT_ROOT
| Nama | Deskripsi | Tipe |
|---|---|---|
| CONTENTRAIN_PROJECT_ROOT | — |
Pengecekan otomatis
Berjalan 16 Nov 2026Laporan lengkap →Belum diverifikasi. Sebuah server memerlukan skor 80, tidak ada temuan serius, dan data yang cukup untuk kami periksa. Cara kerja checks · Yang perlu diperbaiki untuk menambah poin
- Source repository terhubung dan dapat dijangkaucontentrain/ai is public and reachablegithub.com/contentrain/ai ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernya@contentrain/mcp names contentrain/ai as sourcenpmjs.com/package/@contentrain/mcp ↗Lolos
- Provenance build (atestasi Sigstore)Sigstore attestation for @contentrain/mcpnpmjs.com/package/@contentrain/mcp/v/3.12.3#provenance ↗Lolos
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-11-07github.com/contentrain/ai ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerNo popular package one edit away from @contentrain/mcpLolos
- Tidak ada advisory kritis pada paket atau dependensinyaCritical advisory: GHSA-x6jw-m9v5-85vh, GHSA-v5rq-49vh-5v5cosv.dev/vulnerability/GHSA-x6jw-m9v5-85vh ↗Temuan
- Tidak ada instruksi tersembunyi untuk model23 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelNo tool named like delete, drop or execLolos
- Endpoint remote merespons handshake MCPHTTPS endpoint answered 401 (sign-in required)Lolos
README
Lihat di GitHub@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 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/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/{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_BRANCHenv →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
contentraintip: JSON changes are carried over key by key, so entries another writer pushed are kept; a same-value conflict writes nothing and returnsCONTENT_WORKING_TREE_STALE - on a checked-out feature branch, which writes do not update,
.contentrain/**is read from thecontentrainref instead (source files still from the working tree); read tools report it ascontent_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: falsein config.json - local mode (
git.push: falseorCONTENTRAIN_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
gitblock names the resolvedbase_branch; when it is not the checked-out branch, the result'swarningsays your working tree was left alone - commit hooks: skipped on machine commits by default;
git.verify: trueorCONTENTRAIN_VERIFY=1runs 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
contentrainbranch 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).
| 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 | — | Yes |
contentrain_model_delete |
Delete a model definition | — | Yes |
contentrain_content_save |
Save content entries for any model kind | — | Yes |
contentrain_content_delete |
Delete content entries | — | Yes |
contentrain_content_list |
Read content entries, each with its publish state under meta |
Yes | — |
contentrain_content_status |
Change entry status — publish, unpublish, archive (publishing validates first) | — | 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 | — | Yes |
contentrain_reconcile |
Content-aware three-way merge of a diverged contentrain ↔ base pair (dry_run first, resolutions second) | — | — |
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 and deletes (dry_run previews; local only) |
— | Yes |
contentrain_vocabulary_save |
Add or update canonical vocabulary terms (merges with what exists) | — | — |
contentrain_vocabulary_delete |
Remove canonical vocabulary terms by slug (confirm: true) |
— | Yes |
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 -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):
| Variable | Default | Effect |
|---|---|---|
CONTENTRAIN_BRANCH |
unset | Base branch the contentrain branch advances. Wins over repository.default_branch, then remote HEAD → main → master → the checked-out branch → main. Per process; never written to config |
CONTENTRAIN_REMOTE |
origin |
Remote used for every fetch and push (and remote branch cleanup) |
CONTENTRAIN_NO_PUSH |
unset | 1/true turns local mode on; 0/false turns it off. Any other value is ignored |
CONTENTRAIN_AUTHOR_NAME / CONTENTRAIN_AUTHOR_EMAIL |
Contentrain / ai@contentrain.io |
Author identity on Contentrain's commits |
CONTENTRAIN_GIT_BINARY |
unset | Absolute path of the git binary to use |
CONTENTRAIN_VERIFY |
unset | 1/true runs the repository's commit hooks on Contentrain's commits; 0/false skips them. Wins over git.verify. Any other value is ignored |
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 existing projects working: these commits are made in a temporary worktree without your node_modules, and their [contentrain] … subject fails a strict commitlint. Merges still run the merge hooks and pushes still run pre-push, as before.
To run commit hooks on every machine commit, set "git": { "verify": true } in .contentrain/config.json, or CONTENTRAIN_VERIFY=1 for one run (CONTENTRAIN_VERIFY=0 skips them over the config). With hooks on:
- a hook that rejects the content commit fails the write: nothing lands, and the tool error carries the hook's output. Nothing is retried without hooks;
- a hook that rejects only the follow-up
context.jsoncommit (the content is already oncontentrain) is reported in the result'swarning, not swallowed; - the hooks must work in a worktree under the system temp directory — a hook that runs
npx lint-stagedneeds the tool available there.
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 defaultInstructions for the tools the server registers — with every tool available, DEFAULT_INSTRUCTIONS — kept under 512 characters; pass '' to omit). The HTTP entries (startHttpMcpServer, startHttpMcpServerWith) take the same instructions option.
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/{timestamp}-{suffix})
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 or domain}/{timestamp}-{suffix})
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, so a server built on one does not register contentrain_scan or contentrain_apply at all (see TOOL_REQUIREMENTS). A provider that can read the source tree but not write it lists contentrain_apply; its reuse mode then 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 core tool (normalize included) works on it; the media tools need a provider with a media facet. 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. The GitHub provider also takes a full commit SHA as applyPlan's base (and createBranch's fromRef) for compare-and-set writes: a missing branch forks from that commit, and a branch that has moved away from it refuses the write with PROVIDER_CONFLICT.
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) is not registered on a GitLabProvider server — fall back to a local transport for those flows.
Bitbucket
There is no Bitbucket provider. A Bitbucket checkout works through the LocalProvider path like any other local Git repository.
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 (includingplanReconcileand itsbindRefreader adapter) plus content-root-relative path helpers:contentDirPath,contentFilePath,documentFilePath,metaFilePath@contentrain/mcp/core/overlay-reader@contentrain/mcp/core/migration— the allowlisted migration write path:createMigrationWriter,scopeHash,decide. See Migration writes below@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/git/base-branch—resolveBaseBranch, the one base-branch resolver every MCP write andcontentrain status/serveuse (env →repository.default_branch→<remote>/HEAD→main→master→ checked-out branch →main);resolveBaseBranchSource(the same, plus which rung answered);resolveInitDefaultBranch(whatinitrecords asrepository.default_branch, ornull)@contentrain/mcp/git/errors@contentrain/mcp/git/reconcile—reconcileBranches, the local reconcile executor@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.
Migration Writes
A migration does not deliver content, it delivers a codebase: src/, public/,
package.json, a lockfile, deploy configuration. The content write path was
never built for any of that, and widening it would quietly move a security
boundary the whole product rests on — "Contentrain only writes .contentrain/"
is a promise, not an implementation detail.
@contentrain/mcp/core/migration is the gate instead. It wraps a provider whose
applyPlan can already write any path, and puts consent in front of it.
import { createMigrationWriter, scopeHash } from '@contentrain/mcp/core/migration'
const scope = {
allow: ['src/**', 'public/**', 'package.json', 'astro.config.mjs'],
branch: 'migration/acme',
base: 'main',
}
// Show the user `scope`, not the hash. Then bind their consent to it:
const approval = {
scope_hash: await scopeHash(scope),
approver: { kind: 'human', id: userId, role: 'owner' },
approved_at: new Date().toISOString(),
}
const writer = createMigrationWriter(provider, scope, approval)
await writer.applyPlan({ ...plan, step: 'emit', actor })
writer.audit // which file, in which step, by which actor, in which commit
What it guarantees:
| Scope | Only paths an allowlist pattern covers. .contentrain/** is not implicit — a migration that wants the store asks for it, and the person approving sees that it does |
| Consent | One approval, bound to the exact scope by scope_hash. An approval of src/** cannot be replayed against a scope that also has .github/workflows/** |
| Branch | A migration/* ref. The contentrain branch is never a target and never a base — including through ApplyPlanInput's default, which a migration must not inherit |
| Trail | One MigrationAuditEntry per file: step, path, action, the pattern that allowed it, actor, timestamp, commit |
| Undo | One branch, delivered as one PR, revertable with one git revert |
Every refusal happens before the provider is called, and a plan is refused whole: a plan with one path outside the scope writes nothing at all, not even its allowed part. A half-applied migration is harder to recover from than one that never started.
The path matcher is a security control and is written to fail closed. Traversal,
absolute paths, backslash separators, percent-encoding, empty segments and
control characters are refused before any pattern is consulted; patterns are
anchored at both ends, so src/* does not cover src/a/b and nothing matches
by being a prefix; and regex metacharacters in a pattern are literal, so an
allowlist entry cannot silently cover more than it reads.
Design Constraints
Key design decisions in this package:
- local-first by default — stdio transport + LocalProvider works without any network dependency
- provider-agnostic engine — the core tools run over LocalProvider, GitHubProvider, or GitLabProvider behind a single
RepoProvidercontract (remote providers get the remote-safe subset); 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 a local checkout or source-tree access (scan, apply, doctor, init, scaffold, bulk, submit, merge, reconcile, branch tools) are not registered on remote providers;
TOOL_REQUIREMENTSis the map
Pertanyaan tentang Contentrain MCP
Bagaimana cara menambahkan Contentrain MCP ke Claude Code?
Jalankan claude mcp add contentrain -- npx -y @contentrain/mcp di terminal Anda. Tambahkan --scope user agar tersedia di semua proyek.
Bagaimana cara menambahkan Contentrain MCP ke Cursor?
Buka ~/.cursor/mcp.json dan tambahkan server di bawah mcpServers, menggunakan config Cursor yang ditunjukkan di bagian instalasi di atas.
Tool apa yang disediakan Contentrain MCP?
Server ini menyediakan 23 tool, termasuk contentrain_status, contentrain_describe, contentrain_describe_format, contentrain_init, contentrain_scaffold.
Bagaimana Contentrain memastikan keamanan penulisan (write safety)?
Semua operasi penulisan menggunakan model keamanan berbasis git di mana setiap penulisan membuat worktree sementara pada feature branch khusus.