@hanna84/mcp-writing 1.5.2 → 1.6.1

package/CHANGELOG.md

@@ -4,11 +4,31 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v1.6.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.6.0...v1.6.1)
+
+- fix: preflight prose writes and make canonical sheet creation idempotent [`#46`](https://github.com/hannasdev/mcp-writing.git
+/pull/46)
+
+#### [v1.6.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.5.2...v1.6.0)
+
+> 19 April 2026
+
+- feat: add permission preflight diagnostics and ops contract [`#45`](https://github.com/hannasdev/mcp-writing.git
+/pull/45)
+- Release 1.6.0 [`bfab6d2`](https://github.com/hannasdev/mcp-writing.git
+/commit/bfab6d205f4c60bf9e59cb4097796fc7cef63158)
+
 #### [v1.5.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.5.1...v1.5.2)
 
+> 19 April 2026
+
 - fix: avoid nested scenes/projects paths on import [`#44`](https://github.com/hannasdev/mcp-writing.git
 /pull/44)
+- Release 1.5.2 [`47f7c6c`](https://github.com/hannasdev/mcp-writing.git
+/commit/47f7c6c9ddbc4244b8a62b1dc37c86eb914aafbc)
 
 #### [v1.5.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.5.0...v1.5.1)

package/README.md

@@ -34,6 +34,24 @@ npm --version     # should be 8.0.0 or later
 git --version     # should be installed
 ```
 
+## Permission Contract (Recommended For All Users)
+
+To keep MCP write tools reliable across local runs, Docker, and AI agents, use this contract:
+
+1. The same non-root user should own and write the sync directory.
+2. Containerized runs should use host UID/GID, not root.
+3. If ownership drifts (for example root-owned files), repair once on host and continue.
+
+Repair commands (host):
+
+```sh
+sudo chown -R "$(id -u):$(id -g)" /path/to/sync-dir
+find /path/to/sync-dir -type d -exec chmod u+rwx {} +
+find /path/to/sync-dir -type f -exec chmod u+rw {} +
+```
+
+You can also inspect ownership/writability status at runtime via `get_runtime_config`.
+
 ## First-time setup path (recommended)
 
 If this is your first time, follow these steps in order:
@@ -321,6 +339,7 @@ Paginated tools (`find_scenes`, `get_arc`, `list_threads`, `get_thread_arc`, `se
 # docker-compose.yml snippet
 writing-mcp:
   build: .
+  user: "${UID:-1000}:${GID:-1000}"
   environment:
     WRITING_SYNC_DIR: /sync
     DB_PATH: /data/writing.db
@@ -338,6 +357,8 @@ volumes:
   writing-mcp-data:
 ```
 
+If you want explicit host mapping, set `UID` and `GID` in your shell or a `.env` file next to `docker-compose.yml`.
+
 Then register in your OpenClaw config:
 
 ```json

package/index.js

@@ -7,7 +7,7 @@ import matter from "gray-matter";
 import yaml from "js-yaml";
 import { z } from "zod";
 import { openDb } from "./db.js";
