@hanna84/mcp-writing 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.5.2...v1.6.0)
+
+- feat: add permission preflight diagnostics and ops contract [`#45`](https://github.com/hannasdev/mcp-writing.git
+/pull/45)
+
 #### [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, 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";
@@ -220,6 +220,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 +264,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 +415,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "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,94 @@ 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;
+}
+
 // ---------------------------------------------------------------------------
 // DB-dependent sync (takes db + syncDir as arguments for testability)
 // ---------------------------------------------------------------------------
@@ -368,9 +461,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 +488,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 +533,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");