@contentrain/mcp 1.2.1 → 1.4.0

package/dist/{server-Dtq8vqbK.mjs → server-BkhhtEE2.mjs}

@@ -1,145 +1,47 @@
-import { a as readJson, n as ensureDir, r as pathExists, s as writeJson, t as contentrainDir } from "./fs-BnIQ4dKj.mjs";
-import { n as readVocabulary, t as readConfig } from "./config-B5kc2oeV.mjs";
-import { n as readMeta, r as writeMeta } from "./meta-manager--0IwAPCl.mjs";
-import { S as writeContent, _ as resolveMdFilePath, a as fieldDefZodSchema, c as validateModelDefinition, d as listContent, g as resolveLocaleStrategy, h as resolveJsonFilePath, i as deleteModel, l as writeModel, m as resolveContentDir, n as checkReferences, o as listModels, r as countEntries, s as readModel, u as deleteContent } from "./model-manager-DW_fOGRM.mjs";
-import { t as readContext } from "./context-DIDt_TxX.mjs";
-import { t as detectStack } from "./detect-DinOQAmK.mjs";
-import { n as cleanupMergedBranches, t as checkBranchHealth } from "./branch-lifecycle-wGJg25LT.mjs";
-import { n as listTemplates, t as getTemplate } from "./templates-bRPzYq4M.mjs";
-import { i as mergeBranch, n as createTransaction, r as ensureContentBranch, t as buildBranchName } from "./transaction-C_Pvux78.mjs";
-import { t as validateProject } from "./validator-SQYUV2JP.mjs";
-import { t as buildGraph } from "./graph-builder-tM7zj-SX.mjs";
-import { n as scanSummary, t as scanCandidates } from "./scanner-DUoXnmtI.mjs";
-import { n as applyExtract, r as applyReuse } from "./apply-manager-BkPMfpsN.mjs";
+import { i as planContentDelete, n as planModelDelete, r as planContentSave, t as planModelSave } from "./ops-DjEWi5Wa.mjs";
+import { n as contentFilePath, t as contentDirPath } from "./paths-CYl5vCBD.mjs";
+import { a as readJson, n as ensureDir, r as pathExists, s as writeJson, t as contentrainDir } from "./fs-DLbVB-Ek.mjs";
+import { n as readVocabulary, t as readConfig } from "./config-BIl5Ybj0.mjs";
+import { S as writeContent, _ as resolveMdFilePath, a as fieldDefZodSchema, c as validateModelDefinition, d as listContent, g as resolveLocaleStrategy, h as resolveJsonFilePath, l as writeModel, m as resolveContentDir, n as checkReferences, o as listModels, r as countEntries, s as readModel, u as deleteContent } from "./model-manager-BhLsUgaB.mjs";
+import { n as readMeta, r as writeMeta } from "./meta-manager-C900rEyG.mjs";
+import { n as readContext, t as buildContextChange } from "./context-J0OU9Nfp.mjs";
+import { i as mergeBranch, n as createTransaction, r as ensureContentBranch, t as buildBranchName } from "./transaction-DgkNgWSI.mjs";
+import { t as LocalProvider } from "./local-DvP4Y4T-.mjs";
+import { t as detectStack } from "./detect-DL9mFmaS.mjs";
+import { n as checkBranchHealth, r as cleanupMergedBranches } from "./branch-lifecycle-CFVpTpNT.mjs";
+import { t as TOOL_ANNOTATIONS } from "./annotations-Clhbw2lh.mjs";
+import { n as listTemplates, t as getTemplate } from "./templates-VrLVqfe5.mjs";
+import { t as OverlayReader } from "./overlay-reader-DOdyDRIv.mjs";
+import { t as validateProject } from "./validator-B0nNRFeU.mjs";
+import { t as buildGraph } from "./graph-builder-DXv2JEp-.mjs";
+import { n as scanSummary, t as scanCandidates } from "./scanner-DKMwc03k.mjs";
+import { n as applyExtract, r as applyReuse } from "./apply-manager-D5ym5Jba.mjs";
+import { t as runDoctor } from "./doctor-CgBoT6h1.mjs";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { CONTENTRAIN_BRANCH } from "@contentrain/types";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { simpleGit } from "simple-git";
-//#region src/tools/annotations.ts
-/**
-* Centralized tool annotations registry.
-* MCP clients use these hints to distinguish read-only vs. write vs. destructive tools.
-*/
-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_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
-	}
-};
-//#endregion
+import { z } from "zod";
 //#region src/tools/context.ts
-function registerContextTools(server, projectRoot) {
+function registerContextTools(server, provider, projectRoot) {
 	server.tool("contentrain_status", "Get full project status (read-only). Returns config, models, context. Do NOT manually edit .contentrain/ based on this output.", {}, TOOL_ANNOTATIONS["contentrain_status"], async () => {
-		if (!await pathExists(join(contentrainDir(projectRoot), "config.json"))) {
-			const detectedStack = await detectStack(projectRoot);
+		if (!await provider.fileExists(".contentrain/config.json")) {
+			const detectedStack = projectRoot ? await detectStack(projectRoot) : null;
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
 					initialized: false,
-					detected_stack: detectedStack,
+					...detectedStack ? { detected_stack: detectedStack } : {},
 					suggestion: "Run contentrain_init to set up .contentrain/ structure",
 					next_steps: ["Run contentrain_init"]
 				}, null, 2)
 			}] };
 		}
-		const config = await readConfig(projectRoot);
-		const models = await listModels(projectRoot);
-		const context = await readContext(projectRoot);
-		const vocabulary = await readVocabulary(projectRoot);
+		const config = await readConfig(provider);
+		const models = await listModels(provider);
+		const context = projectRoot ? await readContext(projectRoot) : await readContext(provider);
+		const vocabulary = await readVocabulary(provider);
 		const errors = [];
 		if (!config) errors.push(".contentrain/config.json missing");
 		const result = {
@@ -156,20 +58,25 @@ function registerContextTools(server, projectRoot) {
 				lastOperation: context.lastOperation,
 				stats: context.stats
 			} : null,
-			vocabulary_size: vocabulary ? Object.keys(vocabulary.terms).length : 0
+			vocabulary: vocabulary && Object.keys(vocabulary.terms).length > 0 ? {
+				size: Object.keys(vocabulary.terms).length,
+				terms: vocabulary.terms
+			} : { size: 0 }
 		};
