@hanna84/mcp-writing 1.1.1 → 1.3.7

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## [1.3.7](https://github.com/hannasdev/mcp-writing/compare/v1.3.6...v1.3.7) (2026-04-18)
+
+
+### Miscellaneous Chores
+
+* **ci:** remove npm whoami diagnostic step ([65435e9](https://github.com/hannasdev/mcp-writing/commit/65435e9c8cfa829ceb6937904250c46afc45b54c))
+
+## [1.3.6](https://github.com/hannasdev/mcp-writing/compare/v1.3.5...v1.3.6) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** restore npm trusted publishing auth config ([f043368](https://github.com/hannasdev/mcp-writing/commit/f0433681e984e34d1c38725f2d85dc3d14031626))
+
+## [1.3.5](https://github.com/hannasdev/mcp-writing/compare/v1.3.4...v1.3.5) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** force OIDC-only npm publish auth ([c9f1216](https://github.com/hannasdev/mcp-writing/commit/c9f1216f2d3aa49fcc2aad5e6c4032962ad843d1))
+
+## [1.3.4](https://github.com/hannasdev/mcp-writing/compare/v1.3.3...v1.3.4) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** use tag trigger for npm publish (matches n8n pattern) ([#18](https://github.com/hannasdev/mcp-writing/issues/18)) ([a3c5992](https://github.com/hannasdev/mcp-writing/commit/a3c5992e8cb560aa79b554389d41457fcf3c0cfd))
+
+## [1.3.3](https://github.com/hannasdev/mcp-writing/compare/v1.3.2...v1.3.3) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** use tag trigger for npm publish (matches n8n pattern) ([6841de7](https://github.com/hannasdev/mcp-writing/commit/6841de78a90c3b4c121761d28a09b02f9d360a96))
+
+## [1.3.2](https://github.com/hannasdev/mcp-writing/compare/v1.3.1...v1.3.2) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** publish from main release commits for npm trusted publishing ([135ab25](https://github.com/hannasdev/mcp-writing/commit/135ab254fb91ee6427a79cdecdc5b9bf55cfb4d1))
+
+## [1.3.1](https://github.com/hannasdev/mcp-writing/compare/v1.3.0...v1.3.1) (2026-04-18)
+
+
+### Bug Fixes
+
+* **ci:** set npm environment for trusted publishing ([b75fb08](https://github.com/hannasdev/mcp-writing/commit/b75fb0897dbbbd9df2d136cbb78a06218f0c0b50))
+
+
+### Miscellaneous Chores
+
+* generate integration fixtures at runtime and remove test-sync ([#14](https://github.com/hannasdev/mcp-writing/issues/14)) ([0ff5024](https://github.com/hannasdev/mcp-writing/commit/0ff5024f0c3724b099035a6f76fbe4c517870652))
+
+## [1.3.0](https://github.com/hannasdev/mcp-writing/compare/v1.2.0...v1.3.0) (2026-04-17)
+
+
+### Features
+
+* formalize non-draft content and stable Scrivener imports ([#12](https://github.com/hannasdev/mcp-writing/issues/12)) ([70b4beb](https://github.com/hannasdev/mcp-writing/commit/70b4bebd0d3cd823ffe3a9251f59f9a0c0e5f12f))
+
+## [1.2.0](https://github.com/hannasdev/mcp-writing/compare/v1.1.1...v1.2.0) (2026-04-17)
+
+
+### Features
+
+* Phase 3 git-backed prose editing, runtime config tool, startup path logging ([f30a7c8](https://github.com/hannasdev/mcp-writing/commit/f30a7c8b5e5aaf070b0b6cfaec38479141c5f60b))
+
 ## [1.1.1](https://github.com/hannasdev/mcp-writing/compare/v1.1.0...v1.1.1) (2026-04-16)
 
 

package/README.md

@@ -9,16 +9,36 @@ Designed to work with [OpenClaw](https://github.com/openclaw/openclaw) but compa
 Instead of feeding an entire manuscript to an AI and hoping it fits in the context window, `mcp-writing` builds a structured index from your scene files. The AI queries that index first — finding relevant characters, beats, and loglines — then loads only the specific prose it needs.
 
 **Phase 1:** Read-only analysis. Ask questions about your project.
-**Phase 2 (current):** Metadata write-back. Answers stay accurate as the manuscript evolves.
-**Phase 3:** AI-assisted prose editing with confirmation and version history.
+**Phase 2:** Metadata write-back. Answers stay accurate as the manuscript evolves.
+**Phase 3 (current):** AI-assisted prose editing with confirmation and version history.
+
+## Who it is for
+
+- Novelists and writing teams working on long manuscripts with many scenes, characters, and continuity constraints.
+- AI-assisted editing workflows where you want targeted context retrieval instead of full-manuscript prompting.
+- Projects that need traceable, reversible edits with metadata that stays synchronized as drafts evolve.
+
+## Prerequisites
+
+- **Node.js 22.6.0 or later** (required for SQLite support via `--experimental-sqlite` flag)
+- **npm 8.0.0 or later**
+- **Git** (for edit snapshots and version history)
+
+Verify your setup:
+
+```sh
+node --version    # should be v22.6.0 or later
+npm --version     # should be 8.0.0 or later
+git --version     # should be installed
+```
 
 ## 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 in two steps.
+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.
 
 ### 1. Export from Scrivener
 
-In Scrivener: **File → Sync → With External Folder**. Set the format to **plain text** (`.txt`) and pick an output folder, for example `~/my-novel-txt/`. Your `Draft/` folder and `Notes/` folder will be exported as numbered `.txt` files.
+In Scrivener: **File → Sync → With External Folder**. Set the format to **plain text** (`.txt`) and pick an output folder, for example `~/my-novel-txt/`. `mcp-writing` imports the `Draft/` folder automatically.
 
 ### 2. Import into mcp-writing
 
@@ -27,11 +47,11 @@ node scripts/import.js ~/my-novel-txt /path/to/sync-dir --project my-novel
 ```
 
 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.
-- Routes `Notes/` files into `world/characters/` or `world/places/` based on section grouping.
 - Skips beat-marker files (`-Setup-`, `-Catalyst-`, etc.), chapter-intro files, epigraphs, and trashed files.
 
-> **Note:** The importer writes a `group` key to character sidecar files so characters stay organized by their Notes section (e.g. "Main Characters", "Mira's team"). This is preserved through lint and sync.
+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
 
@@ -39,6 +59,14 @@ The importer:
 WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npm start
 ```
 
+You should see:
+
+```
+Listening on port 3000
+Sync dir: /path/to/sync-dir
+Database: ./writing.db
+```
+
 Then call the `sync` tool once to index everything.
 
 ### 4. Lint your metadata (optional)
@@ -80,13 +108,15 @@ Alternatively, metadata can live in a sidecar file named `<scene-file>.meta.yaml
 
 ### Project structure
 
-```
+```bash
 /sync-root/
   /universes/
     /my-series/
       /world/
-        characters/elena.md
-        places/harbor-district.md
+        characters/elena/sheet.md
+        characters/elena/arc.md
+        places/harbor-district/sheet.md
+        reference/vampire-biology.md
       /book-1/
         /part-1/chapter-1/scene-001.md
   /projects/
@@ -94,11 +124,107 @@ Alternatively, metadata can live in a sidecar file named `<scene-file>.meta.yaml
       /world/
         characters/
         places/
+        reference/
       /part-1/chapter-1/scene-001.md
 ```
 
+Character/place folders use one canonical sheet file for entity indexing:
+
+- `world/characters/<slug>/sheet.md` or `sheet.txt`
+- `world/places/<slug>/sheet.md` or `sheet.txt`
+
+Additional files in the same folder are treated as support notes, not separate entities.
+
 Universe-level characters and places are shared across all books in that universe. Standalone projects are fully isolated.
 
+### Scaffolding templates
+
+Yes, a template is helpful here. It keeps the canonical metadata fields consistent, lowers the friction of adding a new character or place, and reduces the chance that a file is created in the right folder but missing the fields needed for indexing.
+
+Use the scaffold script to create a canonical character or place folder:
+
+```sh
+npm run new:entity -- --sync-dir /path/to/sync-root --kind character --scope universe --universe my-series --name "Mira Nystrom"
+```
+
+```sh
+npm run new:entity -- --sync-dir /path/to/sync-root --kind place --scope project --project my-series/book-1 --name "University Hospital"
+```
+
+This creates:
+
+- `world/characters/<slug>/sheet.md` plus `arc.md` for character arcs
+- `world/places/<slug>/sheet.md` for places
+- `sheet.meta.yaml` with the required entity ID and starter fields
+
+Generated Markdown follows one formatting contract so scaffolded files are predictable to edit:
+
+- the first line is a top-level title (`# Name`)
+- every heading is followed by a blank line
+- every generated `.md` file ends with a trailing blank line
+
+Use `--dry-run` to preview the path without writing files.
+
+You can also create canonical sheets directly through the MCP server with `create_character_sheet` and `create_place_sheet`, then move your existing raw notes into the generated folders.
+
+Recommended workflow:
+
+1. Scaffold the entity folder and canonical sheet.
+2. Fill in the metadata fields you care about first.
+3. For characters, fill in `arc.md` as a separate arc-analysis document.
+4. Add any other nearby notes like `relationships.md` or `history.md` as needed.
+5. Run `sync` to index the new entity.
+
+---
+
+## 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.
+
+### 1) Continuity pass before sending chapters to beta readers
+
+Goal: catch inconsistencies before sharing pages.
+
+1. Run `sync` after your latest writing session.
+2. Ask `find_scenes` for scenes involving a specific character or tag (for example, all scenes tagged `injury` or `promise`).
+3. Use `get_arc` to review that character's ordered progression across the manuscript.
+4. Load only the suspect scenes with `get_scene_prose`.
+5. Attach follow-up notes with `flag_scene` where continuity needs a fix.
+
+Outcome: you review one narrative thread at a time instead of rereading the entire novel to find contradictions.
+
+### 2) Planning and tracking subplot beats during revisions
+
+Goal: make sure subplot threads progress intentionally and resolve on time.
+
+1. Run `list_threads` for the project.
+2. Use `get_thread_arc` to inspect scene order and beat labels for each thread.
+3. When a beat is missing, call `upsert_thread_link` to add or update it on the right scene.
+4. Re-run `get_thread_arc` to confirm pacing and coverage.
+
+Outcome: subplot structure stays visible and auditable, which reduces dropped threads in late drafts.
+
+### 3) Tightening scene metadata after heavy prose edits
+
+Goal: keep indexes accurate without manually re-tagging everything.
+
+1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
+2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, timeline position, and tags).
+3. Use `search_metadata` and `find_scenes` to verify scenes are discoverable under the expected filters.
+
+Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.
+
+### 4) Safe AI-assisted line edits with rollback
+
+Goal: let AI propose prose edits without losing control of your draft.
+
+1. Ask the AI to call `propose_edit` for a specific scene.
+2. Review the staged diff.
+3. Accept with `commit_edit` or reject with `discard_edit`.
+4. Use `list_snapshots` (and optional `snapshot_scene`) to inspect or preserve revision history.
+
+Outcome: you get AI speed with explicit approval and recoverable history for every applied change.
+
 ---
 
 ## Available tools
@@ -109,10 +235,14 @@ Universe-level characters and places are shared across all books in that univers
 | `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_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, and notes |
+| `get_character_sheet` | Full character metadata, traits, notes, and support notes |
+| `create_character_sheet` | Create a canonical character sheet folder and sidecar |
 | `list_places` | All places |
+| `get_place_sheet` | Full place metadata, tags, associated characters, notes, and support notes |
+| `create_place_sheet` | Create a canonical place sheet folder and sidecar |
 | `search_metadata` | Full-text search across scene titles and loglines |
 | `list_threads` | All subplot threads for a project |
 | `get_thread_arc` | Scenes belonging to a thread, with per-thread beat |
@@ -121,6 +251,11 @@ Universe-level characters and places are shared across all books in that univers
 | `update_scene_metadata` | Write metadata fields back to a scene sidecar |
 | `update_character_sheet` | Write fields back to a character sidecar |
 | `flag_scene` | Mark a scene with a flag for AI follow-up |
+| `propose_edit` | Stage a scene revision for review without writing it |
+| `commit_edit` | Apply a staged prose edit and create a git-backed snapshot |
+| `discard_edit` | Discard a pending staged prose edit |
+| `snapshot_scene` | Create a manual git snapshot for a scene |
+| `list_snapshots` | List snapshot history for a scene |
 
 Paginated tools (`find_scenes`, `get_arc`, `list_threads`, `get_thread_arc`, `search_metadata`) accept `page` and `page_size` arguments and return `total_count` / `total_pages` in the response envelope.
 
@@ -166,6 +301,27 @@ npm install
 WRITING_SYNC_DIR=./my-manuscript DB_PATH=./writing.db npm start
 ```
 
+The `npm start` script automatically includes the `--experimental-sqlite` flag needed for SQLite support in Node.js 22+.
+
+## Verify your setup
+
+After starting the server, test that it's working:
+
+```sh
+# In a new terminal
+curl http://localhost:3000/healthz
+# Should return: ok
+```
+
+Then test the MCP endpoint:
+
+```sh
+curl http://localhost:3000/sse
+# Should return a stream endpoint: /message?sessionId=<id>
+```
+
+If both return successfully, the server is ready to use.
+
 ## Development
 
 ```sh
@@ -173,10 +329,90 @@ npm install
 npm test           # unit + integration tests
 npm run test:unit  # unit tests only (no server required)
 npm run lint:metadata      # lint metadata in WRITING_SYNC_DIR or ./sync
-npm run lint:metadata:test # lint fixture metadata in ./test-sync
 ```
 
-Unit tests use an in-memory SQLite database and temporary directories — no server needed. Integration tests spawn a real server against `test-sync/` on port 3099 and verify all MCP tools end-to-end.
+Unit tests use an in-memory SQLite database and temporary directories — no server needed. Integration tests generate a fixture sync tree at runtime in temporary directories, spawn a real server on port 3099, and verify all MCP tools end-to-end.
+
+For real projects, keep your manuscript sync folder outside this tool repository and point `WRITING_SYNC_DIR` at that external path.
+
+## Troubleshooting
+
+### "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.
+
+**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)
+
+### "EADDRINUSE: address already in use :::3000"
+
+**Cause:** Port 3000 is already in use by another application.
+
+**Solution:**
+Use a different port:
+
+```sh
+HTTP_PORT=3001 WRITING_SYNC_DIR=./my-manuscript DB_PATH=./writing.db npm start
+```
+
+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.
+
+**Solution:**
+Create the directory first:
+
+```sh
+mkdir -p $(dirname ./writing.db)  # if using a subdirectory
+WRITING_SYNC_DIR=./my-manuscript DB_PATH=./writing.db npm start
+```
+
+Or use an absolute path:
+
+```sh
+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.
+
+**Solution:**
+Create the sync folder first:
+
+```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.
+
+**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`
+
+### Tests fail after updating Node.js
+
+**Cause:** SQLite module cache may be stale.
+
+**Solution:**
+Clear npm cache and reinstall:
+
+```sh
+rm -rf node_modules package-lock.json
+npm install
+npm test
+```
 
 ## Environment variables
 

package/git.js

@@ -0,0 +1,190 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Check if a directory is itself the root of a git repository (not just inside one).
+ * This prevents mcp-writing's own .git from being used for prose snapshots when
+ * WRITING_SYNC_DIR is a subdirectory of the code repo.
+ */
+export function isGitRepository(dirPath) {
+  try {
+    const gitRoot = execSync("git rev-parse --show-toplevel", {
+      cwd: dirPath,
+      stdio: "pipe",
+      encoding: "utf8",
+    }).trim();
+    return path.resolve(gitRoot) === path.resolve(dirPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Initialize a git repository in a directory
+ */
+export function initGitRepository(dirPath) {
+  try {
+    execSync("git init", { cwd: dirPath, stdio: "pipe" });
+    // Set a dummy user config for commits if not already set
+    try {
+      execSync("git config user.email", { cwd: dirPath, stdio: "pipe" });
+    } catch {
+      execSync("git config user.email writing-mcp@local", { cwd: dirPath, stdio: "pipe" });
+      execSync("git config user.name writing-mcp", { cwd: dirPath, stdio: "pipe" });
+    }
+    return true;
+  } catch (err) {
+    throw new Error(`Failed to initialize git repository: ${err.message}`);
+  }
+}
+
+/**
+ * Check if git is available on PATH
+ */
+export function isGitAvailable() {
+  try {
+    execSync("git --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a git commit for a scene file (pre-edit snapshot)
+ * Returns { commit_hash: string, commit_message: string }
+ */
+export function createSnapshot(dirPath, filePath, sceneId, instruction) {
+  try {
+    const relPath = path.relative(dirPath, filePath);
+    execSync(`git add "${relPath}"`, { cwd: dirPath, stdio: "pipe" });
+
+    const commitMessage = `pre-edit snapshot: ${sceneId} — ${instruction}`;
+    // Use 2>&1 so git's stderr (where it prints "[branch hash] msg") is captured in stdout
+    const output = execSync(`git commit -m "${commitMessage.replace(/"/g, '\\"')}" 2>&1`, {
+      cwd: dirPath,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+
+    // git outputs "[branch hash] message" to stderr; redirect 2>&1 captures it in stdout
+    // Regex handles any branch name, with or without (root-commit)
+    const match = output.match(/\[\S+(?:\s+\(root-commit\))?\s+([a-f0-9]+)\]/);
+    const commitHash = match ? match[1] : null;
+
+    return {
+      commit_hash: commitHash,
+      commit_message: commitMessage,
+    };
+  } catch (err) {
+    // Check if nothing changed (no error, just no commit)
+    if (err.message.includes("nothing to commit") || err.status === 1) {
+      return {
+        commit_hash: null,
+        commit_message: null,
+        reason: "no changes to commit",
+      };
+    }
+    throw new Error(`Failed to create snapshot: ${err.message}`);
+  }
+}
+
+/**
+ * List git commits for a file, with timestamps and messages
+ * Returns array of { commit_hash, timestamp, message }
+ */
+export function listSnapshots(dirPath, filePath) {
+  try {
+    const relPath = path.relative(dirPath, filePath);
+    const output = execSync(
+      `git log --pretty=format:"%h|%ai|%s" -- "${relPath}"`,
+      {
+        cwd: dirPath,
+        stdio: "pipe",
+        encoding: "utf8",
+      }
+    );
+
+    if (!output) return [];
+
+    return output
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const [hash, timestamp, ...messageParts] = line.split("|");
+        return {
+          commit_hash: hash.trim(),
+          timestamp: timestamp.trim(),
+          message: messageParts.join("|").trim(),
+        };
+      });
+  } catch (err) {
+    // If there are no commits yet, return empty array
+    if (err.message.includes("your current branch") || err.status === 128) {
+      return [];
+    }
+    throw new Error(`Failed to list snapshots: ${err.message}`);
+  }
+}
+
+/**
+ * Get prose content from a specific git commit
+ * If commit is null, returns current working tree version
+ */
+export function getSceneProseAtCommit(dirPath, filePath, commitHash) {
+  try {
+    const relPath = path.relative(dirPath, filePath);
+
+    if (!commitHash) {
+      // Return current working tree version
+      return fs.readFileSync(filePath, "utf8");
+    }
+
+    // Get version from git
+    const content = execSync(`git show ${commitHash}:"${relPath}"`, {
+      cwd: dirPath,
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+
+    return content;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`File not found in commit ${commitHash}`);
+    }
+    throw new Error(`Failed to retrieve scene prose: ${err.message}`);
+  }
+}
+
+/**
+ * Check if working tree is clean (no uncommitted changes)
+ */
+export function isWorkingTreeClean(dirPath) {
+  try {
+    const output = execSync("git status --porcelain", {
+      cwd: dirPath,
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    return output.trim() === "";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the HEAD commit hash
+ */
+export function getHeadCommitHash(dirPath) {
+  try {
+    const hash = execSync("git rev-parse HEAD", {
+      cwd: dirPath,
+      stdio: "pipe",
+      encoding: "utf8",
+    }).trim();
+    return hash;
+  } catch {
+    return null;
+  }
+}