Contentrain MCP
Official<p align="center"><img src=".github/cover.png" alt="Contentrain — content governance for teams and AI agents" width="100%"></p>
# Contentrain AI
[](https://www.npmjs.com/package/@contentrain/mcp)
[](https://www.npmjs.com/package/contentrain)
[](https://www.npmjs.com/package/@contentrain/query)
[](https://agentskills.io)
[](https://ai.contentrain.io)
[](LICENSE)
[Website](https://contentrain.io) · [Docs](https://ai.contentrain.io) · [Discord](https://discord.gg/8XbFKfgeZx) · [Twitter](https://x.com/Contentrain_io) · [LinkedIn](https://www.linkedin.com/company/contentrain)
**Extract, govern, and ship structured content from your codebase.**
Contentrain is a content governance ecosystem for teams and AI agents. Agent generates. Human approves. Git records every change.
This repository holds its open-source tools (MIT, no account needed): the MCP engine, CLI, query SDK, rules, skills and types, plus the open packages of the WordPress migration pipeline (wp-import, emitter-astro, verify, astro-kit, decide). They help teams turn hardcoded UI text, docs, and structured content into a governed, reviewable content layer that lives in Git as structured JSON and Markdown. Agents can extract, create, translate, and update content, while Contentrain enforces schema, Git review, and portable file output.
```
Agent extracts or updates content → Contentrain standardizes → Human reviews → Any platform consumes
```
## Try it in 30 seconds
```bash
npx contentrain init # create .contentrain/ workspace
npx contentrain serve # open the local review UI
```
That's it. You now have a governed content workspace with models, validation, review branches, and a local UI — no account, no cloud, no proprietary content format.
Start here:
- [See the 2-minute demo](https://ai.contentrain.io/demo)
- [Open the normalize guide](https://ai.contentrain.io/guides/normalize)
- [Read the docs](https://ai.contentrain.io)
## What Contentrain is for
- **Rescuing hardcoded strings** from existing apps and turning them into structured, translatable content
- **Starting new projects with a real content layer** instead of scattering copy across components
- **Serving the same content across web, docs, mobile, and backend systems** from plain JSON and Markdown in Git
## What it is not
- Not an AI writing app
- Not a database-first or dashboard-first CMS replacement for every team
- Not a proprietary content runtime that locks your app to one platform
## What it looks like
**Before:** Hardcoded strings scattered across your codebase — no structure, no translations, no review.
```tsx
export default function Hero() {
return (
<section>
<h1>Welcome to our platform</h1>
<p>Start your free trial today</p>
<button>Get Started</button>
</section>
)
}
```
**After:** Content lives in `.contentrain/`, typed and structured. Source files use i18n keys.
```tsx
export default function Hero() {
const t = useTranslations()
return (
<section>
<h1>{t('hero.title')}</h1>
<p>{t('hero.subtitle')}</p>
<button>{t('hero.cta')}</button>
</section>
)
}
```
```json
// .contentrain/content/marketing/hero/en.json
{
"cta": "Get Started",
"subtitle": "Start your free trial today",
"title": "Welcome to our platform"
}
```
The normalize flow extracts strings, creates models, and patches your source files — all through reviewable git branches.
This is the strongest entry point into the product:
**take the content chaos already in your codebase and turn it into a governed, reviewable content layer.**
## How it works
```
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ AI Agent │────▶│ MCP (23 tools) │────▶│ .contentrain/│
│ (decides) │ │ (enforces) │ │ (stores) │
└─────────────┘ └──────────────────┘ └──────┬───────┘
│
┌──────────────────┐ │
│ Review UI / Git │◀─────────────┘
│ (human approves)│
└──────────────────┘
```
- **Agent** decides what content should exist and where it should come from
- **Contentrain** enforces schemas, validation, canonical serialization, and git workflow
- **Human** reviews through branches, PRs, or the local Serve UI
- **Output** is plain JSON + Markdown that any language or framework can consume
## 4 content kinds
| Kind | What it stores | Storage | Example |
|---|---|---|---|
| **Collection** | Multiple typed entries | JSON object-map | Blog posts, products, team |
| **Singleton** | Single entry per locale | JSON object | Hero section, site config |
| **Document** | Markdown + frontmatter | `.md` files | Docs, articles, changelog |
| **Dictionary** | Flat key-value strings | JSON flat map | i18n translations, UI labels |
27 field types (string, email, url, image, relation, array, object, markdown, ...) with built-in validation.
## Use your content anywhere
Content is plain JSON and Markdown. Any language reads it directly.
For TypeScript projects, generate a typed SDK:
```bash
npx contentrain generate
```
```ts
import { query, singleton, dictionary, document } from '#contentrain'
const hero = singleton('hero').locale('en').get()
const posts = query('blog-post').locale('en').include('author').all()
const labels = dictionary('ui-labels').locale('tr').get('auth.login')
const article = document('docs').locale('en').bySlug('getting-started')
```
Works with Nuxt, Next.js, Astro, SvelteKit, Vue, React, Node, Go, Python, Flutter, and 20+ stacks.
## Why teams use it
- **Git-native** — every write goes through worktree isolation + review branches
- **Normalize flow** — scan codebase for hardcoded strings → extract → create i18n-ready content → patch source files
- **MCP engine** — 23 tools (5 more for media on a media-capable provider such as Studio) over stdio or HTTP transport, works with Claude Code, Cursor, Windsurf, or any MCP client
- **Provider-agnostic engine** — the same tool surface runs over a local worktree, GitHub, or GitLab (self-hosted included) with zero tool-code changes. HTTP transport available for remote drivers such as Studio.
- **Canonical serialization** — sorted keys, deterministic output, clean git diffs, conflict-free parallel edits
- **Agent rules & skills** — behavioral policies and step-by-step workflows ship as npm packages
- **Serve UI** — local web dashboard for browsing models, content, validation, and normalize status
- **Framework-agnostic** — MCP doesn't know your framework. Agent + skills handle stack-specific logic
## Agent Skills
This repo ships 16 [Agent Skills](https://agentskills.io) — reusable workflow procedures that any AI coding agent can load on demand.
Install all skills to your agent:
```bash
npx skills add Contentrain/ai/packages/skills
```
Or install a specific skill:
```bash
npx skills add Contentrain/ai/packages/skills --skill contentrain-normalize
```
Skills work with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Gemini CLI, and 40+ other agents.
See [`AGENTS.md`](AGENTS.md) for the full skill catalog and agent guidance.
## Packages
| Package | npm | Role |
|---|---|---|
| [`@contentrain/mcp`](packages/mcp) | [](https://www.npmjs.com/package/@contentrain/mcp) | 23 MCP tools + stdio / HTTP transport + Local / GitHub / GitLab providers |
| [`contentrain`](packages/cli) | [](https://www.npmjs.com/package/contentrain) | CLI + Serve UI + MCP stdio entrypoint |
| [`@contentrain/query`](packages/sdk/js) | [](https://www.npmjs.com/package/@contentrain/query) | Generated TypeScript query SDK |
| [`@contentrain/types`](packages/types) | [](https://www.npmjs.com/package/@contentrain/types) | Shared type definitions + constants |
| [`@contentrain/rules`](packages/rules) | [](https://www.npmjs.com/package/@contentrain/rules) | Agent quality rules for IDE integration |
| [`@contentrain/skills`](packages/skills) | [](https://www.npmjs.com/package/@contentrain/skills) | Workflow procedures + framework guides |
| [`@contentrain/wp-import`](packages/wp-import) | [](https://www.npmjs.com/package/@contentrain/wp-import) | WordPress WXR / REST → `RawIR` → `.contentrain` store |
| [`@contentrain/emitter-astro`](packages/emitter-astro) | [](https://www.npmjs.com/package/@contentrain/emitter-astro) | `ProjectIR` → a complete Astro project |
| [`@contentrain/verify`](packages/verify) | [](https://www.npmjs.com/package/@contentrain/verify) | SEO, indexing, link and asset gates for a built site |
| [`@contentrain/astro-kit`](packages/astro-kit) | [](https://www.npmjs.com/package/@contentrain/astro-kit) | Copy-in Astro components + catalog + builder mapping tables |
| [`@contentrain/decide`](packages/decide) | [](https://www.npmjs.com/package/@contentrain/decide) | Typed decisions — rule first, then Jev, then Claude Haiku — cached, budgeted, audited |
## Starter Templates
Production-ready templates with Contentrain content models, generated SDK client, and framework-specific patterns:
| Template | Framework | Use Case |
|---|---|---|
| [astro-blog](https://github.com/Contentrain/contentrain-starter-astro-blog) | Astro | Blog / editorial |
| [astro-landing](https://github.com/Contentrain/contentrain-starter-astro-landing) | Astro | Landing page |
| [next-commerce](https://github.com/Contentrain/contentrain-starter-next-commerce) | Next.js | E-commerce storytelling |
| [next-multi-surface-saas](https://github.com/Contentrain/contentrain-starter-next-multi-surface-saas) | Next.js | Marketing + app + docs unified |
| [next-saas-dashboard](https://github.com/Contentrain/contentrain-starter-next-saas-dashboard) | Next.js | SaaS dashboard UI copy |
| [next-white-label-portal](https://github.com/Contentrain/contentrain-starter-next-white-label-portal) | Next.js | White-label / multi-tenant |
| [nuxt-admin-console](https://github.com/Contentrain/contentrain-starter-nuxt-admin-console) | Nuxt | Admin console / operations |
| [nuxt-saas](https://github.com/Contentrain/contentrain-starter-nuxt-saas) | Nuxt | SaaS marketing site |
| [sveltekit-editorial](https://github.com/Contentrain/contentrain-starter-sveltekit-editorial) | SvelteKit | Editorial / publication |
| [vitepress-docs](https://github.com/Contentrain/contentrain-starter-vitepress-docs) | VitePress | Documentation site |
Each template is a GitHub template repo — click "Use this template" to start.
[`templates/astro-starter`](templates/astro-starter) lives in this repository: the base a WordPress migration starts from — posts, pages, archives and permalinks, SEO, RSS, sitemap, search, Studio forms and comments, Gutenberg block styles — and it passes its own gates (`astro check`, knip, build + Pagefind, built-site checks) with no content. `node scripts/starter-gates.mjs` runs them on a standalone copy; CI runs them with the SDK at HEAD, empty and with the fixtures in `templates/fixtures/` (`wp-demo` and others). The starter's own CI, which a delivered site keeps, adds Lighthouse.
## Quick reference
```bash
npx contentrain init # initialize project
npx contentrain setup # configure the MCP server and rules for your IDE
npx contentrain import <wxr-or-url> # import a WordPress site into .contentrain
npx contentrain serve # local review UI (port 3333)
npx contentrain serve --stdio # MCP over stdio for IDE agents
npx contentrain validate # check content health
npx contentrain generate # generate typed SDK client
npx contentrain status # project overview
npx contentrain doctor # setup health check
npx contentrain reconcile # merge a diverged base branch, content-aware
npx contentrain studio login # authenticate with Studio
npx contentrain studio connect # connect repo to Studio project
```
## Documentation
- **[2-Minute Demo](https://ai.contentrain.io/demo)** — the fastest way to understand the product
- **[Getting Started](https://ai.contentrain.io/getting-started)** — install, connect an agent, and run the first workflow
- **[Normalize Guide](https://ai.contentrain.io/guides/normalize)** — the main hardcoded-string rescue flow
- **[Ecosystem Map](https://ai.contentrain.io/ecosystem)** — package-to-product bridges across AI and Studio
- **[Contentrain Studio](https://ai.contentrain.io/studio)** — open-core team operations for Git-native structured content, self-hostable or available as managed plans (Starter/Pro/Enterprise)
- **[Full Docs](https://ai.contentrain.io)** — guides, package reference, and framework integration
## The Contentrain ecosystem
Contentrain has four parts. This repository is the first.
| Part | What it does | License |
|---|---|---|
| **Open-source tools** ([Contentrain/ai](https://github.com/Contentrain/ai), [docs](https://ai.contentrain.io)) | MCP engine, CLI, query SDK, normalize flow, rules, skills and types, plus the open WordPress migration packages. Developers and agents pull content out of code and structure it in their own repository. | MIT |
| **Studio** ([Contentrain/studio](https://github.com/Contentrain/studio), [studio.contentrain.io](https://studio.contentrain.io)) | The team operating surface for governed content: structured editing, review, roles and Git-backed operations. Media, CDN delivery, APIs and remote MCP ([MCP Cloud](https://docs.contentrain.io/developer/mcp-cloud)) depend on plan and deployment. Managed plans or self-hosted. | AGPL-3.0 core, separately licensed `ee/` |
| **Migrate** ([migrate.contentrain.io](https://migrate.contentrain.io)) | A paid service that moves WordPress sites to Astro, with their content and template structure. | Hosted service |
| **Bridge** ([Contentrain/wordpress-bridge](https://github.com/Contentrain/wordpress-bridge), [WordPress.org](https://wordpress.org/plugins/contentrain-bridge/)) | A free WordPress plugin that exports posts, pages, custom fields and interface text as a validated Contentrain store (JSON + Markdown), as a ZIP or to your own GitHub repository. | GPL-2.0-or-later |
## Development
```bash
pnpm install && pnpm build && pnpm test
pnpm lint # oxlint, warnings treated as errors
pnpm docs:check # the docs must not state a number the code disagrees with
```
`pnpm docs:check` runs three checks, all needing `pnpm build` first:
- **facts** — resolves counts (MCP tools, skills, field types, capability keys)
from the packages that own them and compares every place the docs, this
README and `AGENTS.md` state one.
- **examples** — every `@contentrain/*` import in a documented example must
name a real export, and no example may mix CommonJS with a top-level `await`
(a shape that runs in no module system at all).
- **server.json** — `packages/mcp/server.json` (the MCP Registry manifest)
must name the current `@contentrain/mcp` version.
The facts and examples checks self-test against real defects from this repo's history before they run,
so a check that stops catching fails loudly instead of passing silently.
See [`RELEASING.md`](RELEASING.md) for the versioning and publish workflow.
## Community
- [Discord](https://discord.gg/8XbFKfgeZx) — chat with the team and community
- [GitHub Discussions](https://github.com/Contentrain/ai/discussions) — questions and ideas
- [Twitter / X](https://x.com/Contentrain_io) — product updates and announcements
- [LinkedIn](https://www.linkedin.com/company/contentrain) — company news
- [YouTube](https://www.youtube.com/@contentrain) — tutorials and demos
- [GitHub Issues](https://github.com/Contentrain/ai/issues) — bug reports and feature requests
If Contentrain AI is useful to you, consider giving it a star — it helps others discover the project.
## License
MIT
TDQS
Scored across 23 tools
Most tools target clearly distinct resources and actions (model vs content vs vocabulary vs branch), and descriptions clarify adjacent operations like merge (cr/* branch into contentrain) vs reconcile (diverged contentrain ↔ base three-way merge). A few pairs are mildly confusable: contentrain_status vs contentrain_doctor (project state vs health checks), contentrain_describe vs contentrain_describe_format (model schema vs file-format spec), and contentrain_bulk vs contentrain_content_delete (bulk delete overlaps single delete, though a cross-reference notes status changes belong elsewhere).
All tools share a contentrain_ prefix and snake_case convention, and most follow a resource_action pattern (content_save, model_delete, branch_list, vocabulary_delete). A few deviate to bare verbs or nouns (init, scaffold, status, doctor, describe, apply), but the prefix and casing keep the set readable and predictable.
At 23 tools the surface is on the heavy side, but the domain is genuinely broad—modeling, content lifecycle, vocabulary, git branch workflow, validation, scanning, and scaffolding—and each tool covers a distinct operation. Nothing looks redundant enough to trim, though a couple of read-only helpers could be consolidated.
Coverage is strong: init/scaffold, model save/delete (with describe and status exposing models), full content save/list/delete/status plus bulk, vocabulary save/delete, validation, scan/apply, and a complete branch lifecycle (submit/merge/reconcile/branch_list/branch_delete). Minor gaps exist—no explicit model_list or vocabulary_list—but these are workable via contentrain_status and describe.