-		if (await pathExists(join(projectRoot, ".git"))) try {
-			const cleanup = await cleanupMergedBranches(projectRoot);
-			const health = await checkBranchHealth(projectRoot);
-			result["branches"] = {
-				total: health.total,
-				merged: health.merged,
-				unmerged: health.unmerged,
-				cleaned_up: cleanup.deleted
-			};
-			if (health.message) result["branch_warning"] = health.message;
-			if (health.blocked) errors.push(health.message);
-		} catch {}
+		if (projectRoot) {
+			if (await pathExists(join(projectRoot, ".git"))) try {
+				const cleanup = await cleanupMergedBranches(projectRoot);
+				const health = await checkBranchHealth(projectRoot);
+				result["branches"] = {
+					total: health.total,
+					merged: health.merged,
+					unmerged: health.unmerged,
+					cleaned_up: cleanup.deleted
+				};
+				if (health.message) result["branch_warning"] = health.message;
+				if (health.blocked) errors.push(health.message);
+			} catch {}
+		}
 		if (errors.length > 0) result["validation"] = {
 			errors: errors.length,
 			warnings: 0,
@@ -190,7 +97,7 @@ function registerContextTools(server, projectRoot) {
 		include_sample: z.boolean().optional().default(false).describe("Include one sample entry"),
 		locale: z.string().optional().describe("Locale for sample content (default: config default locale)")
 	}, TOOL_ANNOTATIONS["contentrain_describe"], async ({ model: modelId, include_sample, locale }) => {
-		const modelDef = await readModel(projectRoot, modelId);
+		const modelDef = await readModel(provider, modelId);
 		if (!modelDef) return {
 			content: [{
 				type: "text",
@@ -198,9 +105,9 @@ function registerContextTools(server, projectRoot) {
 			}],
 			isError: true
 		};
-		const config = await readConfig(projectRoot);
+		const config = await readConfig(provider);
 		const effectiveLocale = locale ?? config?.locales.default ?? "en";
-		const stats = await countEntries(projectRoot, modelDef);
+		const stats = await countEntries(provider, modelDef);
 		const result = {
 			id: modelDef.id,
 			name: modelDef.name,
@@ -215,10 +122,17 @@ function registerContextTools(server, projectRoot) {
 			}
 		};
 		if (include_sample) {
-			const sample = await getSample(projectRoot, modelDef, effectiveLocale);
+			const sample = await getSample(provider, modelDef, effectiveLocale);
 			if (sample) result["sample"] = sample;
 		}
 		result["import_snippet"] = generateImportSnippet(modelDef, config?.stack ?? "other", effectiveLocale);
+		if (modelDef.kind === "dictionary") {
+			const vocabulary = await readVocabulary(provider);
+			if (vocabulary && Object.keys(vocabulary.terms).length > 0) result["vocabulary_hint"] = {
+				note: "Check these approved terms before creating new dictionary keys",
+				terms: vocabulary.terms
+			};
+		}
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
@@ -335,16 +249,28 @@ function registerContextTools(server, projectRoot) {
 					"4. Determine file path using locale_strategy and i18n flag",
 					"5. Parse JSON (collection/singleton/dictionary) or Markdown frontmatter (document)",
 					"6. Optionally read .contentrain/meta/{model-id}/{locale}.json for status/metadata"
-				] }
+				] },
+				vocabulary: {
+					description: "Canonical terms for content consistency across models and locales.",
+					file: ".contentrain/vocabulary.json",
+					format: {
+						version: "number",
+						terms: "Record<category, Record<slug, translation_value>>"
+					},
+					usage: [
+						"Check vocabulary before creating dictionary entries — reuse canonical terms",
+						"If a new term is needed, consider adding it to vocabulary first",
+						"Vocabulary applies across ALL dictionary models and ALL locales"
+					]
+				}
 			}, null, 2)
 		}] };
 	});
 }
