Contentrain

@contentrain/mcp

适用于 Contentrain 的跨提供商 MCP 引擎——默认优先本地运行，也可选用 GitHub 和 GitLab 后端，并通过 HTTP 传输为 Studio 等远程驱动程序提供支持。

从这里开始：

• 2 分钟产品演示
• MCP 软件包文档
• Normalize 指南

Contentrain 是 AI 生成内容治理基础设施：

• Agent 生成内容决策
• MCP 执行确定性的文件系统和 git 工作流
• 人工审核并合并
• 系统确保架构、区域设置和序列化保持一致

此软件包是 Contentrain MCP 集成背后的运行时核心。可将其用作：

• stdio MCP 服务（contentrain-mcp）
• 可嵌入的服务（createServer(projectRoot)）
• 用于配置、模型、内容、验证、扫描和 git 事务流程的底层工具包

安装

pnpm add @contentrain/mcp

要求：

• Node.js 22+
• 机器上可使用 git

用于提高源代码扫描质量的可选解析器支持：

• @vue/compiler-sfc
• @astrojs/compiler
• svelte

它们被列为可选依赖项。即使未安装，扫描器仍可正常工作；但安装后，对 Vue/Astro/Svelte 的检测会更准确。

功能说明

@contentrain/mcp 会管理项目中的 .contentrain/ 目录，并提供以下 MCP 工具：

• 初始化项目
• 创建和删除模型
• 保存、删除和列出内容
• 验证和自动修复
• 规范化扫描和应用流程
• 批量操作
• 提交分支、以审查模式合并，并感知分支健康状况
• 检查项目健康状况（doctor）

所有写入操作都围绕由 git 支持的安全机制设计：

