AI Integration

Contentrain provides first-class AI integration that enables AI coding assistants to manage your CMS content directly from your development environment. Using the Contentrain AI toolkit, tools like Claude Code and Cursor can create models, write content, manage assets, and run diagnostics — all without leaving your IDE.

How It Works

The Contentrain AI integration operates in two modes:

MCP Mode (Recommended)

When the @contentrain/mcp server is installed, AI agents use the MCP (Model Context Protocol) tools for full-featured content management:

• Automatic Git worktree isolation for safe concurrent writes
• Auto-commit and push to the target environment branch
• Structural 3-way merge for conflict resolution
• Schema validation before every write
• 17 specialized tools for models, content, assets, and diagnostics

Direct File Editing (Fallback)

When the MCP server is not available, AI agents fall back to editing Contentrain files directly using strict validation rules. This mode provides the same data integrity guarantees but without automatic Git operations.

Setup

Claude Code

The fastest way to get started is with the Contentrain AI plugin:

# Install the plugin
claude plugin add /path/to/contentrain-ai

# Or install the MCP server globally
npm install -g @contentrain/mcp

This gives you:

• Auto-invoked skill — Automatically activates when your project has a contentrain/ directory
• /contentrain slash command — User-invoked command for content operations
• MCP integration — Full Git-synced operations when the MCP server is installed

Manual Setup (Claude Code)

If you prefer manual configuration, copy the slash command:

cp commands/contentrain.md ~/.claude/commands/contentrain.md

Cursor

Copy the Cursor rule to enable AI-assisted Contentrain management:

# Project-level
mkdir -p .cursor/rules
cp cursor/contentrain.mdc .cursor/rules/contentrain.mdc

# Or globally
mkdir -p ~/.cursor/rules
cp cursor/contentrain.mdc ~/.cursor/rules/contentrain.mdc

The Cursor rule auto-activates when editing files in the contentrain/ directory.

MCP Server Configuration

After installing the MCP server (npm install -g @contentrain/mcp), configure your tool:

Claude Code — Add .mcp.json to your project root:

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": ".",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    }
  }
}

Cursor — Add .cursor/mcp.json:

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": ".",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    }
  }
}

For detailed MCP server configuration and the complete tools reference, see the MCP Server documentation.

What AI Agents Can Do

Once configured, your AI assistant can perform the following operations:

Model Management

• Create models — Design content model schemas with field definitions, specifying type (JSON, MD, MDX) and localization settings
• Add fields — Add new fields to existing models with the correct component type, data type, validations, and options
• Inspect models — View complete model schemas to understand field requirements before creating content
• Delete models — Remove models and all associated content

Content Operations

• Create entries — Add new content with full schema validation, automatic ID generation, and timestamp management
• Update entries — Modify specific fields without affecting other data
• Delete entries — Remove entries across all locales and associated markdown files
• Publish/draft — Change content status between draft and publish
• Multi-language — Create and manage content in multiple languages with consistent IDs across locales

Asset Management

• Register assets — Add uploaded files to the asset registry with MIME type and alt text
• List assets — View all registered assets with metadata
• Deregister assets — Remove assets from the registry

Diagnostics

• Health checks — Scan all models, content, and assets for data quality issues
• Auto-repair — Fix common problems like duplicate IDs, missing timestamps, and invalid status values
• Staged fixes — Review diagnostic fixes on a staging branch before applying

Example Workflows

Creating a Blog Model

You: "Create a blog model with title, excerpt, cover image, author,
      and published date fields. Enable localization."

AI: Creates the model with correct field types:
    - title → single-line-text (string)
    - excerpt → multi-line-text (string)
    - cover-image → media (string)
    - author → one-to-one relation (string)
    - published-date → date (string)
    - Localization enabled, system fields auto-added

Adding Multi-Language Content

You: "Add a new blog post titled 'Getting Started' in English and Turkish"

AI: Creates the entry with the same ID in both en.json and tr.json,
    with appropriate translations for each field.

Running Diagnostics

You: "Check the project for any content issues"

AI: Runs contentrain_doctor, reports findings:
    - 2 broken relation references
    - 1 duplicate ID
    - 3 missing asset paths
    Offers to auto-fix with staged review.

Bulk Content Updates

You: "List all FAQ entries and change their status to publish"

AI: Lists entries with contentrain_list_content,
    updates each with contentrain_update_content,
    all within a single Git transaction.

Data Validation Rules

The AI integration enforces the same validation rules as the Contentrain Web App:

Rule	Description
ID format	12-character lowercase hexadecimal ([a-f0-9]{12})
Required fields	All required fields must have a value
Unique fields	Values marked as unique cannot be duplicated within a model
Type matching	Values must match the expected data type for the field component
Relation integrity	Referenced entries must exist in the target model
Asset existence	Media field paths must reference registered assets
Locale consistency	Localized entries must share the same ID across all language files
Immutable fields	ID and createdAt cannot be modified after creation

Skill Activation

The Contentrain AI skill automatically activates when:

• Your project contains a contentrain/ directory
• You ask to create, edit, or delete models, content, or assets
• You reference contentrain/ files in your conversation
• Any content management task in a Contentrain-enabled project

The skill does not activate for general programming tasks unrelated to Contentrain.

Resources

• AI Toolkit: github.com/Contentrain/ai
• MCP Server: github.com/Contentrain/mcp
• MCP Server Docs: MCP Server
• License: MIT