-async function getSample(projectRoot, model, locale) {
-	const { readJson, readDir } = await import("./util/fs.mjs");
-	const cDir = resolveContentDir(projectRoot, model);
+async function getSample(reader, model, locale) {
+	const cDir = contentDirPath(model);
 	if (model.kind === "collection") {
-		const data = await readJson(resolveJsonFilePath(cDir, model, locale));
+		const data = await tryReadJson(reader, contentFilePath(model, locale));
 		if (!data) return null;
 		const firstKey = Object.keys(data)[0];
 		return firstKey ? {
@@ -352,18 +278,18 @@ async function getSample(projectRoot, model, locale) {
 			...data[firstKey]
 		} : null;
 	}
-	if (model.kind === "singleton" || model.kind === "dictionary") return readJson(resolveJsonFilePath(cDir, model, locale));
+	if (model.kind === "singleton" || model.kind === "dictionary") return tryReadJson(reader, contentFilePath(model, locale));
 	if (model.kind === "document") {
 		const strategy = resolveLocaleStrategy(model);
 		if (!model.i18n) {
-			const slug = (await readDir(cDir)).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
+			const slug = (await reader.listDirectory(cDir)).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
 			return slug ? {
 				slug,
 				locale
 			} : null;
 		}
 		if (strategy === "file") {
-			const slug = (await readDir(cDir))[0];
+			const slug = (await reader.listDirectory(cDir))[0];
 			return slug ? {
 				slug,
 				locale
@@ -371,20 +297,20 @@ async function getSample(projectRoot, model, locale) {
 		}
 		if (strategy === "suffix") {
 			const suffix = `.${locale}.md`;
-			const slug = (await readDir(cDir)).find((file) => file.endsWith(suffix))?.slice(0, -suffix.length);
+			const slug = (await reader.listDirectory(cDir)).find((file) => file.endsWith(suffix))?.slice(0, -suffix.length);
 			return slug ? {
 				slug,
 				locale
 			} : null;
 		}
 		if (strategy === "directory") {
-			const slug = (await readDir(join(cDir, locale))).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
+			const slug = (await reader.listDirectory(`${cDir}/${locale}`)).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
 			return slug ? {
 				slug,
 				locale
 			} : null;
 		}
-		const slug = (await readDir(cDir)).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
+		const slug = (await reader.listDirectory(cDir)).find((item) => item.endsWith(".md"))?.replace(/\.md$/u, "");
 		return slug ? {
 			slug,
 			locale
@@ -392,6 +318,13 @@ async function getSample(projectRoot, model, locale) {
 	}
 	return null;
 }
+async function tryReadJson(reader, path) {
+	try {
+		return JSON.parse(await reader.readFile(path));
+	} catch {
+		return null;
+	}
+}
 function buildContentPath(model, locale) {
 	const strategy = model.locale_strategy ?? "file";
 	const baseDir = model.content_path ?? `.contentrain/content/${model.domain}/${model.id}`;
@@ -429,13 +362,36 @@ function generateImportSnippet(model, stack, locale) {
 	return snippets;
 }
 //#endregion
+//#region src/tools/guards.ts
+/**
+* Emit a uniform "capability not available" response for tools that
+* require local filesystem access but are being driven by a remote
+* provider (HTTP + GitHubProvider at the moment). The agent can use
+* `capability_required` to decide whether to retry against a different
+* transport or surface the limitation to the user.
+*/
+function capabilityError(tool, capability) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				error: `${tool} requires local filesystem access.`,
+				capability_required: capability,
+				hint: "This tool is unavailable when MCP is driven by a remote provider (e.g. GitHubProvider). Use a LocalProvider or the stdio transport."
+			})
+		}],
+		isError: true
+	};
+}
+//#endregion
 //#region src/tools/setup.ts
-function registerSetupTools(server, projectRoot) {
+function registerSetupTools(server, _provider, projectRoot) {
 	server.tool("contentrain_init", "Initialize .contentrain/ structure. Changes are auto-committed to git — do NOT manually create .contentrain/ files.", {
 		stack: z.string().optional().describe("Framework stack (nuxt, next, astro, svelte, react-vite, other). Auto-detected if omitted."),
 		locales: z.array(z.string()).optional().describe("Supported locales. Default: [\"en\"]"),
 		domains: z.array(z.string()).optional().describe("Content domains. Default: auto-suggested")
 	}, TOOL_ANNOTATIONS["contentrain_init"], async ({ stack, locales, domains }) => {
+		if (!projectRoot) return capabilityError("contentrain_init", "localWorktree");
 		if (await pathExists(join(contentrainDir(projectRoot), "config.json"))) return {
 			content: [{
 				type: "text",
@@ -449,7 +405,15 @@ function registerSetupTools(server, projectRoot) {
 		const detectedStack = stack ?? await detectStack(projectRoot);
 		const supportedLocales = locales ?? ["en"];
 		const suggestedDomains = domains ?? suggestDomains(projectRoot);
-		if (!await pathExists(join(projectRoot, ".git"))) await simpleGit(projectRoot).init();
+		const hasGit = await pathExists(join(projectRoot, ".git"));
+		const git = simpleGit(projectRoot);
+		if (!hasGit) await git.init();
+		if (!await git.raw([
+			"rev-list",
+			"-n",
+			"1",
+			"--all"
+		]).then((out) => out.trim().length > 0).catch(() => false)) await git.commit("initial commit", { "--allow-empty": null });
 		const initHealth = await checkBranchHealth(projectRoot);
 		if (initHealth.blocked) return {
 			content: [{
@@ -562,6 +526,7 @@ function registerSetupTools(server, projectRoot) {
 		locales: z.array(z.string()).optional().describe("Override locales"),
 		with_sample_content: z.boolean().optional().default(true).describe("Include sample content (default: true)")
 	}, TOOL_ANNOTATIONS["contentrain_scaffold"], async ({ template: templateId, locales, with_sample_content }) => {
+		if (!projectRoot) return capabilityError("contentrain_scaffold", "localWorktree");
 		const config = await readConfig(projectRoot);
 		if (!config) return {
 			content: [{
@@ -717,9 +682,63 @@ async function mergeVocabulary(projectRoot, newTerms, _locales) {
 	return added;
 }
 //#endregion
+//#region src/tools/commit-plan.ts
+/**
+* Commit a plan's changes through whichever provider is wired into the
+* tool handler. Encapsulates the LocalProvider vs remote RepoProvider
+* dispatch that every write-side tool (content_save, content_delete,
+* model_save, model_delete) used to inline:
+*
+* - **LocalProvider** — goes through the worktree-backed transaction.
+*   `context` payload is threaded as an extra write-through and the
+*   transaction layer decides `auto-merged` vs `pending-review` based on
+*   the project's configured workflow. Selective-sync result is surfaced
+*   to the caller via `sync`.
+*
+* - **Any other RepoProvider** — the context.json write becomes an extra
+*   `FileChange` bundled into the plan so the whole commit lands
+*   atomically through the generic `RepoWriter.applyPlan`. Remote flows
+*   always report `pending-review`; Studio (or whatever orchestrator is
+*   driving the server) owns the merge.
+*
+* The return shape is deliberately uniform so callers don't have to
+* branch on provider type again.
+*/
+async function commitThroughProvider(provider, input) {
+	const { branch, changes, message, contextPayload } = input;
+	if (provider instanceof LocalProvider) {
+		const result = await provider.applyPlan({
+			branch,
+			changes,
+			message,
+			context: contextPayload
+		});
+		return {
+			commitSha: result.sha,
+			workflowAction: result.workflowAction,
+			sync: result.sync
+		};
+	}
+	const contextChange = await buildContextChange(new OverlayReader(provider, changes), contextPayload);
+	const allChanges = [...changes, contextChange].toSorted((a, b) => a.path.localeCompare(b.path));
+	return {
+		commitSha: (await provider.applyPlan({
+			branch,
+			changes: allChanges,
+			message,
+			author: {
+				name: "Contentrain",
+				email: "mcp@contentrain.io"
+			},
+			base: CONTENTRAIN_BRANCH
+		})).sha,
+		workflowAction: "pending-review"
+	};
+}
+//#endregion
 //#region src/tools/model.ts
 const fieldDefSchema = fieldDefZodSchema;
-function registerModelTools(server, projectRoot) {
+function registerModelTools(server, provider, projectRoot) {
 	server.tool("contentrain_model_save", "Create or update a model definition. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.", {
 		id: z.string().describe("Model ID (kebab-case, e.g. \"blog-post\")"),
 		name: z.string().describe("Human-readable name"),
@@ -741,7 +760,7 @@ function registerModelTools(server, projectRoot) {
 			"none"
 		]).optional().describe("How locale is encoded in file names. Default: \"file\"")
 	}, TOOL_ANNOTATIONS["contentrain_model_save"], async (input) => {
-		const config = await readConfig(projectRoot);
+		const config = await readConfig(provider);
 		if (!config) return {
 			content: [{
 				type: "text",
@@ -767,19 +786,20 @@ function registerModelTools(server, projectRoot) {
 			}],
 			isError: true
 		};
-		const health = await checkBranchHealth(projectRoot);
-		if (health.blocked) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					error: health.message,
-					action: "blocked",
-					hint: "Merge or delete old contentrain/* branches before creating new ones."
-				}, null, 2)
-			}],
-			isError: true
-		};
-		const action = await readModel(projectRoot, input.id) ? "updated" : "created";
+		if (provider instanceof LocalProvider) {
+			const health = await checkBranchHealth(provider.projectRoot);
+			if (health.blocked) return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						error: health.message,
+						action: "blocked",
+						hint: "Merge or delete old contentrain/* branches before creating new ones."
+					}, null, 2)
+				}],
+				isError: true
+			};
+		}
 		const model = {
 			id: input.id,
 			name: input.name,
@@ -791,52 +811,28 @@ function registerModelTools(server, projectRoot) {
 			content_path: input.content_path,
 			locale_strategy: input.locale_strategy
 		};
+		const savePlan = await planModelSave(provider, { model });
+		const action = savePlan.result.action;
 		const branch = buildBranchName("model", input.id);
-		const tx = await createTransaction(projectRoot, branch);
+		const message = `[contentrain] ${action}: ${input.id}`;
+		const contextPayload = {
+			tool: "contentrain_model_save",
+			model: input.id
+		};
+		let commitSha;
+		let workflowAction;
+		let sync;
 		try {
-			await tx.write(async (wt) => {
-				await writeModel(wt, model);
+			const result = await commitThroughProvider(provider, {
+				branch,
+				changes: savePlan.changes,
+				message,
+				contextPayload
 			});
-			await tx.commit(`[contentrain] ${action}: ${input.id}`, {
-				tool: "contentrain_model_save",
-				model: input.id
-			});
-			const gitResult = await tx.complete();
-			const defaultLocale = config.locales.default;
-			const contentDir = resolveContentDir(projectRoot, model);
-			const contentPath = model.content_path ?? `.contentrain/content/${input.domain}/${input.id}`;
-			let exampleFilePath;
-			if (model.kind === "document") exampleFilePath = resolveMdFilePath(contentDir, model, defaultLocale, "{slug}");
-			else exampleFilePath = resolveJsonFilePath(contentDir, model, defaultLocale);
-			const displayPath = exampleFilePath.replace(projectRoot + "/", "").replace(projectRoot, "");
-			const importSnippet = { generic: `import data from '${displayPath}'` };
-			if (config.stack === "nuxt") importSnippet["nuxt"] = model.kind === "document" ? `const { data } = await useAsyncData(() => queryContent('${model.domain}/${model.id}').locale('${defaultLocale}').find())` : `const { data } = await useFetch('/api/content/${model.id}?locale=${defaultLocale}')`;
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					status: "committed",
-					message: "Model saved and committed to git. Do NOT manually edit .contentrain/ files.",
-					action,
-					model: input.id,
-					validation: {
-						valid: true,
-						errors: []
-					},
-					git: {
-						branch,
-						action: gitResult.action,
-						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
-					},
-					context_updated: true,
-					content_path: contentPath + "/",
-					example_file: displayPath,
-					import_snippet: importSnippet,
-					next_steps: ["Add content with contentrain_content_save"]
-				}, null, 2)
-			}] };
+			commitSha = result.commitSha;
+			workflowAction = result.workflowAction;
+			sync = result.sync;
 		} catch (error) {
-			await tx.cleanup();
 			return {
 				content: [{
 					type: "text",
@@ -844,41 +840,76 @@ function registerModelTools(server, projectRoot) {
 				}],
 				isError: true
 			};
-		} finally {
-			await tx.cleanup();
 		}
+		const defaultLocale = config.locales.default;
+		const contentPath = model.content_path ?? `.contentrain/content/${input.domain}/${input.id}`;
+		let displayPath;
+		let importSnippet;
+		if (projectRoot) {
+			const contentDir = resolveContentDir(projectRoot, model);
+			displayPath = (model.kind === "document" ? resolveMdFilePath(contentDir, model, defaultLocale, "{slug}") : resolveJsonFilePath(contentDir, model, defaultLocale)).replace(projectRoot + "/", "").replace(projectRoot, "");
+			importSnippet = { generic: `import data from '${displayPath}'` };
+			if (config.stack === "nuxt") importSnippet["nuxt"] = model.kind === "document" ? `const { data } = await useAsyncData(() => queryContent('${model.domain}/${model.id}').locale('${defaultLocale}').find())` : `const { data } = await useFetch('/api/content/${model.id}?locale=${defaultLocale}')`;
+		}
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				status: "committed",
+				message: "Model saved and committed to git. Do NOT manually edit .contentrain/ files.",
+				action,
+				model: input.id,
+				validation: {
+					valid: true,
+					errors: []
+				},
+				git: {
+					branch,
+					action: workflowAction,
+					commit: commitSha,
+					...sync ? { sync } : {}
+				},
+				context_updated: true,
+				content_path: contentPath + "/",
+				...displayPath ? { example_file: displayPath } : {},
+				...importSnippet ? { import_snippet: importSnippet } : {},
+				next_steps: ["Add content with contentrain_content_save"]
+			}, null, 2)
+		}] };
 	});
 	server.tool("contentrain_model_delete", "Delete a model and its content/meta. Changes are auto-committed to git — do NOT manually edit .contentrain/ files.", {
 		model: z.string().describe("Model ID to delete"),
 		confirm: z.literal(true).describe("Must be true to confirm deletion")
 	}, TOOL_ANNOTATIONS["contentrain_model_delete"], async ({ model: modelId }) => {
-		if (!await readConfig(projectRoot)) return {
+		if (!await readConfig(provider)) return {
 			content: [{
 				type: "text",
 				text: JSON.stringify({ error: "Project not initialized." })
 			}],
 			isError: true
 		};
-		if (!await readModel(projectRoot, modelId)) return {
+		const existing = await readModel(provider, modelId);
+		if (!existing) return {
 			content: [{
 				type: "text",
 				text: JSON.stringify({ error: `Model "${modelId}" not found` })
 			}],
 			isError: true
 		};
-		const deleteHealth = await checkBranchHealth(projectRoot);
-		if (deleteHealth.blocked) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					error: deleteHealth.message,
-					action: "blocked",
-					hint: "Merge or delete old contentrain/* branches before creating new ones."
-				}, null, 2)
-			}],
-			isError: true
-		};
-		const refs = await checkReferences(projectRoot, modelId);
+		if (provider instanceof LocalProvider) {
+			const deleteHealth = await checkBranchHealth(provider.projectRoot);
+			if (deleteHealth.blocked) return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						error: deleteHealth.message,
+						action: "blocked",
+						hint: "Merge or delete old contentrain/* branches before creating new ones."
+					}, null, 2)
+				}],
+				isError: true
+			};
+		}
+		const refs = await checkReferences(provider, modelId);
 		if (refs.length > 0) return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -888,18 +919,26 @@ function registerModelTools(server, projectRoot) {
 				next_steps: ["Remove relation fields from referencing models first"]
 			}, null, 2)
 		}] };
