@hanna84/mcp-writing 1.6.2 → 1.7.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.7.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.6.3...v1.7.0)
+
+- feat: configurable OpenClaw runtime identity and ownership guardrails [`#49`](https://github.com/hannasdev/mcp-writing.git
+/pull/49)
+
+#### [v1.6.3](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.6.2...v1.6.3)
+
+> 19 April 2026
+
+- docs: sync PRD with current app behavior [`#48`](https://github.com/hannasdev/mcp-writing.git
+/pull/48)
+- Release 1.6.3 [`53add10`](https://github.com/hannasdev/mcp-writing.git
+/commit/53add102551c586c81aaef249509eec2c5487f96)
+
 #### [v1.6.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.6.1...v1.6.2)
 
+> 19 April 2026
+
 - docs: correct README license footer to AGPL-3.0-only [`#47`](https://github.com/hannasdev/mcp-writing.git
 /pull/47)
+- Release 1.6.2 [`27e92ab`](https://github.com/hannasdev/mcp-writing.git
+/commit/27e92ab8718b4c5736cf901c479dc91ea8259be0)
 
 #### [v1.6.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.6.0...v1.6.1)

package/README.md

@@ -339,13 +339,16 @@ Paginated tools (`find_scenes`, `get_arc`, `list_threads`, `get_thread_arc`, `se
 # docker-compose.yml snippet
 writing-mcp:
   build: .
-  user: "${UID:-1000}:${GID:-1000}"
+  user: "${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}"
   environment:
     WRITING_SYNC_DIR: /sync
     DB_PATH: /data/writing.db
     HTTP_PORT: "3000"
+    OWNERSHIP_GUARD_MODE: "${OWNERSHIP_GUARD_MODE:-warn}"
+    GIT_SSH_COMMAND: "ssh -i /ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/ssh/known_hosts"
   volumes:
-    - /path/to/sync-dir:/sync
+    - ${OPENCLAW_WORKSPACE_DIR:?run scripts/setup-openclaw-env.sh first}/sync:/sync
+    - ${OPENCLAW_SSH_DIR:?run scripts/setup-openclaw-env.sh first}:/ssh:ro
     - writing-mcp-data:/data
   healthcheck:
     test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
@@ -357,7 +360,15 @@ 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`.
+Recommended: start from `docker-compose.example.yml` and generate `.env` with machine-specific values:
+
+```sh
+sh scripts/setup-openclaw-env.sh
+```
+
+That script writes `OPENCLAW_UID`, `OPENCLAW_GID`, `OPENCLAW_WORKSPACE_DIR`, and `OPENCLAW_SSH_DIR` to `.env`.
+Running Compose without these values is unsupported and may create invalid mount definitions.
+It also normalizes `OWNERSHIP_GUARD_MODE` to `warn` or `fail` and preserves an existing valid value when rerun.
 
 Then register in your OpenClaw config:
 
@@ -380,8 +391,17 @@ When `mcp-writing` runs behind OpenClaw (or any Docker MCP gateway), these detai
 
 - Set `WRITING_SYNC_DIR=/sync`
 - Set `DB_PATH=/data/writing.db`
+- Set `OWNERSHIP_GUARD_MODE=warn` (or `fail` to block startup on ownership drift)
 - Mount your manuscript sync repo to `/sync`
 - Mount a persistent path for SQLite data at `/data`
+- Mount SSH materials read-only at `/ssh` and use `GIT_SSH_COMMAND` with `/ssh` paths
+
+Debug/test-only runtime override knobs:
+
+- `RUNTIME_UID_OVERRIDE` — test helper to simulate runtime UID during ownership diagnostics
+- `ALLOW_RUNTIME_UID_OVERRIDE=1` — explicitly enables the override outside `NODE_ENV=test`
+
+Do not set these in normal production or desktop deployments.
 
 If `/sync` contains raw Scrivener external-sync output, run the importer once before normal `sync` usage:
 
@@ -414,7 +434,7 @@ For private remotes, mount SSH materials read-only and enforce strict host check
 Example:
 
 ```sh
-export GIT_SSH_COMMAND="ssh -i /root/.ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/root/.ssh/known_hosts"
+export GIT_SSH_COMMAND="ssh -i /ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/ssh/known_hosts"
 ```
 
 #### Separate auth and signing keys
@@ -603,6 +623,22 @@ git config --system --add safe.directory /sync
 4. Verify SSH key has write access to the remote and `known_hosts` is mounted.
 5. Prefer branch-per-change workflow (`bot/*` or `edda/*`) if `main` is protected.
 
+### "Blocked: file is root-owned" (EACCES / ownership drift)
+
+The runtime user can read but cannot overwrite prose files.
+
+Fix:
+
+1. Repair host ownership once:
+
+```sh
+sudo chown -R "$(id -u):$(id -g)" /path/to/sync-dir
+```
+
+2. Ensure container user mapping is set from `.env` (`OPENCLAW_UID` / `OPENCLAW_GID`).
+3. Optionally set `OWNERSHIP_GUARD_MODE=fail` to catch mismatches at startup.
+4. Re-check `get_runtime_config` and confirm ownership warnings are gone.
+
 ### Tests fail after updating Node.js
 
 Local install state may be stale after the Node.js change.
@@ -624,6 +660,7 @@ npm test
 | `HTTP_PORT` | `3000` | Port for the MCP SSE endpoint |
 | `MAX_CHAPTER_SCENES` | `10` | Maximum scenes returned by `get_chapter_prose` |
 | `DEFAULT_METADATA_PAGE_SIZE` | `20` | Default page size for paginated tools |
+| `OWNERSHIP_GUARD_MODE` | `warn` | Startup ownership policy: `warn` logs drift, `fail` exits when sampled files are not owned by runtime user |
 
 ## License
 

package/index.js

@@ -19,6 +19,11 @@ const DB_PATH_DISPLAY = DB_PATH === ":memory:" ? DB_PATH : path.resolve(DB_PATH)
 const HTTP_PORT = parseInt(process.env.HTTP_PORT ?? "3000", 10);
 const MAX_CHAPTER_SCENES = parseInt(process.env.MAX_CHAPTER_SCENES ?? "10", 10);
 const DEFAULT_METADATA_PAGE_SIZE = parseInt(process.env.DEFAULT_METADATA_PAGE_SIZE ?? "20", 10);
+const OWNERSHIP_GUARD_MODE_RAW = (process.env.OWNERSHIP_GUARD_MODE ?? "warn").trim().toLowerCase();
+const OWNERSHIP_GUARD_MODE = OWNERSHIP_GUARD_MODE_RAW === "fail" || OWNERSHIP_GUARD_MODE_RAW === "warn"
+  ? OWNERSHIP_GUARD_MODE_RAW
+  : "warn";
+const OWNERSHIP_GUARD_MODE_RAW_DISPLAY = JSON.stringify(OWNERSHIP_GUARD_MODE_RAW);
 
 function paginateRows(rows, { page, pageSize, forcePagination = false }) {
   const totalCount = rows.length;
@@ -302,6 +307,23 @@ function getRuntimeDiagnostics() {
   const warnings = [];
   const recommendations = [];
 
+  if (OWNERSHIP_GUARD_MODE_RAW !== OWNERSHIP_GUARD_MODE) {
+    warnings.push(
+      `OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${OWNERSHIP_GUARD_MODE_RAW_DISPLAY}. Falling back to 'warn'.`
+    );
+    recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
+  }
+
+  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_ignored) {
+    warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
+    recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
+  }
+
+  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_invalid) {
+    warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
+    recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
+  }
+
   if (!SYNC_DIR_WRITABLE) {
     warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
     recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
@@ -316,10 +338,17 @@ function getRuntimeDiagnostics() {
       `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."
+      "For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
     );
   }
 
+  if (OWNERSHIP_GUARD_MODE === "fail" && SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid === 0) {
+    warnings.push(
+      "OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
+    );
+    recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
+  }
+
   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).`
@@ -353,6 +382,20 @@ if (RUNTIME_DIAGNOSTICS.warnings.length) {
   }
 }
 
+const SHOULD_ENFORCE_OWNERSHIP_FAIL_GUARD = OWNERSHIP_GUARD_MODE === "fail"
+  && SYNC_OWNERSHIP_DIAGNOSTICS.supported
+  && SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid !== 0;
+
+if (SHOULD_ENFORCE_OWNERSHIP_FAIL_GUARD && SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths > 0) {
+  process.stderr.write(
+    `[mcp-writing] FATAL: OWNERSHIP_GUARD_MODE=fail and ${SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid}.\n`
+  );
+  process.stderr.write(
+    `[mcp-writing] FATAL: Repair ownership once on the host directory mounted at ${SYNC_DIR_ABS}: sudo chown -R "$(id -u):$(id -g)" /path/to/host-sync-dir\n`
+  );
+  process.exit(1);
+}
+
 // Run sync on startup
 syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 
@@ -466,6 +509,7 @@ function createMcpServer() {
         sync_dir: SYNC_DIR_ABS,
         db_path: DB_PATH_DISPLAY,
         sync_dir_writable: SYNC_DIR_WRITABLE,
+        ownership_guard_mode: OWNERSHIP_GUARD_MODE,
         permission_diagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
         git_available: GIT_AVAILABLE,
         git_enabled: GIT_ENABLED,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -21,6 +21,7 @@
   "scripts": {
     "start": "node --experimental-sqlite index.js",
     "new:entity": "node scripts/new-world-entity.js",
+    "setup:openclaw-env": "sh scripts/setup-openclaw-env.sh",
     "release": "release-it",
     "lint": "eslint index.js importer.js db.js sync.js metadata-lint.js scripts/",
     "lint:metadata": "node scripts/lint-metadata.mjs",

package/scripts/setup-openclaw-env.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env sh
+set -eu
+
+ENV_FILE="${1:-.env}"
+OPENCLAW_UID_VALUE="$(id -u)"
+OPENCLAW_GID_VALUE="$(id -g)"
+OPENCLAW_WORKSPACE_DIR_VALUE="${OPENCLAW_WORKSPACE_DIR:-$(pwd)}"
+OPENCLAW_SSH_DIR_VALUE="${OPENCLAW_SSH_DIR:-${HOME:-$(pwd)}/.ssh}"
+OWNERSHIP_GUARD_MODE_VALUE="${2:-${OWNERSHIP_GUARD_MODE:-}}"
+
+quote_env_value() {
+  printf '"%s"' "$(printf '%s' "$1" | sed 's/["\\]/\\&/g')"
+}
+
+if [ -z "$OWNERSHIP_GUARD_MODE_VALUE" ] && [ -f "$ENV_FILE" ]; then
+  EXISTING_GUARD_MODE="$(grep -E '^OWNERSHIP_GUARD_MODE=' "$ENV_FILE" | tail -n1 | cut -d= -f2- || true)"
+  OWNERSHIP_GUARD_MODE_VALUE="$EXISTING_GUARD_MODE"
+fi
+
+if [ -z "$OWNERSHIP_GUARD_MODE_VALUE" ]; then
+  OWNERSHIP_GUARD_MODE_VALUE="warn"
+fi
+
+NORMALIZED_GUARD_MODE="$(printf '%s' "$OWNERSHIP_GUARD_MODE_VALUE" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"
+if [ "$NORMALIZED_GUARD_MODE" != "warn" ] && [ "$NORMALIZED_GUARD_MODE" != "fail" ]; then
+  printf 'Warning: unsupported OWNERSHIP_GUARD_MODE=%s, defaulting to "warn".\n' "$OWNERSHIP_GUARD_MODE_VALUE" >&2
+  OWNERSHIP_GUARD_MODE_VALUE="warn"
+else
+  OWNERSHIP_GUARD_MODE_VALUE="$NORMALIZED_GUARD_MODE"
+fi
+
+if TMP_FILE="$(mktemp -t openclaw-env.XXXXXX 2>/dev/null)"; then
+  :
+else
+  TMP_FILE="$(mktemp "${TMPDIR:-/tmp}/openclaw-env.XXXXXX")"
+fi
+trap 'rm -f "$TMP_FILE"' EXIT
+
+if [ -f "$ENV_FILE" ]; then
+  awk '
+    !/^OPENCLAW_UID=/ &&
+    !/^OPENCLAW_GID=/ &&
+    !/^OPENCLAW_WORKSPACE_DIR=/ &&
+    !/^OPENCLAW_SSH_DIR=/ &&
+    !/^OWNERSHIP_GUARD_MODE=/
+  ' "$ENV_FILE" > "$TMP_FILE"
+fi
+
+{
+  cat "$TMP_FILE"
+  if [ -s "$TMP_FILE" ]; then
+    printf "\n"
+  fi
+  printf "OPENCLAW_UID=%s\n" "$OPENCLAW_UID_VALUE"
+  printf "OPENCLAW_GID=%s\n" "$OPENCLAW_GID_VALUE"
+  printf "OPENCLAW_WORKSPACE_DIR=%s\n" "$(quote_env_value "$OPENCLAW_WORKSPACE_DIR_VALUE")"
+  printf "OPENCLAW_SSH_DIR=%s\n" "$(quote_env_value "$OPENCLAW_SSH_DIR_VALUE")"
+  printf "OWNERSHIP_GUARD_MODE=%s\n" "$OWNERSHIP_GUARD_MODE_VALUE"
+} > "$ENV_FILE"
+
+printf "Wrote %s with OPENCLAW runtime variables.\n" "$ENV_FILE"
+printf "UID:GID=%s:%s\n" "$OPENCLAW_UID_VALUE" "$OPENCLAW_GID_VALUE"
+printf "WORKSPACE=%s\n" "$OPENCLAW_WORKSPACE_DIR_VALUE"
+printf "SSH_DIR=%s\n" "$OPENCLAW_SSH_DIR_VALUE"

package/sync.js

@@ -241,7 +241,26 @@ function collectOwnershipSample(rootDir, limit = 200) {
 }
 
 export function getSyncOwnershipDiagnostics(syncDir, { sampleLimit = 200 } = {}) {
-  const runtimeUid = typeof process.getuid === "function" ? process.getuid() : null;
+  let runtimeUid = typeof process.getuid === "function" ? process.getuid() : null;
+  const runtimeUidOverrideRaw = process.env.RUNTIME_UID_OVERRIDE;
+  const runtimeUidOverrideAllowed = process.env.NODE_ENV === "test" || process.env.ALLOW_RUNTIME_UID_OVERRIDE === "1";
+  let runtimeUidOverrideApplied = false;
+  let runtimeUidOverrideIgnored = false;
+  let runtimeUidOverrideInvalid = false;
+
+  if (runtimeUidOverrideRaw !== undefined) {
+    if (!runtimeUidOverrideAllowed) {
+      runtimeUidOverrideIgnored = true;
+    } else {
+      const parsed = Number.parseInt(runtimeUidOverrideRaw, 10);
+      if (Number.isInteger(parsed) && parsed >= 0) {
+        runtimeUid = parsed;
+        runtimeUidOverrideApplied = true;
+      } else {
+        runtimeUidOverrideInvalid = true;
+      }
+    }
+  }
   let syncDirPathExists;
   let syncDirIsDirectory;
   try {
@@ -261,6 +280,10 @@ export function getSyncOwnershipDiagnostics(syncDir, { sampleLimit = 200 } = {})
     sync_dir_exists: syncDirIsDirectory,
     supported: runtimeUid !== null,
     runtime_uid: runtimeUid,
+    runtime_uid_override_requested: runtimeUidOverrideRaw !== undefined,
+    runtime_uid_override_applied: runtimeUidOverrideApplied,
+    runtime_uid_override_ignored: runtimeUidOverrideIgnored,
+    runtime_uid_override_invalid: runtimeUidOverrideInvalid,
     sampled_paths: 0,
     sample_limit: sampleLimit,
     root_owned_paths: 0,