• 专用的 contentrain 分支作为内容状态的唯一事实来源
• 每次写入都会在一个从 contentrain 分出的功能分支上创建临时工作树（分支名称：cr/{operation}/{model}/{locale}/{timestamp}-{suffix}）
• 自动合并：功能分支合并到 contentrain，通过 update-ref 推进 baseBranch；当开发者当前检出的分支是 base branch 时，将 .contentrain/ 文件有选择地同步到开发者的工作树
• baseBranch = CONTENTRAIN_BRANCH env → repository.default_branch → remote HEAD → main → master → 当前检出的分支（最后的兜底选项）。在功能分支上执行的写入不会合并、移动或推送该分支
• 计划从工作树读取，但会提交到获取到的 contentrain 最新提交：JSON 更改会按键逐一移植，因此其他写入者推送的条目会保留；若发生相同值冲突，则不写入任何内容，并返回 CONTENT_WORKING_TREE_STALE
• 在当前检出的功能分支上，未更新的写入会改为从 contentrain ref 读取 .contentrain/**（源文件仍从工作树读取）；读取工具会通过 content_source 报告这一点
• 审查：将功能分支推送到远程，供团队审查；一旦合并（或删除），其远程副本也会被移除——尽力执行，可在 config.json 中设置 remoteBranchCleanup: false 选择退出
• 本地模式（git.push: false 或 CONTENTRAIN_NO_PUSH=1）：绝不会向远程推送或删除任何内容，且每个结果都会说明这一点——参见Git 环境和本地模式
• 每次本地写入的 git 块都会标明解析后的 base_branch；如果它不是当前检出的分支，结果中的 warning 会说明工作树未受影响
• 提交钩子：默认在机器提交时跳过；设置 git.verify: true 或 CONTENTRAIN_VERIFY=1 后会运行钩子，若钩子拒绝提交，写入会失败并返回其输出——参见提交钩子
• 合并分支检测能够应对 base 历史重写（通过祖先关系检查，并在必要时回退到 patch-id），因此 rebase/squash 不会遗留过时的分支
• MCP git 操作期间绝不会修改开发者的工作树（不执行 stash、checkout 或 merge）
• context.json 永远不会进入功能分支——合并后会在 contentrain 分支上重新生成（本地流程由事务层执行；远程流程由负责合并的编排器执行）
• 规范化的 JSON 输出——键排序、2 个空格缩进、以换行符结尾
• 向调用方提供验证结果和后续步骤提示

工具范围

27 个 MCP 工具——22 个核心工具 + 5 个媒体工具——均带有注解（readOnlyHint、destructiveHint、idempotentHint，以及 openWorldHint: false；唯一例外是 contentrain_media_ingest，它会在服务端获取调用方提供的 URL），用于向客户端提供安全提示。

工具列表会根据能力动态调整。 tools/list 只会公布解析后的 provider 与 projectRoot 组合实际能够提供的工具。本地 stdio 服务会列出 22 个核心工具；由远程 provider（GitHub/GitLab，无本地检出）驱动的会话只会列出适用于远程的子集——status、describe、describe_format、model_save、model_delete、content_save、content_delete、content_list、vocabulary_save、vocabulary_delete、validate。需求映射位于 TOOL_REQUIREMENTS（@contentrain/mcp/tools/availability）。

工具	用途	只读	破坏性
contentrain_status	项目状态、配置、模型、分支健康状况、上下文	是	—
contentrain_describe	模型的完整架构和示例数据	是	—
contentrain_describe_format	文件格式和存储约定参考	是	—
contentrain_doctor	项目健康报告（环境、结构、模型、孤立项、本地与远程分支、SDK）	是	—
contentrain_init	创建 .contentrain/ 结构和基础配置	—	—
contentrain_scaffold	应用博客、文档、落地页、SaaS 等起始模板	—	—
contentrain_model_save	创建或更新模型定义	—	—
contentrain_model_delete	删除模型定义	—	是
contentrain_content_save	为任意模型类型保存内容条目	—	—
contentrain_content_delete	删除内容条目	—	是
contentrain_content_list	读取内容条目	是	—
contentrain_validate	验证项目内容，可选择自动修复结构问题	—	—
contentrain_submit	将 cr/* 分支推送到远程，然后按需清理已合并的本地与远程残留分支	—	—
contentrain_merge	在本地将审查模式分支合并到 contentrain（按精确分支或模型）；删除其远程副本	—	—
contentrain_reconcile	对已分叉的 contentrain ↔ base 分支对执行内容感知型三方合并（先 dry_run，再处理冲突）	—	—
contentrain_branch_list	列出待处理的 cr/* 分支及合并状态（remote: true 会添加远程视图）	是	—
contentrain_branch_delete	在本地和远程删除过期或失败的 cr/* 分支（contentrain 分支受保护）	—	是
contentrain_scan	基于图和候选项扫描硬编码字符串	是	—
contentrain_apply	执行规范化的提取/复用，支持 dry-run	—	—
contentrain_bulk	批量复制区域设置、更新状态和删除（dry_run 可预览）	—	—
contentrain_vocabulary_save	添加或更新规范词汇条目（与现有内容合并）	—	—
contentrain_vocabulary_delete	按 slug 移除规范词汇条目（confirm: true）	—	是
contentrain_media_list	列出媒体资源（搜索、标签筛选、游标分页）	是	—
contentrain_media_get	按 id 获取单个媒体资源	是	—
contentrain_media_ingest	从源 URL 导入资源（由提供方在服务端获取）	—	—
contentrain_media_update	更新资源元数据（alt、标签、文件名）	—	—
contentrain_media_delete	从媒体栈中删除资源	—	是

五个 contentrain_media_* 工具会确定性地透传到提供方可选的媒体功能（RepoProvider.media），仅在提供方公开该功能时才会注册（例如 Studio MCP Cloud）。本地 stdio 服务和普通 GitHub/GitLab 提供方不会列出这些工具。导入基于 URL（MCP 没有二进制通道）；获取时的 SSRF、MIME 和大小策略由提供方实现负责。

快速开始

通过 CLI 配置（推荐）

npx contentrain setup claude-code   # or: cursor, vscode, windsurf, copilot

此操作会自动为你的 IDE 创建正确的 MCP 配置文件。详情请参阅 CLI 文档。

作为独立 MCP 服务运行

CONTENTRAIN_PROJECT_ROOT=/path/to/project npx -y @contentrain/mcp

如果未提供 CONTENTRAIN_PROJECT_ROOT，则使用当前工作目录。

Git 环境和本地模式

这些设置适用于本地提供方（stdio、LocalProvider）：

变量	默认值	作用
CONTENTRAIN_BRANCH	未设置	contentrain 分支推进时所基于的分支。优先级高于 repository.default_branch，其次依次为远程 HEAD → main → master → 当前检出的分支。仅对当前进程生效；不会写入配置
CONTENTRAIN_REMOTE	origin	每次 fetch 和 push（以及远程分支清理）所用的远程仓库
CONTENTRAIN_NO_PUSH	未设置	1/true 会启用本地模式；0/false 会关闭本地模式。其他值均忽略
CONTENTRAIN_VERIFY	未设置	1/true 会在 Contentrain 的提交上运行仓库的提交钩子；0/false 会跳过钩子。优先级高于 git.verify。其他值均忽略

本地模式会将所有写入保留在本地分支：不推送分支、不推送评审分支，也不会在自动合并、批准或协调后推送；不会删除或清理远程分支。有远程仓库时仍会 fetch，因为 fetch 不属于 push。若要为项目启用此模式，可在 .contentrain/config.json 中设置 "git": { "push": false }；也可以通过 CONTENTRAIN_NO_PUSH=1 对单次运行启用。

优先级：环境变量在两个方向上都优先于配置。即使配置允许推送，CONTENTRAIN_NO_PUSH=1 也会关闭推送；即使 git.push: false，CONTENTRAIN_NO_PUSH=0 也会重新启用推送。两者均未设置时，推送处于启用状态。

这绝不会静默成功。每次写入的 git 块都会报告 remote_push: "disabled"，并附带 remote_note: "not pushed (local mode)"；next_steps 中会包含一行 LOCAL MODE。contentrain_submit 会返回错误，而不是推送；请使用 contentrain_merge 合并评审分支。contentrain_merge 和 contentrain_branch_delete 会照常删除本地分支，并报告 remote_skipped: "local-mode"，远程副本保持不变。

提交钩子

默认情况下，Contentrain 的机器提交（cr/* 内容提交、context.json 提交、协调合并提交、空仓库的初始提交）会跳过仓库的提交钩子（pre-commit、prepare-commit-msg、commit-msg）。这样可以确保现有项目继续正常运行：这些提交是在不含你的 node_modules 的临时工作树中创建的，而且它们以 [contentrain] … 开头的主题不符合严格的 commitlint 规则。合并仍会运行合并钩子，推送仍会运行 pre-push，与之前一样。

若要在每次机器提交时运行提交钩子，可在 .contentrain/config.json 中设置 "git": { "verify": true }，或在单次运行时设置 CONTENTRAIN_VERIFY=1（CONTENTRAIN_VERIFY=0 会覆盖配置并跳过钩子）。启用钩子后：

• 如果某个钩子拒绝内容提交，写入就会失败：不会有任何内容落地，工具错误会包含钩子的输出。不会在不运行钩子的情况下重试；
• 如果钩子只拒绝后续的 context.json 提交（此时内容已经在 contentrain 上），结果会报告 warning，而不会将其吞掉；
• 钩子必须能在系统临时目录下的工作树中正常运行——如果钩子运行 npx lint-staged，则该工具必须在该目录中可用。

将服务嵌入自己的进程

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 也接受一个选项对象：{ provider, projectRoot?, instructions? }。instructions 用于设置客户端在 initialize 时接收的 MCP instructions 字符串（默认为该服务已注册工具的 defaultInstructions；若所有工具均可用，则为 DEFAULT_INSTRUCTIONS；长度不超过 512 个字符；传入 '' 可省略）。HTTP 入口（startHttpMcpServer、startHttpMcpServerWith）也接受相同的 instructions 选项。

MCP 工作流示例

典型的 Agent 工作流：

1. 调用 contentrain_status
2. 如有需要，调用 contentrain_init
3. 使用 contentrain_model_save 或 contentrain_scaffold 创建模型
4. 使用 contentrain_content_save 保存内容
5. 使用 contentrain_validate 进行验证
6. 对于硬编码字符串，先使用 contentrain_scan，再使用 contentrain_apply
7. 使用 contentrain_submit 推送评审分支

标准化流程

标准化特意拆分为两个阶段：

1. 提取

contentrain_scan 用于查找候选字符串。

使用 mode: "extract" 调用 contentrain_apply：

• 创建或更新模型
• 写入内容条目
• 记录源代码跟踪信息
• 创建审核分支（cr/normalize/extract/{domain}/{timestamp}）

2. 复用

使用 mode: "reuse" 调用 contentrain_apply：

• 使用 Agent 提供的表达式修补源文件
• 按需添加导入语句
• 强制执行补丁路径安全检查和作用范围检查
• 创建单独的审核分支（cr/normalize/reuse/{model}/{locale}/{timestamp}）

这种拆分将内容提取与源代码重写分开。

传输方式 / 提供方要求

Normalize（contentrain_scan 和 contentrain_apply）需要访问本地磁盘——AST 扫描器会遍历源代码树并就地修补文件。它只能在 LocalProvider 上运行（stdio 传输，或配置了 LocalProvider 的 HTTP 传输）。

GitHubProvider 等远程提供方会将 astScan: false、sourceRead: false 和 sourceWrite: false 作为能力公开。通过远程提供方调用这些工具时，会返回统一的能力错误：

{
  "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."
}

使用远程传输的 Agent 应在调用 normalize 前，改用本地传输（或本地检出）。

远程提供方

MCP 支持三个后端，它们遵循相同的 RepoProvider 契约：

• LocalProvider — simple-git + worktree。所有工具（包括 normalize）均可使用。stdio 传输默认使用此提供方。
• GitHubProvider — 通过 Git Data + Repos API 使用 Octokit。无需克隆，无需 worktree。@octokit/rest 作为可选对等依赖提供。
• GitLabProvider — 通过 GitLab REST API 使用 gitbeaker。无需克隆，无需 worktree。@gitbeaker/rest 作为可选对等依赖提供。支持 gitlab.com 和可自托管的 CE / EE。

每个远程提供方都实现相同的接口：读取器（readFile / listDirectory / fileExists）、写入器（applyPlan——单个原子提交）、分支操作（list / create / delete / diff / merge / isMerged / getDefaultBranch）。mergeBranch 在 GitHub 上会直接执行；在 GitLab 上则会打开一个 MR 并立即接受，因此最终的 MergeResult 结构在两种情况下都相同。GitHub 提供方还支持将完整的提交 SHA 作为 applyPlan 的 base（以及 createBranch 的 fromRef），用于比较并设置写入：若分支不存在，则从该提交创建分支；若分支已偏离该提交，则拒绝写入并返回 PROVIDER_CONFLICT。

GitLab — 安装与使用

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

能力：sourceRead、sourceWrite、astScan、localWorktree 均为 false；pushRemote、branchProtection、pullRequestFallback 均为 true。在 GitLabProvider 上执行 Normalize / scan / apply 会因能力错误而被拒绝——这些工作流请改用本地传输。

Bitbucket — 即将推出

Bitbucket Cloud + Data Center 支持已列入路线图。在该提供方发布之前，请通过 LocalProvider 路径从 Bitbucket 检出中使用 contentrain_describe_format 工具，手动执行 Contentrain 内容操作。

核心导出

该软件包还导出了用于嵌入和高级用途的底层模块：

• @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 — 计划 API（包括 planReconcile 及其 bindRef 读取器适配器），以及相对于内容根目录的路径辅助函数：contentDirPath、contentFilePath、documentFilePath、metaFilePath
• @contentrain/mcp/core/overlay-reader
• @contentrain/mcp/core/migration — 允许列表限定的迁移写入路径：createMigrationWriter、scopeHash、decide。请参阅下文的迁移写入
• @contentrain/mcp/util/detect
• @contentrain/mcp/util/fs
• @contentrain/mcp/git/transaction
• @contentrain/mcp/git/branch-lifecycle — 分支健康检查与清理，以及远程 cr/* 生命周期管理：deleteRemoteBranch、listRemoteCrBranches、pruneMergedRemoteBranches、isRefMerged、classifyMergedBranches
• @contentrain/mcp/git/base-branch — resolveBaseBranch，所有 MCP 写入操作以及 contentrain status / serve 使用的唯一基础分支解析器（环境变量 → repository.default_branch → origin/HEAD → main → master → 当前检出的分支）；resolveBaseBranchSource（相同的解析逻辑，并指出命中的层级）；resolveInitDefaultBranch（init 记录为 repository.default_branch 的值，或 null）
• @contentrain/mcp/git/errors
• @contentrain/mcp/git/reconcile — reconcileBranches，本地协调执行器
• @contentrain/mcp/tools/annotations
• @contentrain/mcp/templates
• @contentrain/mcp/providers/local
• @contentrain/mcp/providers/github
• @contentrain/mcp/providers/gitlab

这些模块面向 Contentrain 工具和高级集成，不适用于直接手动编辑 .contentrain/ 文件。

迁移写入

迁移交付的不是内容，而是代码库：src/、public/、package.json、锁文件、部署配置。内容写入路径从未为这些内容而设计；拓宽它会悄然改变整个产品赖以立足的安全边界——“Contentrain 只写入 .contentrain/”是一项承诺，而非实现细节。

@contentrain/mcp/core/migration 才是把关机制。它封装了一个本就能写入任意路径的提供方，并在其前面加入同意机制。

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

它保证：

范围	仅限白名单模式覆盖的路径。.contentrain/** 不会默认包含在内——迁移若要操作存储目录，就必须明确申请；审批者也能看到这一点
同意	一次审批通过 scope_hash 绑定到确切范围。对 src/** 的审批无法被重放到同时包含 .github/workflows/** 的范围上
分支	使用 migration/* 引用。contentrain 分支绝不会作为目标或基准分支——包括迁移不得继承的 ApplyPlanInput 默认值
审计记录	每个文件对应一条 MigrationAuditEntry：步骤、路径、操作、允许该操作的模式、操作者、时间戳、提交
撤销	一个分支，通过一个 PR 交付，可用一次 git revert 撤销

所有拒绝操作都会在调用提供方之前发生，且计划会整体拒绝：只要计划中有一个路径超出范围，就不会写入任何内容，包括范围内允许的部分。与从未开始相比，恢复仅完成一半的迁移更困难。

路径匹配器是一项安全控制，设计上采用默认拒绝策略。路径遍历、绝对路径、反斜杠分隔符、百分号编码、空路径段和控制字符都会在检查任何模式之前被拒绝；模式两端均设锚点，因此 src/* 不会覆盖 src/a/b，也不会因前缀匹配而命中任何路径；模式中的正则元字符按字面量处理，因此白名单条目不会在不知情的情况下覆盖超出其表述范围的路径。

设计约束

此软件包的关键设计决策：

• 默认本地优先——stdio 传输 + LocalProvider 无需任何网络依赖即可工作
• 提供方无关的引擎——相同的核心工具可通过统一的 RepoProvider 契约，运行于 LocalProvider、GitHubProvider 或 GitLabProvider；媒体工具使用提供方可选的媒体功能
• 远程提供方 SDK（@octokit/rest、@gitbeaker/rest）是可选的对等依赖——仅在使用相应提供方时引入
• 仅使用 JSON 存储内容
• 基于 git 的写入工作流（本地通过 worktree 事务，远程通过 Git Data / REST API 执行单次原子提交）
• 规范化序列化——字节级确定性输出、键排序、末尾换行符
• 与框架无关的 MCP 层
• Agent 决定内容语义，MCP 强制执行确定性操作
• 能力门控——需要访问源码树的工具（normalize、scan、apply、doctor）在远程提供方上会返回统一的 capability_required 错误

开发

在 monorepo 根目录运行：

pnpm --filter @contentrain/mcp build
pnpm --filter @contentrain/mcp test
pnpm --filter @contentrain/mcp typecheck
pnpm exec oxlint packages/mcp/src packages/mcp/tests

相关软件包

• contentrain — CLI 和本地审查工具
• @contentrain/query — 生成的运行时查询 SDK
• @contentrain/rules — IDE / Agent 规则和提示词
• @contentrain/types — 共享的架构和模型类型

文档

完整文档请参阅 ai.contentrain.io/packages/mcp。

许可证

MIT

区域覆盖范围（model.locales）

contentrain_validate 会检查 i18n: true 模型与 config.locales.supported 中每个区域设置的对等性。声明了 locales 的模型（即该列表的子集）则只会针对这个子集进行检查，这样，部分内容已翻译的网站就能如实声明覆盖范围，而不必因从未提供过的翻译而验证失败。未声明 locales（所有早于此字段的模型均如此）表示覆盖整个项目列表。

从未编写过的翻译属于警告：一个区域设置有而另一个没有的 collection 条目（Entry parity），类似于 document 缺少翻译。没有内容文件的区域设置（Locale file missing）以及某个区域设置缺少的 dictionary 键（Key parity）则属于错误。每条消息都会注明评估时所依据的列表，因此可以区分以下两种情况：

Locale file missing: tr.json (checked against the model's own locales [en, tr])
Entry parity: entry "a1b2c3" exists in en but missing in tr (checked against the project's supported locales [en, tr, da])

contentrain_model_save 接受 locales，并会拒绝 config.locales.supported 之外的区域设置。contentrain_validate fix:true 会报告错误的声明，但绝不会自行编造声明：缩小模型的覆盖范围属于内容决策，而工具唯一能推导出的值——当前恰好有文件的区域设置——会把现有缺口写入架构，并掩盖揭示这些缺口的错误。

运行时模型配置

结构性 contentrain_model_save 编辑会保留现有的顶层 form 和 comments 块。这些块属于运行时提供程序；结构性工具不会启用或更改它们。如果配置得以保留，其响应会列出 preserved_blocks。