@contentrain/mcp 1.2.0 → 1.3.0

package/README.md

@@ -4,7 +4,7 @@
 [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/mcp)
 [![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/mcp)
 
-Local-first MCP server and core primitives for Contentrain.
+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:
 
@@ -25,7 +25,7 @@ This package is the runtime core behind Contentrain's MCP integration. It can be
 - an embeddable server (`createServer(projectRoot)`)
 - a low-level toolkit for config, models, content, validation, scanning, and git transaction flow
 
-## 🚀 Install
+## Install
 
 ```bash
 pnpm add @contentrain/mcp
@@ -44,7 +44,7 @@ Optional parser support for higher-quality source scanning:
 
 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
+## What It Does
 
 `@contentrain/mcp` manages a `.contentrain/` directory in your project and exposes MCP tools for:
 
@@ -54,28 +54,30 @@ They are listed as optional dependencies. The scanner still works without them,
 - validation and auto-fix
 - normalize scan and apply flows
 - bulk operations
-- branch submission and branch-health awareness
+- branch submission, review-mode merge, and branch-health awareness
+- project health checking (doctor)
 
 All write operations are designed around git-backed safety:
 
 - a dedicated `contentrain` branch serves as the content state single source of truth
-- each write creates a temporary worktree on a feature branch forked from `contentrain`
+- each write creates a temporary worktree on a feature branch forked from `contentrain` (branch name: `cr/{operation}/{model}/{locale}/{timestamp}-{suffix}`)
 - auto-merge: feature merges into `contentrain`, baseBranch advanced via update-ref, `.contentrain/` files selectively synced to developer's working tree
 - review: feature branch pushed to remote for team review
 - developer's working tree is never mutated during MCP git operations (no stash, no checkout, no merge)
 - context.json is committed together with content changes, not as a separate commit
-- keep canonical JSON output
-- surface validation and next-step hints to the caller
+- canonical JSON output — sorted keys, 2-space indent, trailing newline
+- validation + next-step hints surfaced to the caller
 
-## 🧰 Tool Surface
+## Tool Surface
 
-16 MCP tools with [annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) for client safety hints:
+17 MCP tools with [annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) for client safety hints:
 
 | 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, 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 | — | — |
@@ -84,13 +86,13 @@ All write operations are designed around git-backed safety:
 | `contentrain_content_delete` | Delete content entries | — | **Yes** |
 | `contentrain_content_list` | Read content entries | Yes | — |
 | `contentrain_validate` | Validate project content, optionally auto-fix structural issues | — | — |
-| `contentrain_submit` | Push `contentrain/*` branches to remote | — | — |
+| `contentrain_submit` | Push `cr/*` branches to remote | — | — |
 | `contentrain_merge` | Merge a review-mode branch into contentrain locally | — | — |
 | `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, status updates, and deletes | — | — |
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Configure via CLI (recommended)
 
@@ -120,7 +122,7 @@ const transport = new StdioServerTransport()
 await server.connect(transport)
 ```
 
-## 🔄 Example MCP Flow
+## Example MCP Flow
 
 Typical agent workflow:
 
@@ -132,7 +134,7 @@ Typical agent workflow:
 6. For hardcoded strings, use `contentrain_scan` then `contentrain_apply`
 7. Push review branches with `contentrain_submit`
 
-## 🧪 Normalize Flow
+## Normalize Flow
 
 Normalize is intentionally split into two phases:
 
@@ -145,7 +147,7 @@ Normalize is intentionally split into two phases:
 - creates or updates models
 - writes content entries
 - records source tracking
-- creates a review branch
+- creates a review branch (`cr/normalize/extract/{domain}/{timestamp}`)
 
 ### 2. Reuse
 
@@ -154,15 +156,70 @@ Normalize is intentionally split into two phases:
 - patches source files using agent-provided expressions
 - adds imports when needed
 - enforces patch path safety and scope checks
-- creates a separate review branch
+- creates a separate review branch (`cr/normalize/reuse/{model}/{locale}/{timestamp}`)
 
 This split keeps content extraction separate from source rewriting.
 
-## 📦 Core Exports
+### 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`. Calling these tools over a remote provider returns a uniform capability error:
+
+```json
+{
+  "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 tool (normalize included) works on it. Stdio transport defaults to this.
+- **GitHubProvider** — Octokit over the Git Data + Repos APIs. No clone, no worktree. `@octokit/rest` ships as an optional peer dependency.
+- **GitLabProvider** — gitbeaker over the GitLab REST API. No clone, no worktree. `@gitbeaker/rest` ships 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.
+
+### GitLab — installation & usage
+
+```bash
+pnpm add @gitbeaker/rest
+```
+
+```ts
+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 reject with a capability error on GitLabProvider — fall back to a local transport for those flows.
+
+### Bitbucket — coming soon
+
+Bitbucket Cloud + Data Center support is on the roadmap. Until the provider ships, use the `contentrain_describe_format` tool to drive Contentrain content operations manually from a Bitbucket checkout via the LocalProvider path.
+
+## 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`
@@ -171,27 +228,38 @@ The package also exposes low-level modules for embedding and advanced use:
 - `@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`
+- `@contentrain/mcp/core/overlay-reader`
 - `@contentrain/mcp/util/detect`
 - `@contentrain/mcp/util/fs`
 - `@contentrain/mcp/git/transaction`
 - `@contentrain/mcp/git/branch-lifecycle`
+- `@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.
 
-## 🧠 Design Constraints
+## Design Constraints
 
 Key design decisions in this package:
 
-- local-first, filesystem-based MCP
-- no GitHub API dependency in MCP
+- local-first **by default** — stdio transport + LocalProvider works without any network dependency
+- provider-agnostic engine — the same 17 tools run over LocalProvider, GitHubProvider, or GitLabProvider behind a single `RepoProvider` contract
+- 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
-- canonical serialization
+- 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 source-tree access (normalize, scan, apply, doctor) reject with a uniform `capability_required` error on remote providers
 
-## 🛠 Development
+## Development
 
 From the monorepo root:
 
@@ -202,17 +270,17 @@ pnpm --filter @contentrain/mcp typecheck
 pnpm exec oxlint packages/mcp/src packages/mcp/tests
 ```
 
-## 🔗 Related Packages
+## 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
+## Documentation
 
 Full documentation at **[ai.contentrain.io/packages/mcp](https://ai.contentrain.io/packages/mcp)**.
 
-## 📄 License
+## License
 
 MIT

package/dist/annotations-Clhbw2lh.mjs

@@ -0,0 +1,126 @@
+//#region src/tools/annotations.ts
+/**
+* Centralized tool annotations registry.
+* MCP clients use these hints to distinguish read-only vs. write vs. destructive tools.
+*
+* Also serves as the **single source of truth for the tool name list**. Consumers
+* that need to enumerate every registered tool (e.g. parity tests in
+* `@contentrain/rules` / `@contentrain/skills`) should import `TOOL_NAMES` below
+* rather than hardcoding the list.
+*/
+const TOOL_ANNOTATIONS = {
+	contentrain_status: {
+		title: "Project Status",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_describe: {
+		title: "Describe Model",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_describe_format: {
+		title: "Describe Format",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_doctor: {
+		title: "Project Health Report",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_init: {
+		title: "Initialize Project",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false
+	},
+	contentrain_scaffold: {
+		title: "Scaffold Template",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false
+	},
+	contentrain_model_save: {
+		title: "Save Model",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_model_delete: {
+		title: "Delete Model",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: false
+	},
+	contentrain_content_save: {
+		title: "Save Content",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_content_delete: {
+		title: "Delete Content",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: false
+	},
+	contentrain_content_list: {
+		title: "List Content",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_validate: {
+		title: "Validate Project",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_submit: {
+		title: "Submit Branches",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_merge: {
+		title: "Merge Branch",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false
+	},
+	contentrain_scan: {
+		title: "Scan Source Code",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	contentrain_apply: {
+		title: "Apply Normalize",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false
+	},
+	contentrain_bulk: {
+		title: "Bulk Operations",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false
+	}
+};
+/**
+* Canonical list of every registered MCP tool name, derived from the
+* single source of truth above. Re-exported here with a stable name so
+* parity tests in sibling packages (`@contentrain/rules`,
+* `@contentrain/skills`) can assert against it without depending on
+* `TOOL_ANNOTATIONS` internals.
+*/
+const TOOL_NAMES = Object.freeze(Object.keys(TOOL_ANNOTATIONS));
+//#endregion
+export { TOOL_NAMES as n, TOOL_ANNOTATIONS as t };
+
+//# sourceMappingURL=annotations-Clhbw2lh.mjs.map

package/dist/annotations-Clhbw2lh.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations-Clhbw2lh.mjs","names":[],"sources":["../src/tools/annotations.ts"],"sourcesContent":["import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'\n\n/**\n * Centralized tool annotations registry.\n * MCP clients use these hints to distinguish read-only vs. write vs. destructive tools.\n *\n * Also serves as the **single source of truth for the tool name list**. Consumers\n * that need to enumerate every registered tool (e.g. parity tests in\n * `@contentrain/rules` / `@contentrain/skills`) should import `TOOL_NAMES` below\n * rather than hardcoding the list.\n */\nexport const TOOL_ANNOTATIONS: Record<string, ToolAnnotations> = {\n  // ─── Context (read-only) ───\n  contentrain_status: {\n    title: 'Project Status',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_describe: {\n    title: 'Describe Model',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_describe_format: {\n    title: 'Describe Format',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_doctor: {\n    title: 'Project Health Report',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n\n  // ─── Setup (write + git) ───\n  contentrain_init: {\n    title: 'Initialize Project',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: false,\n  },\n  contentrain_scaffold: {\n    title: 'Scaffold Template',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: false,\n  },\n\n  // ─── Model (write + git) ───\n  contentrain_model_save: {\n    title: 'Save Model',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_model_delete: {\n    title: 'Delete Model',\n    readOnlyHint: false,\n    destructiveHint: true,\n    idempotentHint: false,\n  },\n\n  // ─── Content (mixed) ───\n  contentrain_content_save: {\n    title: 'Save Content',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_content_delete: {\n    title: 'Delete Content',\n    readOnlyHint: false,\n    destructiveHint: true,\n    idempotentHint: false,\n  },\n  contentrain_content_list: {\n    title: 'List Content',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n\n  // ─── Workflow (mixed) ───\n  contentrain_validate: {\n    title: 'Validate Project',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_submit: {\n    title: 'Submit Branches',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_merge: {\n    title: 'Merge Branch',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: false,\n  },\n\n  // ─── Normalize (mixed) ───\n  contentrain_scan: {\n    title: 'Scan Source Code',\n    readOnlyHint: true,\n    destructiveHint: false,\n    idempotentHint: true,\n  },\n  contentrain_apply: {\n    title: 'Apply Normalize',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: false,\n  },\n\n  // ─── Bulk (write + git) ───\n  contentrain_bulk: {\n    title: 'Bulk Operations',\n    readOnlyHint: false,\n    destructiveHint: false,\n    idempotentHint: false,\n  },\n}\n\n/**\n * Canonical list of every registered MCP tool name, derived from the\n * single source of truth above. Re-exported here with a stable name so\n * parity tests in sibling packages (`@contentrain/rules`,\n * `@contentrain/skills`) can assert against it without depending on\n * `TOOL_ANNOTATIONS` internals.\n */\nexport const TOOL_NAMES: readonly string[] = Object.freeze(Object.keys(TOOL_ANNOTATIONS))\n"],"mappings":";;;;;;;;;;AAWA,MAAa,mBAAoD;CAE/D,oBAAoB;EAClB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,sBAAsB;EACpB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,6BAA6B;EAC3B,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,oBAAoB;EAClB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,kBAAkB;EAChB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,sBAAsB;EACpB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,wBAAwB;EACtB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,0BAA0B;EACxB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,0BAA0B;EACxB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,4BAA4B;EAC1B,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,0BAA0B;EACxB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,sBAAsB;EACpB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,oBAAoB;EAClB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,mBAAmB;EACjB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,kBAAkB;EAChB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACD,mBAAmB;EACjB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CAGD,kBAAkB;EAChB,OAAO;EACP,cAAc;EACd,iBAAiB;EACjB,gBAAgB;EACjB;CACF;;;;;;;;AASD,MAAa,aAAgC,OAAO,OAAO,OAAO,KAAK,iBAAiB,CAAC"}

package/dist/{apply-manager-BkPMfpsN.mjs → apply-manager-D5ym5Jba.mjs}

@@ -1,9 +1,9 @@
-import { c as writeText, o as readText, r as pathExists } from "./fs-BnIQ4dKj.mjs";
-import { t as readConfig } from "./config-B5kc2oeV.mjs";
-import { S as writeContent, _ as resolveMdFilePath, c as validateModelDefinition, h as resolveJsonFilePath, l as writeModel, m as resolveContentDir, o as listModels, s as readModel } from "./model-manager-DW_fOGRM.mjs";
-import { n as writeContext } from "./context-DIDt_TxX.mjs";
-import { t as checkBranchHealth } from "./branch-lifecycle-wGJg25LT.mjs";
-import { n as createTransaction, t as buildBranchName } from "./transaction-C_Pvux78.mjs";
+import { c as writeText, o as readText, r as pathExists } from "./fs-DLbVB-Ek.mjs";
+import { t as readConfig } from "./config-BIl5Ybj0.mjs";
+import { S as writeContent, _ as resolveMdFilePath, c as validateModelDefinition, h as resolveJsonFilePath, l as writeModel, m as resolveContentDir, o as listModels, s as readModel } from "./model-manager-BhLsUgaB.mjs";
+import { r as writeContext } from "./context-J0OU9Nfp.mjs";
+import { n as createTransaction, t as buildBranchName } from "./transaction-DgkNgWSI.mjs";
+import { n as checkBranchHealth } from "./branch-lifecycle-CFVpTpNT.mjs";
 import { extname, join } from "node:path";
 //#region src/core/apply-manager.ts
 const MAX_PATCHES = 100;
@@ -753,4 +753,4 @@ function addImportsToLines(lines, imports) {
 //#endregion
 export { detectFileFramework as a, validatePatchPath as c, checkSyntax as i, applyExtract as n, replaceInLine as o, applyReuse as r, validateFrameworkExpression as s, PATCHABLE_EXTENSIONS as t };
 
-//# sourceMappingURL=apply-manager-BkPMfpsN.mjs.map
+//# sourceMappingURL=apply-manager-D5ym5Jba.mjs.map