+		const deletePlan = await planModelDelete(provider, { model: existing });
 		const branch = buildBranchName("model", modelId);
-		const tx = await createTransaction(projectRoot, branch);
+		const message = `[contentrain] delete: ${modelId}`;
+		const contextPayload = {
+			tool: "contentrain_model_delete",
+			model: modelId
+		};
+		let commitSha;
+		let workflowAction;
+		let sync;
 		try {
-			let filesRemoved = [];
-			await tx.write(async (wt) => {
-				filesRemoved = await deleteModel(wt, modelId);
+			const result = await commitThroughProvider(provider, {
+				branch,
+				changes: deletePlan.changes,
+				message,
+				contextPayload
 			});
-			await tx.commit(`[contentrain] delete: ${modelId}`, {
-				tool: "contentrain_model_delete",
-				model: modelId
-			});
-			const gitResult = await tx.complete();
+			commitSha = result.commitSha;
+			workflowAction = result.workflowAction;
+			sync = result.sync;
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
@@ -908,16 +947,15 @@ function registerModelTools(server, projectRoot) {
 					deleted: true,
 					git: {
 						branch,
-						action: gitResult.action,
-						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
+						action: workflowAction,
+						commit: commitSha,
+						...sync ? { sync } : {}
 					},
-					files_removed: filesRemoved,
+					files_removed: deletePlan.result,
 					context_updated: true
 				}, null, 2)
 			}] };
 		} catch (error) {
-			await tx.cleanup();
 			return {
 				content: [{
 					type: "text",
@@ -925,15 +963,13 @@ function registerModelTools(server, projectRoot) {
 				}],
 				isError: true
 			};
-		} finally {
-			await tx.cleanup();
 		}
 	});
 }
 const validateModel = validateModelDefinition;
 //#endregion
 //#region src/tools/content.ts
