@contentrain/mcp 0.3.1 → 1.0.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Contentrain
+Copyright (c) 2026 Contentrain
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,282 +1,198 @@
-# @contentrain/mcp
+# `@contentrain/mcp`
 
-MCP (Model Context Protocol) server for [Contentrain](https://contentrain.io) CMS content management. Enables AI agents (Claude, Codex, Cursor, etc.) and humans to create, read, update, and delete Contentrain models, content, and assets — with automatic git branch synchronization.
+[![npm version](https://img.shields.io/npm/v/%40contentrain%2Fmcp?label=%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp)
+[![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/mcp)
 
-## Why?
+Local-first MCP server and core primitives for Contentrain.
 
-Contentrain is a git-based headless CMS. This MCP server lets AI assistants directly manage your Contentrain content through a standardized protocol, so you can say things like:
+Contentrain is AI-generated content governance infrastructure:
 
-- *"Create a blog post model with title, excerpt, and cover image fields"*
-- *"Add a new blog post in English and Turkish"*
-- *"List all FAQ entries and update the second one"*
+- agent produces content decisions
+- MCP applies deterministic filesystem and git workflow
+- humans review and merge
+- the system keeps schema, locale, and serialization consistent
 
-All changes are committed and pushed to your git repository automatically.
+This package is the runtime core behind Contentrain's MCP integration. It can be used as:
 
-## Prerequisites
+- 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
 
-- A Contentrain project already set up via the [Contentrain Web App](https://app.contentrain.io)
-- The project's GitHub repository cloned locally
-- Node.js >= 18
+## 🚀 Install
 
-> **Important:** Contentrain projects must be initialized through the Web App first. The Web App creates the repository structure, the `contentrain` branch, models, and environment configuration. This MCP server operates on an existing Contentrain project — it does not replace the initial setup.
+```bash
+pnpm add @contentrain/mcp
+```
 
-## Quick Start
+Requirements:
 
-### 1. Install
+- Node.js `22+`
+- git available on the machine
 
-```bash
-# From npm (when published)
-npm install -g @contentrain/mcp
+Optional parser support for higher-quality source scanning:
 
-# Or from source
-git clone https://github.com/Contentrain/contentrain-mcp.git
-cd contentrain-mcp
-pnpm install && pnpm build
-```
+- `@vue/compiler-sfc`
+- `@astrojs/compiler`
+- `svelte`
 
-### 2. Configure your MCP client
+They are listed as optional dependencies. The scanner still works without them, but Vue/Astro/Svelte detection is stronger when they are installed.
 
-Add to your MCP client configuration:
+## ✨ What It Does
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+`@contentrain/mcp` manages a `.contentrain/` directory in your project and exposes MCP tools for:
 
-```json
-{
-  "mcpServers": {
-    "contentrain": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
-        "CONTENTRAIN_BRANCH": "contentrain"
-      }
-    }
-  }
-}
-```
+- project initialization
+- model creation and deletion
+- content save, delete, and list
+- validation and auto-fix
+- normalize scan and apply flows
+- bulk operations
+- branch submission and branch-health awareness
 
-**Cursor** (`.cursor/mcp.json` in your project root):
-
-```json
-{
-  "mcpServers": {
-    "contentrain": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
-        "CONTENTRAIN_BRANCH": "contentrain"
-      }
-    }
-  }
-}
-```
+All write operations are designed around git-backed safety:
 
-**Claude Code** (`.mcp.json` in your project root):
-
-```json
-{
-  "mcpServers": {
-    "contentrain": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
-        "CONTENTRAIN_BRANCH": "contentrain"
-      }
-    }
-  }
-}
-```
+- write to a dedicated `contentrain/*` branch
+- keep canonical JSON output
+- update `.contentrain/context.json`
+- surface validation and next-step hints to the caller
+
+## 🧰 Tool Surface
 
-> If installed from source instead of globally, replace `"command": "contentrain-mcp"` with `"command": "node"` and add `"args": ["/absolute/path/to/contentrain-mcp/dist/index.mjs"]`.
+Current MCP tools exposed by the server:
 
-### 3. Start using
+| Tool | Purpose |
+| --- | --- |
+| `contentrain_status` | Project status, config, models, branch health, context |
+| `contentrain_describe` | Full schema and sample data for a model |
+| `contentrain_describe_format` | File-format and storage contract reference |
+| `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 |
+| `contentrain_content_save` | Save content entries for any model kind |
+| `contentrain_content_delete` | Delete content entries |
+| `contentrain_content_list` | Read content entries |
+| `contentrain_validate` | Validate project content, optionally auto-fix structural issues |
+| `contentrain_submit` | Push `contentrain/*` branches to remote |
+| `contentrain_scan` | Graph- and candidate-based hardcoded string scan |
+| `contentrain_apply` | Normalize extract/reuse execution with dry-run support |
+| `contentrain_bulk` | Bulk locale copy, status updates, and deletes |
 
-Once configured, your AI assistant has access to 17 tools. Here's an example conversation:
+## 🚀 Quick Start
 
+### Run as an MCP server
+
+```bash
+CONTENTRAIN_PROJECT_ROOT=/path/to/project npx contentrain-mcp
 ```
-You:    List all my models
-Agent:  → calls contentrain_list_models
-        You have 3 models: blog (MD, localized), faq (JSON), authors (JSON)
-
-You:    Show me the blog model schema
-Agent:  → calls contentrain_describe_model { modelId: "blog" }
-        Blog model has fields: title (string, required), description (string),
-        category (one-to-one → blogcategories), imagesrc (media), author (one-to-one → authors)
-
-You:    Create a new blog post titled "Getting Started with Contentrain"
-Agent:  → calls contentrain_create_content {
-            modelId: "blog",
-            data: { title: "Getting Started with Contentrain", slug: "getting-started-with-contentrain", description: "..." },
-            locale: "en",
-            status: "draft",
-            content: "# Getting Started\n\nWelcome to Contentrain..."
-          }
-        Created entry e7f3a1b9c0d2 in blog model (draft).
-        Committed and pushed to contentrain branch.
-
-You:    Now publish it
-Agent:  → calls contentrain_update_content {
-            modelId: "blog",
-            entryId: "e7f3a1b9c0d2",
-            data: { status: "publish" },
-            locale: "en"
-          }
-        Updated and published.
+
+If `CONTENTRAIN_PROJECT_ROOT` is omitted, the current working directory is used.
+
+### Embed the server in your own process
+
+```ts
+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)
 ```
 
-## Environments
+## 🔄 Example MCP Flow
 
-Contentrain uses **git branches** to manage environments. Each environment maps to a branch:
+Typical agent workflow:
 
-| Environment | Branch | Description |
-|-------------|--------|-------------|
-| Default | `contentrain` | Main content branch (created automatically) |
-| Staging | `contentrain-staging` | Preview/staging environment |
-| Production | `contentrain-production` | Production environment |
+1. Call `contentrain_status`
+2. If needed, call `contentrain_init`
+3. Create models with `contentrain_model_save` or `contentrain_scaffold`
+4. Save content with `contentrain_content_save`
+5. Validate with `contentrain_validate`
+6. For hardcoded strings, use `contentrain_scan` then `contentrain_apply`
+7. Push review branches with `contentrain_submit`
 
-Environments are created via the Contentrain Web App. The branch naming follows the pattern `contentrain-{environment-name}`.
+## 🧪 Normalize Flow
 
-### Targeting a specific environment
+Normalize is intentionally split into two phases:
 
-Set the `CONTENTRAIN_BRANCH` environment variable to the target environment's branch:
+### 1. Extract
 
-```json
-{
-  "mcpServers": {
-    "contentrain": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/project",
-        "CONTENTRAIN_BRANCH": "contentrain-staging"
-      }
-    }
-  }
-}
-```
+`contentrain_scan` finds candidate strings.
 
-### Multiple environments simultaneously
-
-You can register multiple MCP server instances — one per environment:
-
-```json
-{
-  "mcpServers": {
-    "contentrain-default": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/project",
-        "CONTENTRAIN_BRANCH": "contentrain"
-      }
-    },
-    "contentrain-staging": {
-      "command": "contentrain-mcp",
-      "env": {
-        "CONTENTRAIN_REPO_PATH": "/path/to/project",
-        "CONTENTRAIN_BRANCH": "contentrain-staging"
-      }
-    }
-  }
-}
-```
+`contentrain_apply` with `mode: "extract"`:
 
-## Available Tools
-
-### Model Management
-
-| Tool | Description |
-|------|-------------|
-| `contentrain_list_models` | List all models with metadata |
-| `contentrain_describe_model` | Get full schema with field definitions |
-| `contentrain_create_model` | Create a new model (JSON, MD, or MDX) |
-| `contentrain_add_field` | Add a field to an existing model |
-| `contentrain_delete_model` | Delete a model and all its content |
-
-### Content Management
-
-| Tool | Description |
-|------|-------------|
-| `contentrain_list_content` | List all entries for a model |
-| `contentrain_get_content` | Get a single entry by ID |
-| `contentrain_create_content` | Create a new entry with validation |
-| `contentrain_update_content` | Update specific fields of an entry |
-| `contentrain_delete_content` | Delete an entry (all locales + markdown) |
-| `contentrain_validate` | Dry-run validation against model schema |
-
-### Asset Management
-
-| Tool | Description |
-|------|-------------|
-| `contentrain_list_assets` | List all registered assets |
-| `contentrain_register_asset` | Register an existing file as an asset |
-| `contentrain_deregister_asset` | Remove an asset from the registry |
-
-### Diagnostics
-
-| Tool | Description |
-|------|-------------|
-| `contentrain_doctor` | Full diagnostic scan — detects ID, schema, relation, asset, and sync issues. Use `fix=true` to auto-repair (pushes to a staging branch for review). |
-| `contentrain_doctor_apply` | Merge a staged doctor fix into the target branch |
-| `contentrain_doctor_discard` | Discard a staged doctor fix without merging |
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CONTENTRAIN_REPO_PATH` | `process.cwd()` | Path to the git repository |
-| `CONTENTRAIN_BRANCH` | `contentrain` | Target environment branch |
-| `CONTENTRAIN_REMOTE` | `origin` | Git remote name |
-| `CONTENTRAIN_DIR` | `contentrain` | Contentrain directory name |
-| `CONTENTRAIN_DRY_RUN` | `false` | Skip git operations (local changes only) |
-| `CONTENTRAIN_AUTHOR_NAME` | — | Git commit author name |
-| `CONTENTRAIN_AUTHOR_EMAIL` | — | Git commit author email |
-
-## Programmatic Usage
-
-You can also use the writer directly in your own code:
-
-```typescript
-import { ContentrainWriter } from '@contentrain/mcp'
-
-const writer = new ContentrainWriter({
-  repoPath: '/path/to/your/project',
-  branch: 'contentrain',
-})
-
-// Read operations (no git transaction needed)
-const models = await writer.model.list()
-const entries = await writer.content.list('blog-posts')
-
-// Write operations (uses git worktree + commit + push)
-await writer.transaction(async (tx) => {
-  await tx.content.create('blog-posts', {
-    title: 'Hello World',
-    excerpt: 'My first post',
-  }, { status: 'draft' })
-}, { message: 'add new blog post' })
-```
+- creates or updates models
+- writes content entries
+- records source tracking
+- creates a review branch
+
+### 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
+
+This split keeps content extraction separate from source rewriting.
+
+## 📦 Core Exports
 
-## How Git Sync Works
+The package also exposes low-level modules for embedding and advanced use:
 
-Every write operation runs inside a **transaction**:
+- `@contentrain/mcp/server`
+- `@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/util/detect`
+- `@contentrain/mcp/util/fs`
+- `@contentrain/mcp/git/transaction`
+- `@contentrain/mcp/git/branch-lifecycle`
+- `@contentrain/mcp/templates`
 
-1. Creates an isolated git worktree from the target branch
-2. Applies all changes inside the worktree
-3. Commits and pushes to the target branch
-4. If the push is rejected (remote advanced), performs a **structural 3-way merge** — diffing JSON entries by their `ID` field instead of text lines — then retries (up to 3 attempts)
-5. Cleans up the worktree
+These are intended for Contentrain tooling and advanced integrations, not for direct manual editing of `.contentrain/` files.
 
-This means concurrent writes from multiple agents or the Contentrain web app won't conflict.
+## 🧠 Design Constraints
 
-## Development
+Key design decisions in this package:
+
+- local-first, filesystem-based MCP
+- no GitHub API dependency in MCP
+- JSON-only content storage
+- git-backed write workflow
+- canonical serialization
+- framework-agnostic MCP layer
+- agent decides content semantics, MCP enforces deterministic execution
+
+## 🛠 Development
+
+From the monorepo root:
 
 ```bash
-pnpm install        # Install dependencies
-pnpm dev            # Watch mode build
-pnpm test           # Run tests (watch mode)
-pnpm test:run       # Run tests once
-pnpm lint           # Lint with oxlint
-pnpm build          # Production build
+pnpm --filter @contentrain/mcp build
+pnpm --filter @contentrain/mcp test
+pnpm --filter @contentrain/mcp typecheck
+pnpm exec oxlint packages/mcp/src packages/mcp/tests
 ```
 
-## License
+## 🔗 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](https://ai.contentrain.io/packages/mcp)**.
+
+## 📄 License
 
 MIT