@hanna84/mcp-writing 1.3.8 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.4.0](https://github.com/hannasdev/mcp-writing/compare/v1.3.8...v1.4.0) (2026-04-18)
+
+
+### Features
+
+* add runtime write-access diagnostics for onboarding ([434c453](https://github.com/hannasdev/mcp-writing/commit/434c45323b7662312cff8cc24e2c8ee2c0fd8745))
+
 ## [1.3.8](https://github.com/hannasdev/mcp-writing/compare/v1.3.7...v1.3.8) (2026-04-18)
 
 

package/README.md

@@ -32,6 +32,21 @@ npm --version     # should be 8.0.0 or later
 git --version     # should be installed
 ```
 
+## First-time setup path (recommended)
+
+If this is your first time, use this path and skip the advanced/reference sections for now:
+
+1. Follow either **Quick start with Scrivener** or **Running with Docker**.
+2. Start the server with `npm start`.
+3. Run **Verify your setup** (`/healthz` and `/sse`).
+4. Use the MCP `sync` tool once to build the index.
+
+After that, come back to:
+
+- **Advanced: Native sync format** for custom project layouts
+- **Reference: Available tools** for the full tool catalog
+- **Appendix: Real-world usage scenarios** for workflow ideas
+
 ## Quick start with Scrivener
 
 If you write in [Scrivener](https://www.literatureandlatte.com/scrivener), you can seed `mcp-writing` from a Scrivener external-sync export for scene prose, then curate non-draft content directly into the target folder structure.
@@ -51,6 +66,8 @@ The importer:
 - Converts `Draft/` files to scene sidecars (`.meta.yaml`) with auto-generated `scene_id`, `title`, `part`, `chapter`, and `save_the_cat_beat` fields derived from the filename/structure.
 - Skips beat-marker files (`-Setup-`, `-Catalyst-`, etc.), chapter-intro files, epigraphs, and trashed files.
 
+Important: `sync` does not run this import step for you. If your source is a raw Scrivener `Draft/` export, run `scripts/import.js` first so scene files get `scene_id` metadata before indexing.
+
 Non-draft content is not inferred from `Notes/`. Put it directly into the target sync dir using the `world/` folder conventions described below.
 
 ### 3. Start the server
@@ -61,7 +78,7 @@ WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npm start
 
 You should see:
 
-```
+```sh
 Listening on port 3000
 Sync dir: /path/to/sync-dir
 Database: ./writing.db
@@ -79,7 +96,7 @@ Exits non-zero if any errors are found. Warnings (e.g. `UNKNOWN_KEY`) are inform
 
 ---
 
-## Native sync format
+## Advanced: Native sync format
 
 For projects not starting from a Scrivener export, place plain `.md` files in the sync folder directly. Metadata lives in a YAML frontmatter block.
 
@@ -177,7 +194,7 @@ Recommended workflow:
 
 ---
 
-## Real-world usage scenarios
+## Appendix: Real-world usage scenarios
 
 The tool list is useful as reference. These example workflows show how people actually use `mcp-writing` while drafting and revising.
 
@@ -227,7 +244,7 @@ Outcome: you get AI speed with explicit approval and recoverable history for eve
 
 ---
 
-## Available tools
+## Reference: Available tools
 
 | Tool | Description |
 | --- | --- |
@@ -235,7 +252,7 @@ Outcome: you get AI speed with explicit approval and recoverable history for eve
 | `find_scenes` | Filter scenes by character, beat, tag, part, chapter, or POV |
 | `get_scene_prose` | Load the full prose for a specific scene |
 | `get_chapter_prose` | Load all prose for a chapter |
-| `get_runtime_config` | Show the active sync dir, DB path, and runtime capabilities |
+| `get_runtime_config` | Show active paths/capabilities plus runtime warnings and setup recommendations |
 | `get_arc` | Ordered scene metadata for all scenes involving a character |
 | `list_characters` | All characters, optionally filtered by project or universe |
 | `get_character_sheet` | Full character metadata, traits, notes, and support notes |
@@ -294,6 +311,99 @@ Then register in your OpenClaw config:
 }
 ```
 
+<details>
+<summary>Advanced OpenClaw / Docker integration notes</summary>
+
+### OpenClaw / Docker integration notes
+
+When `mcp-writing` runs behind OpenClaw (or any Docker MCP gateway), these details prevent common runtime failures.
+
+#### Required environment and mounts
+
+- Set `WRITING_SYNC_DIR=/sync`
+- Set `DB_PATH=/data/writing.db`
+- Mount your manuscript sync repo to `/sync`
+- Mount a persistent path for SQLite data at `/data`
+
+If `/sync` contains raw Scrivener external-sync output, run the importer once before normal `sync` usage:
+
+```sh
+node scripts/import.js /path/to/scrivener-export /sync --project my-novel
+```
+
+`sync` indexes files that already contain scene metadata. It does not convert Scrivener `Draft/` filenames into scene sidecars by itself.
+
+#### Git ownership trust for mounted repos
+
+If host and container ownership differ, git can fail with:
+
+- `fatal: detected dubious ownership in repository`
+
+Mark the mounted repo path as safe in the container image:
+
+```sh
+git config --system --add safe.directory /sync
+```
+
+#### SSH transport hardening
+
+For private remotes, mount SSH materials read-only and enforce strict host checks:
+
+- Auth key for fetch/pull/push
+- `known_hosts` with GitHub host key
+- `StrictHostKeyChecking=yes`
+
+Example:
+
+```sh
+export GIT_SSH_COMMAND="ssh -i /root/.ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/root/.ssh/known_hosts"
+```
+
+#### Separate auth and signing keys
+
+Use dedicated keys for transport and signing:
+
+- Auth key: repository transport (`fetch` / `pull` / `push`)
+- Signing key: commit/tag signatures
+
+Recommended git config:
+
+```sh
+git config gpg.format ssh
+git config user.signingkey /root/.ssh/id_ed25519_signing
+git config commit.gpgsign true
+git config pull.ff only
+```
+
+#### Git identity and GitHub email privacy
+
+If GitHub email privacy is enabled, pushes can fail unless `user.email` is a GitHub noreply address:
+
+```sh
+git config user.name "Edda"
+git config user.email "<id>+<username>@users.noreply.github.com"
+```
+
+#### Branch safety for automation
+
+For bot-driven edits, prefer branch-per-change flow:
+
+- Push to `edda/*` or `bot/*`
+- Merge via pull request
+- Protect `main` from direct automation pushes
+
+#### Quick validation
+
+```sh
+ssh -T git@github.com
+git -C /sync fetch origin
+git -C /sync pull --ff-only
+```
+
+Then create and push a signed smoke commit on a temporary branch.
+
+</details>
+
 ## Running locally
 
 ```sh
@@ -339,19 +449,19 @@ For real projects, keep your manuscript sync folder outside this tool repository
 
 ### "Module not found: sqlite" or "Database support not available"
 
-**Cause:** Node.js version is below 22.6.0 or the `--experimental-sqlite` flag was not passed.
+Your Node.js version is too old, or SQLite support was not started with the required flag.
 
-**Solution:**
-1. Check your Node.js version: `node --version` (should be v22.6.0+)
-2. Update Node.js if needed: use nvm, homebrew, or download from nodejs.org
-3. Restart with `npm start` (which includes the flag automatically)
+Fix:
+
+1. Run `node --version` and confirm v22.6.0 or newer.
+2. Upgrade Node.js if needed.
+3. Restart with `npm start` (the script already includes `--experimental-sqlite`).
 
 ### "EADDRINUSE: address already in use :::3000"
 
-**Cause:** Port 3000 is already in use by another application.
+Port 3000 is already in use.
 
-**Solution:**
-Use a different port:
+Fix: start on a different port.
 
 ```sh
 HTTP_PORT=3001 WRITING_SYNC_DIR=./my-manuscript DB_PATH=./writing.db npm start
@@ -361,10 +471,9 @@ Then update your MCP client config to use `http://localhost:3001/sse`.
 
 ### "ENOENT: no such file or directory, open './writing.db'"
 
-**Cause:** The directory for `DB_PATH` does not exist.
+The directory for `DB_PATH` does not exist.
 
-**Solution:**
-Create the directory first:
+Fix: create the directory first.
 
 ```sh
 mkdir -p $(dirname ./writing.db)  # if using a subdirectory
@@ -379,34 +488,66 @@ WRITING_SYNC_DIR=~/my-manuscript DB_PATH=~/writing-data/writing.db npm start
 
 ### "Sync dir not found: ./my-manuscript"
 
-**Cause:** The `WRITING_SYNC_DIR` path does not exist.
+The `WRITING_SYNC_DIR` path does not exist.
 
-**Solution:**
-Create the sync folder first:
+Fix: create it (or point to an existing sync folder).
 
 ```sh
 mkdir -p ./my-manuscript/projects/my-novel
 WRITING_SYNC_DIR=./my-manuscript DB_PATH=./writing.db npm start
 ```
 
-Or point to an existing folder where you've already placed scene files.
-
 ### "Import failed: unrecognized format"
 
-**Cause:** The Scrivener export format was not plain text (`.txt`) or the folder structure is unexpected.
+Scrivener export is not plain text (`.txt`) or folder layout is unexpected.
+
+Fix:
 
-**Solution:**
 1. In Scrivener, re-export with **File → Sync → With External Folder**
 2. Ensure the format is set to **Plain text** (not RTF or .docx)
 3. Verify the export folder has a `Draft/` subdirectory with `.txt` files
 4. Try the import again: `node scripts/import.js ~/my-novel-txt /path/to/sync-dir --project my-novel`
 
+### "OpenClaw can read tools, but scene indexing is empty or incomplete"
+
+You are likely running `sync` on raw Scrivener `Draft/` output that has not been imported yet.
+
+Fix:
+
+1. Run importer once to create scene metadata sidecars:
+
+```sh
+node scripts/import.js /path/to/scrivener-export /path/to/sync-dir --project my-novel
+```
+
+2. Restart the service (if needed), then call `sync` again.
+
+Note: importer behavior is Draft-aware (`<source>/Draft` if present, else source root), but plain `sync` only indexes already-normalized scene files.
+
+### "Write access to repository denied" (or git push/pull fails in container)
+
+Your container can start and read files, but cannot write metadata, create snapshots, or push branches.
+
+Fix:
+
+1. Check runtime diagnostics via `get_runtime_config`:
+  - `sync_dir_writable` must be `true`
+  - `runtime_warnings` should be empty for normal editing flows
+2. Ensure `/sync` is mounted read-write (no `:ro`) and owned by the container user.
+3. For mounted git repos with UID mismatch, mark safe directory:
+
+```sh
+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.
+
 ### Tests fail after updating Node.js
 
-**Cause:** SQLite module cache may be stale.
+Local install state may be stale after the Node.js change.
 
-**Solution:**
-Clear npm cache and reinstall:
+Fix: reinstall dependencies.
 
 ```sh
 rm -rf node_modules package-lock.json

package/index.js

@@ -252,6 +252,43 @@ function generateProposalId() {
   return `proposal-${nextProposalId++}`;
 }
 
+function getRuntimeDiagnostics() {
+  const warnings = [];
+  const recommendations = [];
+
+  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').");
+    recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
+  }
+
+  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.");
+  }
+
+  if (GIT_AVAILABLE && SYNC_DIR_WRITABLE && !GIT_ENABLED) {
+    warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
+    recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
+  }
+
+  if (GIT_AVAILABLE && !SYNC_DIR_WRITABLE) {
+    recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
+  }
+
+  recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
+
+  return { warnings, recommendations };
+}
+
+const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics();
+if (RUNTIME_DIAGNOSTICS.warnings.length) {
+  process.stderr.write(`[mcp-writing] Runtime diagnostics:\n`);
+  for (const line of RUNTIME_DIAGNOSTICS.warnings) {
+    process.stderr.write(`[mcp-writing] - ${line}\n`);
+  }
+}
+
 // Run sync on startup
 syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 
@@ -267,6 +304,7 @@ function createMcpServer() {
     const parts = [`Sync complete. ${result.indexed} scenes indexed. ${result.staleMarked} scenes marked stale.`];
     if (result.sidecarsMigrated) parts.push(`${result.sidecarsMigrated} sidecar(s) auto-generated from frontmatter.`);
     if (result.skipped) parts.push(`${result.skipped} file(s) skipped (no scene_id).`);
+    if (result.skipped) parts.push(`Tip: for raw Scrivener Draft exports, run scripts/import.js first, then run sync again.`);
     if (result.warnings.length) parts.push(`\n⚠️ Warnings:\n` + result.warnings.map(w => `- ${w}`).join("\n"));
     return { content: [{ type: "text", text: parts.join(" ") }] };
   });
@@ -284,6 +322,8 @@ function createMcpServer() {
         git_available: GIT_AVAILABLE,
         git_enabled: GIT_ENABLED,
         http_port: HTTP_PORT,
+        runtime_warnings: RUNTIME_DIAGNOSTICS.warnings,
+        setup_recommendations: RUNTIME_DIAGNOSTICS.recommendations,
       });
     }
   );

package/package.json

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