-function registerContentTools(server, projectRoot) {
+function registerContentTools(server, provider, projectRoot) {
 	server.tool("contentrain_content_save", "Save content entries. Entry format varies by model kind: DICTIONARY — provide \"locale\" and \"data\" (flat key-value, all string values); \"id\" and \"slug\" are ignored; data keys are the identities. COLLECTION — provide \"locale\" and \"data\"; \"id\" is optional (auto-generated if omitted); \"slug\" is ignored. DOCUMENT — provide \"slug\" (required), \"locale\", and \"data\"; use the \"body\" key inside data for markdown content. SINGLETON — provide only \"locale\" and \"data\". Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.", {
 		model: z.string().describe("Model ID"),
 		entries: z.array(z.object({
@@ -945,7 +981,7 @@ function registerContentTools(server, projectRoot) {
 			expire_at: z.string().optional().describe("ISO 8601 date for scheduled expiry (stored in meta, must be after publish_at)")
 		})).describe("Content entries to save")
 	}, TOOL_ANNOTATIONS["contentrain_content_save"], async (input) => {
-		const config = await readConfig(projectRoot);
+		const config = await readConfig(provider);
 		if (!config) return {
 			content: [{
 				type: "text",
@@ -953,7 +989,7 @@ function registerContentTools(server, projectRoot) {
 			}],
 			isError: true
 		};
-		const model = await readModel(projectRoot, input.model);
+		const model = await readModel(provider, input.model);
 		if (!model) return {
 			content: [{
 				type: "text",
@@ -1001,57 +1037,61 @@ function registerContentTools(server, projectRoot) {
 			if (entry.publish_at !== void 0) entry.data["publish_at"] = entry.publish_at;
 			if (entry.expire_at !== void 0) entry.data["expire_at"] = entry.expire_at;
 		}
-		const health = await checkBranchHealth(projectRoot);
-		if (health.blocked) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					error: health.message,
-					action: "blocked",
-					hint: "Merge or delete old contentrain/* branches before creating new ones."
-				}, null, 2)
-			}],
-			isError: true
-		};
-		const branch = buildBranchName("content", input.model);
-		const tx = await createTransaction(projectRoot, branch);
+		if (provider instanceof LocalProvider) {
+			const health = await checkBranchHealth(provider.projectRoot);
+			if (health.blocked) return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						error: health.message,
+						action: "blocked",
+						hint: "Merge or delete old contentrain/* branches before creating new ones."
+					}, null, 2)
+				}],
+				isError: true
+			};
+		}
+		const vocabulary = await readVocabulary(provider);
+		let plan;
 		try {
-			let results;
-			let entryIds = [];
-			await tx.write(async (wt) => {
-				results = await writeContent(wt, model, input.entries, config);
-				entryIds = results.map((r) => r.id ?? r.slug ?? r.locale).filter(Boolean);
+			plan = await planContentSave(provider, {
+				model,
+				entries: input.entries,
+				config,
+				vocabulary
 			});
-			await tx.commit(`[contentrain] content: ${input.model}`, {
-				tool: "contentrain_content_save",
-				model: input.model,
-				locale: input.entries[0]?.locale,
-				entries: entryIds
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({ error: `Content save failed: ${error instanceof Error ? error.message : String(error)}` })
+				}],
+				isError: true
+			};
+		}
+		const entryIds = plan.result.map((r) => r.id ?? r.slug ?? r.locale).filter((v) => Boolean(v));
+		const branch = buildBranchName("content", input.model);
+		const message = `[contentrain] content: ${input.model}`;
+		const contextPayload = {
+			tool: "contentrain_content_save",
+			model: input.model,
+			locale: input.entries[0]?.locale,
+			entries: entryIds
+		};
+		let commitSha;
+		let workflowAction;
+		let sync;
+		try {
+			const result = await commitThroughProvider(provider, {
+				branch,
+				changes: plan.changes,
+				message,
+				contextPayload
 			});
-			const gitResult = await tx.complete();
-			const validationResult = await validateProject(projectRoot, { model: input.model });
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					status: "committed",
-					message: "Content saved and committed to git. Do NOT manually edit .contentrain/ files.",
-					results,
-					git: {
-						branch,
-						action: gitResult.action,
-						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
-					},
-					validation: {
-						valid: validationResult.valid,
-						errors: validationResult.issues.filter((i) => i.severity === "error").map((i) => i.message)
-					},
-					context_updated: true,
-					next_steps: [...!validationResult.valid ? ["WARNING: Content has validation errors — run contentrain_validate for details"] : [], ...model.kind === "collection" ? ["Use contentrain_content_list to verify", "Add more entries or publish"] : ["Use contentrain_content_list to verify"]]
-				}, null, 2)
-			}] };
+			commitSha = result.commitSha;
+			workflowAction = result.workflowAction;
+			sync = result.sync;
 		} catch (error) {
-			await tx.cleanup();
 			return {
 				content: [{
 					type: "text",
@@ -1059,9 +1099,37 @@ function registerContentTools(server, projectRoot) {
 				}],
 				isError: true
 			};
-		} finally {
-			await tx.cleanup();
 		}
+		const validationResult = projectRoot ? await validateProject(projectRoot, { model: input.model }) : await validateProject(new OverlayReader(provider, plan.changes), { model: input.model });
+		const allAdvisories = plan.result.flatMap((r) => r.advisories ?? []);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				status: "committed",
+				message: "Content saved and committed to git. Do NOT manually edit .contentrain/ files.",
+				results: plan.result,
+				git: {
+					branch,
+					action: workflowAction,
+					commit: commitSha,
+					...sync ? { sync } : {}
+				},
+				...allAdvisories.length > 0 ? {
+					advisories: allAdvisories,
+					advisory_note: "Save succeeded. Review these warnings and consider consolidating duplicate values."
+				} : {},
+				validation: {
+					valid: validationResult.valid,
+					errors: validationResult.issues.filter((i) => i.severity === "error").map((i) => i.message)
+				},
+				context_updated: true,
+				next_steps: [
+					...allAdvisories.length > 0 ? ["ADVISORY: Duplicate values detected — review advisories above"] : [],
+					...!validationResult.valid ? ["WARNING: Content has validation errors — run contentrain_validate for details"] : [],
+					...model.kind === "collection" ? ["Use contentrain_content_list to verify", "Add more entries or publish"] : ["Use contentrain_content_list to verify"]
+				]
+			}, null, 2)
+		}] };
 	});
 	server.tool("contentrain_content_delete", "Delete content entries. For dictionaries, use \"keys\" to remove specific keys (omit to delete entire locale file). Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.", {
 		model: z.string().describe("Model ID"),
@@ -1071,14 +1139,14 @@ function registerContentTools(server, projectRoot) {
 		keys: z.array(z.string()).optional().describe("Dictionary only: specific keys to remove. Omit to delete entire locale file."),
 		confirm: z.literal(true).describe("Must be true to confirm deletion")
 	}, TOOL_ANNOTATIONS["contentrain_content_delete"], async (input) => {
-		if (!await readConfig(projectRoot)) return {
+		if (!await readConfig(provider)) return {
 			content: [{
 				type: "text",
 				text: JSON.stringify({ error: "Project not initialized." })
 			}],
 			isError: true
 		};
-		const model = await readModel(projectRoot, input.model);
+		const model = await readModel(provider, input.model);
 		if (!model) return {
 			content: [{
 				type: "text",
@@ -1086,54 +1154,75 @@ function registerContentTools(server, projectRoot) {
 			}],
 			isError: true
 		};
-		const deleteHealth = await checkBranchHealth(projectRoot);
-		if (deleteHealth.blocked) return {
-			content: [{
-				type: "text",
-				text: JSON.stringify({
-					error: deleteHealth.message,
-					action: "blocked",
-					hint: "Merge or delete old contentrain/* branches before creating new ones."
-				}, null, 2)
-			}],
-			isError: true
-		};
-		const branch = buildBranchName("content", input.model);
-		const tx = await createTransaction(projectRoot, branch);
+		if (provider instanceof LocalProvider) {
+			const deleteHealth = await checkBranchHealth(provider.projectRoot);
+			if (deleteHealth.blocked) return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						error: deleteHealth.message,
+						action: "blocked",
+						hint: "Merge or delete old contentrain/* branches before creating new ones."
+					}, null, 2)
+				}],
+				isError: true
+			};
+		}
+		let deletePlan;
 		try {
-			let removed = [];
-			await tx.write(async (wt) => {
-				removed = await deleteContent(wt, model, {
-					id: input.id,
-					slug: input.slug,
-					locale: input.locale,
-					keys: input.keys
-				});
+			deletePlan = await planContentDelete(provider, {
+				model,
+				id: input.id,
+				slug: input.slug,
+				locale: input.locale,
+				keys: input.keys
 			});
-			await tx.commit(`[contentrain] delete content: ${input.model}`, {
-				tool: "contentrain_content_delete",
-				model: input.model,
-				locale: input.locale
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({ error: `Delete failed: ${error instanceof Error ? error.message : String(error)}` })
+				}],
+				isError: true
+			};
+		}
+		const branch = buildBranchName("content", input.model);
+		const message = `[contentrain] delete content: ${input.model}`;
+		const contextPayload = {
+			tool: "contentrain_content_delete",
+			model: input.model,
+			locale: input.locale
+		};
+		let commitSha;
+		let workflowAction;
+		let sync;
+		try {
+			const result = await commitThroughProvider(provider, {
+				branch,
+				changes: deletePlan.changes,
+				message,
+				contextPayload
 			});
-			const gitResult = await tx.complete();
+			commitSha = result.commitSha;
+			workflowAction = result.workflowAction;
+			sync = result.sync;
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
 					status: "committed",
 					message: "Content deleted and committed to git. Do NOT manually edit .contentrain/ files.",
 					deleted: true,
-					files_removed: removed,
+					files_removed: deletePlan.result,
 					git: {
 						branch,
-						action: gitResult.action,
-						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
+						action: workflowAction,
+						commit: commitSha,
+						...sync ? { sync } : {}
 					},
 					context_updated: true
 				}, null, 2)
 			}] };
 		} catch (error) {
-			await tx.cleanup();
 			return {
 				content: [{
 					type: "text",
@@ -1141,8 +1230,6 @@ function registerContentTools(server, projectRoot) {
 				}],
 				isError: true
 			};
-		} finally {
-			await tx.cleanup();
 		}
 	});
 	server.tool("contentrain_content_list", "List content entries (read-only). Returns data from .contentrain/ — do NOT manually create or modify content files.", {
@@ -1153,7 +1240,7 @@ function registerContentTools(server, projectRoot) {
 		limit: z.number().optional().describe("Max entries to return"),
 		offset: z.number().optional().describe("Skip N entries")
 	}, TOOL_ANNOTATIONS["contentrain_content_list"], async (input) => {
-		const config = await readConfig(projectRoot);
+		const config = await readConfig(provider);
 		if (!config) return {
 			content: [{
 				type: "text",
@@ -1161,7 +1248,7 @@ function registerContentTools(server, projectRoot) {
 			}],
 			isError: true
 		};
-		const model = await readModel(projectRoot, input.model);
+		const model = await readModel(provider, input.model);
 		if (!model) return {
 			content: [{
 				type: "text",
@@ -1170,13 +1257,14 @@ function registerContentTools(server, projectRoot) {
 			isError: true
 		};
 		try {
-			const result = await listContent(projectRoot, model, {
+			const listOpts = {
 				locale: input.locale,
 				filter: input.filter,
 				resolve: input.resolve,
 				limit: input.limit,
 				offset: input.offset
-			}, config);
+			};
+			const result = projectRoot ? await listContent(projectRoot, model, listOpts, config) : await listContent(provider, model, listOpts, config);
 			return { content: [{
 				type: "text",
 				text: JSON.stringify(result, null, 2)
@@ -1194,12 +1282,13 @@ function registerContentTools(server, projectRoot) {
 }
 //#endregion
 //#region src/tools/workflow.ts
-function registerWorkflowTools(server, projectRoot) {
+function registerWorkflowTools(server, provider, projectRoot) {
 	server.tool("contentrain_validate", "Validate project content against model schemas. Detects required field violations, type mismatches, broken relations, secret leaks, i18n parity issues, and more. If fix:true, auto-fixes structural issues (canonical sort, orphan meta, missing locale files) — do NOT manually edit .contentrain/ files.", {
 		model: z.string().optional().describe("Model ID to validate (omit for all models)"),
 		fix: z.boolean().optional().describe("Auto-fix structural issues (canonical sort, orphan meta, missing locale files). Default: false")
 	}, TOOL_ANNOTATIONS["contentrain_validate"], async (input) => {
-		if (!await readConfig(projectRoot)) return {
+		if (input.fix && !projectRoot) return capabilityError("contentrain_validate", "localWorktree");
+		if (!await readConfig(provider)) return {
 			content: [{
 				type: "text",
 				text: JSON.stringify({ error: "Project not initialized. Run contentrain_init first." })
@@ -1208,7 +1297,7 @@ function registerWorkflowTools(server, projectRoot) {
 		};
 		try {
 			let result;
-			if (input.fix) {
+			if (input.fix && projectRoot) {
 				const fixHealth = await checkBranchHealth(projectRoot);
 				if (fixHealth.blocked) return {
 					content: [{
@@ -1264,7 +1353,10 @@ function registerWorkflowTools(server, projectRoot) {
 					await tx.cleanup();
 				}
 			}
-			if (!result) result = await validateProject(projectRoot, {
+			if (!result) result = projectRoot ? await validateProject(projectRoot, {
+				model: input.model,
+				fix: false
+			}) : await validateProject(provider, {
 				model: input.model,
 				fix: false
 			});
@@ -1295,6 +1387,7 @@ function registerWorkflowTools(server, projectRoot) {
 		branches: z.array(z.string()).optional().describe("Specific branch names to push (omit for all contentrain/* branches)"),
 		message: z.string().optional().describe("Optional message for the push operation")
 	}, TOOL_ANNOTATIONS["contentrain_submit"], async (input) => {
+		if (!provider.capabilities.localWorktree || !provider.capabilities.pushRemote || !projectRoot) return capabilityError("contentrain_submit", "localWorktree");
 		const config = await readConfig(projectRoot);
 		if (!config) return {
 			content: [{
@@ -1407,6 +1500,7 @@ function registerWorkflowTools(server, projectRoot) {
 		branch: z.string().describe("Branch name to merge (e.g. cr/normalize/extract/...)"),
 		confirm: z.literal(true).describe("Must be true to confirm the merge")
 	}, TOOL_ANNOTATIONS["contentrain_merge"], async (input) => {
+		if (!provider.capabilities.localWorktree || !projectRoot) return capabilityError("contentrain_merge", "localWorktree");
 		if (!await readConfig(projectRoot)) return {
 			content: [{
 				type: "text",
@@ -1453,7 +1547,7 @@ function registerWorkflowTools(server, projectRoot) {
 }
 //#endregion
 //#region src/tools/normalize.ts
-function registerNormalizeTools(server, projectRoot) {
+function registerNormalizeTools(server, provider, projectRoot) {
 	server.tool("contentrain_scan", "Scan project source code for content strings. Three modes: \"graph\" builds import/component graph for project intelligence, \"candidates\" extracts string literals with pre-filtering and pagination, \"summary\" provides quick overview stats. Read-only — no changes to disk or git. MCP finds strings deterministically; the agent decides what is content. Recommended workflow: start with \"summary\" or \"graph\" for orientation, then paginate through \"candidates\" to evaluate strings.", {
 		mode: z.enum([
 			"graph",
@@ -1468,6 +1562,7 @@ function registerNormalizeTools(server, projectRoot) {
 		min_length: z.number().optional().describe("Candidates mode: minimum string length. Default: 2"),
 		max_length: z.number().optional().describe("Candidates mode: maximum string length. Default: 500")
 	}, TOOL_ANNOTATIONS["contentrain_scan"], async (input) => {
+		if (!provider.capabilities.astScan || !projectRoot) return capabilityError("contentrain_scan", "astScan");
 		if (!await readConfig(projectRoot)) return {
 			content: [{
 				type: "text",
@@ -1594,6 +1689,8 @@ function registerNormalizeTools(server, projectRoot) {
 			import_statement: z.string().optional().describe("Import to add if needed")
 		})).optional().describe("Reuse mode: patches to apply (max 100)")
 	}, TOOL_ANNOTATIONS["contentrain_apply"], async (input) => {
+		const capability = input.mode === "reuse" ? "sourceWrite" : "sourceRead";
+		if (!provider.capabilities[capability] || !projectRoot) return capabilityError("contentrain_apply", capability);
 		if (!await readConfig(projectRoot)) return {
 			content: [{
 				type: "text",
@@ -1695,7 +1792,7 @@ function registerNormalizeTools(server, projectRoot) {
 }
 //#endregion
 //#region src/tools/bulk.ts
-function registerBulkTools(server, projectRoot) {
+function registerBulkTools(server, _provider, projectRoot) {
 	server.tool("contentrain_bulk", "Batch operations on content entries. All operations are auto-committed to git.", {
 		operation: z.enum([
 			"copy_locale",
@@ -1715,6 +1812,7 @@ function registerBulkTools(server, projectRoot) {
 		]).optional().describe("New status for update_status"),
 		confirm: z.boolean().optional().describe("Must be true for delete_entries")
 	}, TOOL_ANNOTATIONS["contentrain_bulk"], async (input) => {
+		if (!projectRoot) return capabilityError("contentrain_bulk", "localWorktree");
 		const config = await readConfig(projectRoot);
 		if (!config) return {
 			content: [{
@@ -2011,25 +2109,58 @@ function registerBulkTools(server, projectRoot) {
 	});
 }
 //#endregion
+//#region src/tools/doctor.ts
+function registerDoctorTools(server, _provider, projectRoot) {
+	server.tool("contentrain_doctor", "Project health report (read-only). Returns structured checks: git, node, .contentrain/ structure, model parse, orphan content, branch pressure, SDK freshness. Pass `usage: true` for a deeper analysis of content-key references in source files (unused keys, duplicate dictionary values, locale coverage). Local-filesystem only — unavailable over remote providers.", { usage: z.boolean().optional().default(false).describe("Run the heavier usage-analysis branch (unused keys, duplicate values, missing locales). Default: false.") }, TOOL_ANNOTATIONS["contentrain_doctor"], async ({ usage }) => {
+		if (!projectRoot) return capabilityError("contentrain_doctor", "localWorktree");
+		const report = await runDoctor(projectRoot, { usage });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(report, null, 2)
+		}] };
+	});
+}
+//#endregion
 //#region package.json
-var version = "1.2.1";
+var version = "1.4.0";
 //#endregion
 //#region src/server.ts
-function createServer(projectRoot) {
+function createServer(input) {
+	const { provider, projectRoot } = resolveServerContext(input);
 	const server = new McpServer({
 		name: "contentrain-mcp",
 		version
 	});
-	registerContextTools(server, projectRoot);
-	registerSetupTools(server, projectRoot);
-	registerModelTools(server, projectRoot);
-	registerContentTools(server, projectRoot);
-	registerWorkflowTools(server, projectRoot);
-	registerNormalizeTools(server, projectRoot);
-	registerBulkTools(server, projectRoot);
+	registerContextTools(server, provider, projectRoot);
+	registerSetupTools(server, provider, projectRoot);
+	registerModelTools(server, provider, projectRoot);
+	registerContentTools(server, provider, projectRoot);
+	registerWorkflowTools(server, provider, projectRoot);
+	registerNormalizeTools(server, provider, projectRoot);
+	registerBulkTools(server, provider, projectRoot);
+	registerDoctorTools(server, provider, projectRoot);
 	return server;
 }
+function resolveServerContext(input) {
+	if (typeof input === "string") return {
+		provider: new LocalProvider(input),
+		projectRoot: input
+	};
+	if (input.provider) {
+		let projectRoot = input.projectRoot;
+		if (!projectRoot && input.provider instanceof LocalProvider) projectRoot = input.provider.projectRoot;
+		return {
+			provider: input.provider,
+			projectRoot
+		};
+	}
+	if (input.projectRoot) return {
+		provider: new LocalProvider(input.projectRoot),
+		projectRoot: input.projectRoot
+	};
+	throw new Error("createServer: either `provider` or `projectRoot` must be provided");
+}
 //#endregion
 export { createServer as t };
 
-//# sourceMappingURL=server-Dtq8vqbK.mjs.map
+//# sourceMappingURL=server-BkhhtEE2.mjs.map