-import { syncAll, isSyncDirWritable, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
+import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDiagnostics, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
@@ -180,28 +180,72 @@ function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId,
   const { dir } = resolveWorldEntityDir({ kind, projectId, universeId, name });
   const prosePath = path.join(dir, "sheet.md");
   const metaPath = sidecarPath(prosePath);
-  if (fs.existsSync(prosePath) || fs.existsSync(metaPath)) {
-    throw new Error(`Canonical sheet already exists at ${dir}`);
+  const hadProse = fs.existsSync(prosePath);
+  const hadMeta = fs.existsSync(metaPath);
+
+  let shouldWriteMeta = !hadMeta;
+  let payload;
+  const derivedId = `${prefix}-${slug}`;
+  if (hadMeta) {
+    let parsedMeta;
+    try {
+      parsedMeta = yaml.load(fs.readFileSync(metaPath, "utf8"));
+    } catch (err) {
+      throw new Error(
+        `Existing metadata sidecar is invalid YAML at ${metaPath}: ${err.message}`,
+        { cause: err }
+      );
+    }
+
+    if (parsedMeta != null && (typeof parsedMeta !== "object" || Array.isArray(parsedMeta))) {
+      throw new Error(`Existing metadata sidecar must be a YAML mapping at ${metaPath}.`);
+    }
+
+    const existingMeta = parsedMeta ?? {};
+
+    const backfilledId = existingMeta[idKey] ?? derivedId;
+    const backfilledName = existingMeta.name ?? name;
+    shouldWriteMeta = existingMeta[idKey] == null || existingMeta.name == null;
+    payload = shouldWriteMeta
+      ? {
+        ...existingMeta,
+        [idKey]: backfilledId,
+        name: backfilledName,
+      }
+      : existingMeta;
+  } else {
+    payload = {
+      [idKey]: derivedId,
+      name,
+      ...(meta ?? {}),
+    };
   }
 
   fs.mkdirSync(dir, { recursive: true });
-  const defaultSheet = kind === "character"
-    ? renderCharacterSheetTemplate(name)
-    : renderPlaceSheetTemplate(name);
-  fs.writeFileSync(prosePath, `${notes?.trim() ?? defaultSheet}${(notes?.trim() ?? defaultSheet) ? "\n" : ""}`, "utf8");
+
+  if (!hadProse) {
+    const defaultSheet = kind === "character"
+      ? renderCharacterSheetTemplate(name)
+      : renderPlaceSheetTemplate(name);
+    const body = notes?.trim() ?? defaultSheet;
+    fs.writeFileSync(prosePath, `${body}${body ? "\n" : ""}`, "utf8");
+  }
+
   if (kind === "character") {
-    fs.writeFileSync(path.join(dir, "arc.md"), `${renderCharacterArcTemplate(name)}\n`, "utf8");
+    const arcPath = path.join(dir, "arc.md");
+    if (!fs.existsSync(arcPath)) {
+      fs.writeFileSync(arcPath, `${renderCharacterArcTemplate(name)}\n`, "utf8");
+    }
+  }
+
+  if (shouldWriteMeta) {
+    fs.writeFileSync(metaPath, yaml.dump(payload, { lineWidth: 120 }), "utf8");
   }
-  const payload = {
-    [idKey]: `${prefix}-${slug}`,
-    name,
-    ...meta,
-  };
-  fs.writeFileSync(metaPath, yaml.dump(payload, { lineWidth: 120 }), "utf8");
 
   syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 
   return {
+    created: !hadProse && !hadMeta,
     id: payload[idKey],
     prose_path: prosePath,
     meta_path: metaPath,
@@ -220,6 +264,7 @@ process.stderr.write(`[mcp-writing] DB path: ${DB_PATH_DISPLAY}\n`);
 
 // Check sync dir writability once at startup (needed for Phase 2 sidecar writes)
 const SYNC_DIR_WRITABLE = isSyncDirWritable(SYNC_DIR);
+const SYNC_OWNERSHIP_DIAGNOSTICS = getSyncOwnershipDiagnostics(SYNC_DIR);
 if (!SYNC_DIR_WRITABLE) {
   process.stderr.write(`[mcp-writing] WARNING: sync dir is not writable — sidecar auto-migration and metadata write-back will be unavailable\n`);
 }
@@ -263,6 +308,24 @@ function getRuntimeDiagnostics() {
     recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
   }
 
+  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths > 0) {
+    warnings.push(
+      `OWNERSHIP_MISMATCH: ${SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid}.`
+    );
+    recommendations.push(
+      `Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${SYNC_DIR_ABS}"`
+    );
+    recommendations.push(
+      "For Docker, run container as host user (compose: user: \"${UID:-1000}:${GID:-1000}\"). Optionally set UID/GID explicitly in a .env file."
+    );
+  }
+
+  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths > 0) {
+    warnings.push(
+      `ROOT_OWNED_PATHS: ${SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
+    );
+  }
+
   if (!GIT_AVAILABLE) {
     warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
     recommendations.push("Install git in the runtime image/environment.");
@@ -396,13 +459,14 @@ function createMcpServer() {
   // ---- get_runtime_config --------------------------------------------------
   s.tool(
     "get_runtime_config",
-    "Show the active runtime paths and capabilities for this server instance (sync dir, database path, writability, and git availability). Use this to verify which manuscript location is currently connected.",
+    "Show the active runtime paths and capabilities for this server instance (sync dir, database path, writability, permission diagnostics, and git availability). Use this to verify which manuscript location is currently connected.",
     {},
     async () => {
       return jsonResponse({
         sync_dir: SYNC_DIR_ABS,
         db_path: DB_PATH_DISPLAY,
         sync_dir_writable: SYNC_DIR_WRITABLE,
+        permission_diagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
         git_available: GIT_AVAILABLE,
         git_enabled: GIT_ENABLED,
         http_port: HTTP_PORT,
@@ -691,7 +755,7 @@ function createMcpServer() {
   // ---- create_character_sheet ---------------------------------------------
   s.tool(
     "create_character_sheet",
-    "Create a canonical character sheet folder with sheet.md and sheet.meta.yaml so the character can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    "Create or reuse a canonical character sheet folder with sheet.md and sheet.meta.yaml so the character can be indexed immediately. If the folder already exists, missing canonical files are backfilled and the existing sheet is preserved.",
     {
       name: z.string().describe("Display name of the character (e.g. 'Mira Nystrom')."),
       project_id: z.string().optional().describe("Project scope for a book-local character (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
@@ -713,7 +777,7 @@ function createMcpServer() {
       }
 
       try {
-        const created = createCanonicalWorldEntity({
+        const result = createCanonicalWorldEntity({
           kind: "character",
           name,
           notes,
@@ -722,7 +786,7 @@ function createMcpServer() {
           meta: fields ?? {},
         });
 
-        return jsonResponse({ ok: true, action: "created", kind: "character", ...created });
+        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "character", ...result });
       } catch (err) {
         return errorResponse("IO_ERROR", `Failed to create character sheet: ${err.message}`);
       }
@@ -757,7 +821,7 @@ function createMcpServer() {
   // ---- create_place_sheet -------------------------------------------------
   s.tool(
     "create_place_sheet",
-    "Create a canonical place sheet folder with sheet.md and sheet.meta.yaml so the place can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    "Create or reuse a canonical place sheet folder with sheet.md and sheet.meta.yaml so the place can be indexed immediately. If the folder already exists, missing canonical files are backfilled and the existing sheet is preserved.",
     {
       name: z.string().describe("Display name of the place (e.g. 'University Hospital')."),
       project_id: z.string().optional().describe("Project scope for a book-local place (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
@@ -777,7 +841,7 @@ function createMcpServer() {
       }
 
       try {
-        const created = createCanonicalWorldEntity({
+        const result = createCanonicalWorldEntity({
           kind: "place",
           name,
           notes,
@@ -786,7 +850,7 @@ function createMcpServer() {
           meta: fields ?? {},
         });
 
-        return jsonResponse({ ok: true, action: "created", kind: "place", ...created });
+        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "place", ...result });
       } catch (err) {
         return errorResponse("IO_ERROR", `Failed to create place sheet: ${err.message}`);
       }
@@ -1363,6 +1427,54 @@ function createMcpServer() {
       }
 
       try {
+        const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
+        if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file cannot be accessed by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (proseWriteDiagnostics.stat_error_code && proseWriteDiagnostics.stat_error_code !== "ENOENT" && proseWriteDiagnostics.stat_error_code !== "ENOTDIR") {
+          return errorResponse(
+            "IO_ERROR",
+            "Failed to inspect scene prose path before writing.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (!proseWriteDiagnostics.exists) {
+          return errorResponse("STALE_PATH", "Prose file not found at indexed path.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.is_file) {
+          return errorResponse("INVALID_PROSE_PATH", "Indexed prose path is not a regular file.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.writable) {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file is not writable by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
         // Reconstruct file content, preserving frontmatter only if the original had it
         const hasFrontmatter = proposal.metadata && Object.keys(proposal.metadata).length > 0;
         const content = hasFrontmatter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/sync.js

@@ -53,6 +53,11 @@ export function walkSidecars(dir, fileList = []) {
   return fileList;
 }
 
+function isNestedMirrorPath(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/");
+  return rel.includes("/scenes/projects/") || rel.includes("/scenes/universes/");
+}
+
 export function sidecarPath(filePath) {
   return filePath.replace(/\.(md|txt)$/, ".meta.yaml");
 }
@@ -204,6 +209,142 @@ export function isSyncDirWritable(syncDir) {
   }
 }
 
+function collectOwnershipSample(rootDir, limit = 200) {
+  const samples = [];
+  const stack = [rootDir];
+
+  while (stack.length && samples.length < limit) {
+    const current = stack.pop();
+    samples.push(current);
+
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (samples.length + stack.length >= limit) break;
+      if (entry.isSymbolicLink()) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else {
+        samples.push(full);
+        if (samples.length >= limit) break;
+      }
+    }
+  }
+
+  return samples;
+}
+
+export function getSyncOwnershipDiagnostics(syncDir, { sampleLimit = 200 } = {}) {
+  const runtimeUid = typeof process.getuid === "function" ? process.getuid() : null;
+  let syncDirPathExists;
+  let syncDirIsDirectory;
+  try {
+    const stat = fs.statSync(syncDir);
+    syncDirPathExists = true;
+    syncDirIsDirectory = stat.isDirectory();
+  } catch {
+    syncDirPathExists = false;
+    syncDirIsDirectory = false;
+  }
+
+  const diagnostics = {
+    sync_dir: path.resolve(syncDir),
+    sync_dir_path_exists: syncDirPathExists,
+    sync_dir_is_directory: syncDirIsDirectory,
+    // Backwards-compatible: "exists" now means "exists and is a directory".
+    sync_dir_exists: syncDirIsDirectory,
+    supported: runtimeUid !== null,
+    runtime_uid: runtimeUid,
+    sampled_paths: 0,
+    sample_limit: sampleLimit,
+    root_owned_paths: 0,
+    non_runtime_owned_paths: 0,
+    unreadable_paths: 0,
+    root_owned_examples: [],
+    non_runtime_owned_examples: [],
+  };
+
+  if (!diagnostics.sync_dir_is_directory || runtimeUid === null) {
+    return diagnostics;
+  }
+
+  const sample = collectOwnershipSample(syncDir, sampleLimit);
+  diagnostics.sampled_paths = sample.length;
+
+  for (const filePath of sample) {
+    try {
+      const stat = fs.statSync(filePath);
+      const rel = path.relative(syncDir, filePath) || ".";
+      if (stat.uid === 0) {
+        diagnostics.root_owned_paths++;
+        if (diagnostics.root_owned_examples.length < 5) diagnostics.root_owned_examples.push(rel);
+      }
+      if (stat.uid !== runtimeUid) {
+        diagnostics.non_runtime_owned_paths++;
+        if (diagnostics.non_runtime_owned_examples.length < 5) diagnostics.non_runtime_owned_examples.push(rel);
+      }
+    } catch {
+      diagnostics.unreadable_paths++;
+    }
+  }
+
+  return diagnostics;
+}
+
+export function getFileWriteDiagnostics(filePath) {
+  const runtimeUid = typeof process.getuid === "function" ? process.getuid() : null;
+  const resolvedPath = path.resolve(filePath);
+  const parentDir = path.dirname(resolvedPath);
+  const diagnostics = {
+    path: resolvedPath,
+    parent_dir: parentDir,
+    exists: false,
+    is_file: false,
+    writable: false,
+    parent_dir_writable: false,
+    supported: runtimeUid !== null,
+    runtime_uid: runtimeUid,
+    owner_uid: null,
+    root_owned: false,
+    stat_error_code: null,
+    stat_error_message: null,
+  };
+
+  try {
+    fs.accessSync(parentDir, fs.constants.W_OK);
+    diagnostics.parent_dir_writable = true;
+  } catch {
+    diagnostics.parent_dir_writable = false;
+  }
+
+  try {
+    const stat = fs.statSync(resolvedPath);
+    diagnostics.exists = true;
+    diagnostics.is_file = stat.isFile();
+    diagnostics.owner_uid = typeof stat.uid === "number" ? stat.uid : null;
+    diagnostics.root_owned = stat.uid === 0;
+  } catch (err) {
+    diagnostics.stat_error_code = typeof err?.code === "string" ? err.code : null;
+    diagnostics.stat_error_message = typeof err?.message === "string" ? err.message : String(err);
+    return diagnostics;
+  }
+
+  try {
+    fs.accessSync(resolvedPath, fs.constants.W_OK);
+    diagnostics.writable = diagnostics.is_file;
+  } catch {
+    diagnostics.writable = false;
+  }
+
+  return diagnostics;
+}
+
 // ---------------------------------------------------------------------------
 // DB-dependent sync (takes db + syncDir as arguments for testability)
 // ---------------------------------------------------------------------------
@@ -368,9 +509,18 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
   const warnings = [];
 
+  const scanFiles = [];
+  for (const file of files) {
+    if (isNestedMirrorPath(syncDir, file)) {
+      warnings.push(`Ignored nested mirror path: ${path.relative(syncDir, file)}`);
+      continue;
+    }
+    scanFiles.push(file);
+  }
+
   // --- Pass 1: world files (characters/places must be indexed before scenes
   // so that character name → ID resolution in scene_characters works) ---
-  for (const file of files) {
+  for (const file of scanFiles) {
     if (!isWorldFile(syncDir, file)) continue;
     try {
       const { meta } = readMeta(file, syncDir, { writable });
@@ -386,7 +536,7 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   }
 
   // --- Pass 2: scene files ---
-  for (const file of files) {
+  for (const file of scanFiles) {
     if (isWorldFile(syncDir, file)) continue;
     try {
       const { meta, sourceMeta, sidecarGenerated, derived, mismatches } = readMeta(file, syncDir, { writable });
@@ -431,7 +581,7 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   }
 
   // --- Orphaned sidecar detection ---
-  const sidecars = walkSidecars(syncDir);
+  const sidecars = walkSidecars(syncDir).filter(sidecar => !isNestedMirrorPath(syncDir, sidecar));
   for (const sidecar of sidecars) {
     const prose = sidecar.replace(/\.meta\.yaml$/, ".md");
     const proseTxt = sidecar.replace(/\.meta\.yaml$/, ".txt");