@hanna84/mcp-writing 1.5.1 → 1.6.0

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.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)
 
+> 19 April 2026
+
 - chore: switch license from MIT to AGPL v3 [`#43`](https://github.com/hannasdev/mcp-writing.git
 /pull/43)
+- Release 1.5.1 [`73b233f`](https://github.com/hannasdev/mcp-writing.git
+/commit/73b233f2f210d435386f1235aa15ebc3c945542b)
 
 #### [v1.5.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.4.8...v1.5.0)

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/importer.js

@@ -129,6 +129,57 @@ function removeIfExists(filePath) {
   if (filePath && fs.existsSync(filePath)) fs.unlinkSync(filePath);
 }
 
+function resolveSyncRootFromPrefix(prefix, syncDirAbs) {
+  const parsedRoot = path.parse(syncDirAbs).root;
+
+  if (!prefix) {
+    return parsedRoot ? path.resolve(parsedRoot) : path.resolve(syncDirAbs);
+  }
+
+  // On Windows, a regex prefix like "C:" would resolve relative to cwd on drive C.
+  // Use the true drive root instead (e.g., "C:\\").
+  if (/^[a-zA-Z]:$/.test(prefix)) {
+    return parsedRoot || `${prefix}${path.sep}`;
+  }
+
+  return path.resolve(prefix);
+}
+
+function detectScopedSyncDir(syncDirAbs) {
+  const normalized = syncDirAbs.split(path.sep).join("/");
+
+  const universeMatch = normalized.match(/^(.*)\/universes\/([^/]+)\/([^/]+)(?:\/scenes)?$/);
+  if (universeMatch) {
+    const prefix = universeMatch[1];
+    const universeId = universeMatch[2];
+    const projectSlug = universeMatch[3];
+    const syncRoot = resolveSyncRootFromPrefix(prefix, syncDirAbs);
+    const projectRoot = path.join(syncRoot, "universes", universeId, projectSlug);
+    return {
+      projectId: `${universeId}/${projectSlug}`,
+      scope: "universe",
+      syncRoot,
+      projectRoot,
+    };
+  }
+
+  const projectMatch = normalized.match(/^(.*)\/projects\/([^/]+)(?:\/scenes)?$/);
+  if (projectMatch) {
+    const prefix = projectMatch[1];
+    const projectSlug = projectMatch[2];
+    const syncRoot = resolveSyncRootFromPrefix(prefix, syncDirAbs);
+    const projectRoot = path.join(syncRoot, "projects", projectSlug);
+    return {
+      projectId: projectSlug,
+      scope: "project",
+      syncRoot,
+      projectRoot,
+    };
+  }
+
+  return null;
+}
+
 export function importScrivenerSync({
   scrivenerDir,
   mcpSyncDir,
@@ -138,31 +189,48 @@ export function importScrivenerSync({
 }) {
   const scrivenerDirAbs = path.resolve(scrivenerDir);
   const mcpSyncDirAbs = path.resolve(mcpSyncDir);
+  const scopedSyncDir = detectScopedSyncDir(mcpSyncDirAbs);
+  const fallbackProjectId = path.basename(mcpSyncDirAbs).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
   const resolvedProjectId = projectId
     ? projectId
-    : path.basename(mcpSyncDirAbs).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    : scopedSyncDir?.projectId ?? fallbackProjectId;
 
   const projectIdCheck = validateProjectId(resolvedProjectId);
   if (!projectIdCheck.ok) {
     throw new Error(`Invalid project_id '${resolvedProjectId}': ${projectIdCheck.reason}`);
   }
 
+  if (scopedSyncDir && projectId && projectId !== scopedSyncDir.projectId) {
+    throw new Error(
+      `project_id '${projectId}' does not match WRITING_SYNC_DIR scope '${scopedSyncDir.projectId}'. `
+      + "Set WRITING_SYNC_DIR to the sync root or use the matching project_id."
+    );
+  }
+
   if (!fs.existsSync(scrivenerDirAbs)) {
     throw new Error(`Scrivener sync dir not found: ${scrivenerDirAbs}`);
   }
 
-  // Route universe/project IDs to universes/<universe>/<project>/scenes,
-  // matching the convention used by inferProjectAndUniverse in sync.js.
-  const segments = resolvedProjectId.split("/");
   let scenesDir;
   let scenesBoundaryRoot;
-  if (segments.length === 2) {
-    const [universeId, projectSlug] = segments;
-    scenesBoundaryRoot = path.join(mcpSyncDirAbs, "universes");
-    scenesDir = path.resolve(scenesBoundaryRoot, universeId, projectSlug, "scenes");
+  if (scopedSyncDir) {
+    scenesBoundaryRoot = path.join(
+      scopedSyncDir.syncRoot,
+      scopedSyncDir.scope === "universe" ? "universes" : "projects"
+    );
+    scenesDir = path.join(scopedSyncDir.projectRoot, "scenes");
   } else {
-    scenesBoundaryRoot = path.join(mcpSyncDirAbs, "projects");
-    scenesDir = path.resolve(scenesBoundaryRoot, resolvedProjectId, "scenes");
+    // Route universe/project IDs to universes/<universe>/<project>/scenes,
+    // matching the convention used by inferProjectAndUniverse in sync.js.
+    const segments = resolvedProjectId.split("/");
+    if (segments.length === 2) {
+      const [universeId, projectSlug] = segments;
+      scenesBoundaryRoot = path.join(mcpSyncDirAbs, "universes");
+      scenesDir = path.resolve(scenesBoundaryRoot, universeId, projectSlug, "scenes");
+    } else {
+      scenesBoundaryRoot = path.join(mcpSyncDirAbs, "projects");
+      scenesDir = path.resolve(scenesBoundaryRoot, resolvedProjectId, "scenes");
+    }
   }
 
   const relFromBoundary = path.relative(scenesBoundaryRoot, scenesDir);

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.1",
+  "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");