@hanna84/mcp-writing 3.17.1 → 3.18.0

package/CHANGELOG.md

@@ -4,9 +4,23 @@ 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).
 
+#### [v3.18.0](https://github.com/hannasdev/mcp-writing/compare/v3.17.2...v3.18.0)
+
+- feat: complete chapter structure alignment [`#217`](https://github.com/hannasdev/mcp-writing/pull/217)
+
+#### [v3.17.2](https://github.com/hannasdev/mcp-writing/compare/v3.17.1...v3.17.2)
+
+> 23 May 2026
+
+- docs: complete Docker deployment readiness [`#216`](https://github.com/hannasdev/mcp-writing/pull/216)
+- Release 3.17.2 [`e2fb946`](https://github.com/hannasdev/mcp-writing/commit/e2fb946bdbae6ca4c8216edfc578d94ceda7fabf)
+
 #### [v3.17.1](https://github.com/hannasdev/mcp-writing/compare/v3.17.0...v3.17.1)
 
+> 23 May 2026
+
 - docs: add database backup recovery initiative [`#215`](https://github.com/hannasdev/mcp-writing/pull/215)
+- Release 3.17.1 [`a0fa16c`](https://github.com/hannasdev/mcp-writing/commit/a0fa16cac37add24dc1fbcaecd3c4301e9ee2873)
 
 #### [v3.17.0](https://github.com/hannasdev/mcp-writing/compare/v3.16.0...v3.17.0)
 

package/README.md

@@ -28,9 +28,10 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 
 **Current status:**
 - **Core platform complete:** Metadata-first analysis, sidecar-backed metadata maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
-- **Recently completed:** Filesystem Boundary Hardening centralized local file mutation through application-aware helpers and lint guardrails.
-- **Active development:** Docker, CI, and Deployment Workflow is making Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
-- **Deferred backlog:** OpenClaw integration, client-agnostic setup, chapter-structure follow-up, and embeddings search.
+- **Recently completed:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
+- **Previous milestone:** Filesystem Boundary Hardening centralized local file mutation through application-aware helpers and lint guardrails.
+- **Active development:** No active initiative is currently selected.
+- **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, database backup/recovery, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 
 ## Who it is for
@@ -45,7 +46,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 |---|---|
 | [docs/guides/setup.md](docs/guides/setup.md) | Prerequisites, first-time setup, Scrivener import, native sync format |
 | [mcp-writing-vscode](https://github.com/hannasdev/mcp-writing-vscode) | VS Code extension for client-native setup flows |
-| [docs/guides/docker.md](docs/guides/docker.md) | Docker Compose, OpenClaw integration, SSH hardening |
+| [docs/guides/docker.md](docs/guides/docker.md) | Docker Compose, deployment operations, MCP gateway notes |
 | [docs/foundations/managed-structure-contract.md](docs/foundations/managed-structure-contract.md) | Design boundaries for structural mutation, generated views, import, and maintenance workflows |
 | [docs/agents/tools.md](docs/agents/tools.md) | Full tool reference — auto-generated from source |
 | [docs/agents/README.md](docs/agents/README.md) | Index of agent-focused guidance, examples, and boot files |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",
@@ -73,9 +73,10 @@
     "release": "release-it",
     "lint": "eslint *.js eslint-rules src/index.js src/core src/review-bundles src/runtime src/setup src/scripts src/structure src/styleguide src/sync src/tools src/workflows src/world",
     "guard:legacy-root-imports": "node src/scripts/check-legacy-root-imports.mjs",
+    "guard:docker-docs": "node src/scripts/check-docker-docs.mjs",
     "docs": "node src/scripts/generate-tool-docs.mjs",
     "check:docs": "npm run docs && git diff --exit-code -- docs/agents/tools.md",
-    "check:static": "npm run lint && npm run guard:legacy-root-imports && npm run check:docs",
+    "check:static": "npm run lint && npm run guard:legacy-root-imports && npm run guard:docker-docs && npm run check:docs",
     "check:pr": "npm run check:static && npm test",
     "lint:metadata": "node src/scripts/lint-metadata.mjs",
     "sync:server-json-version": "node src/scripts/sync-server-json-version.mjs",

package/src/core/helpers.js

@@ -125,7 +125,7 @@ export function resolveBatchTargetScenes(dbHandle, {
     }
   }
 
-  const conditions = ["project_id = ?"];
+  const conditions = ["s.project_id = ?"];
   const params = [projectId];
   const resolvedChapterFilter = (chapter !== undefined || chapterId !== undefined)
     ? resolveValidatedChapterFilter(dbHandle, { projectId, chapterNumber: chapter, chapterId })
@@ -146,26 +146,27 @@ export function resolveBatchTargetScenes(dbHandle, {
 
   if (sceneIds?.length) {
     const placeholders = sceneIds.map(() => "?").join(",");
-    conditions.push(`scene_id IN (${placeholders})`);
+    conditions.push(`s.scene_id IN (${placeholders})`);
     params.push(...sceneIds);
   }
   if (part !== undefined) {
-    conditions.push("part = ?");
+    conditions.push("s.part = ?");
     params.push(part);
   }
   if (resolvedChapterFilter.chapter) {
-    conditions.push("chapter_id = ?");
+    conditions.push("s.chapter_id = ?");
     params.push(resolvedChapterFilter.chapter.chapter_id);
   }
   if (onlyStale) {
-    conditions.push("metadata_stale = 1");
+    conditions.push("s.metadata_stale = 1");
   }
 
   const query = `
-    SELECT scene_id, project_id, file_path
-    FROM scenes
+    SELECT s.scene_id, s.project_id, s.file_path
+    FROM scenes s
+    LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
     WHERE ${conditions.join(" AND ")}
-    ORDER BY part, chapter, timeline_position, scene_id
+    ORDER BY s.part, COALESCE(c.sort_index, s.chapter), s.timeline_position, s.scene_id
   `;
 
   return {

package/src/scripts/check-docker-docs.mjs

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+const dockerfile = fs.readFileSync(path.join(ROOT, "Dockerfile"), "utf8");
+const compose = fs.readFileSync(path.join(ROOT, "docker-compose.example.yml"), "utf8");
+const guide = fs.readFileSync(path.join(ROOT, "docs", "guides", "docker.md"), "utf8");
+
+const requiredDocSnippets = [
+  "`WRITING_SYNC_DIR`",
+  "`DB_PATH`",
+  "`HTTP_PORT`",
+  "`MCP_TRANSPORT`",
+  "`OWNERSHIP_GUARD_MODE`",
+  "`/sync`",
+  "`/data`",
+  "`/ssh`",
+  "Upgrade Checklist",
+  "Backup Checklist",
+  "Rollback",
+  "Supported Deployment Targets",
+  "OpenClaw",
+];
+
+const requiredComposeSnippets = [
+  "WRITING_SYNC_DIR: /sync",
+  "DB_PATH: /data/writing.db",
+  "HTTP_PORT: \"3000\"",
+  "OWNERSHIP_GUARD_MODE:",
+  "MCP_TRANSPORT: http",
+  "${WRITING_SYNC_DIR_HOST:-./sync}:/sync",
+  "${WRITING_DATA_DIR_HOST:-./data}:/data",
+  "WRITING_SSH_DIR_HOST",
+  "GIT_SSH_COMMAND",
+];
+
+const requiredDockerfileSnippets = [
+  "ENV WRITING_SYNC_DIR=/sync",
+  "ENV DB_PATH=/data/writing.db",
+  "ENV HTTP_PORT=3000",
+  "ENV MCP_TRANSPORT=http",
+  "git openssh-client",
+  "HEALTHCHECK",
+  "/healthz",
+];
+
+const findings = [];
+
+function requireSnippet(label, content, snippet) {
+  if (!content.includes(snippet)) {
+    findings.push(`${label} is missing ${JSON.stringify(snippet)}`);
+  }
+}
+
+for (const snippet of requiredDocSnippets) {
+  requireSnippet("docs/guides/docker.md", guide, snippet);
+}
+
+for (const snippet of requiredComposeSnippets) {
+  requireSnippet("docker-compose.example.yml", compose, snippet);
+}
+
+for (const snippet of requiredDockerfileSnippets) {
+  requireSnippet("Dockerfile", dockerfile, snippet);
+}
+
+if (findings.length > 0) {
+  console.error("Docker docs drift check failed:");
+  for (const finding of findings) {
+    console.error(`- ${finding}`);
+  }
+  process.exit(1);
+}
+
+console.log("Docker docs drift check passed.");

package/src/sync/metadata-lint.js

@@ -30,6 +30,8 @@ const sceneSchema = z.object({
   external_source: z.string().min(1).optional(),
   external_id: z.string().min(1).optional(),
   title: z.string().min(1).optional(),
+  chapter_id: z.string().min(1).nullable().optional(),
+  scene_role: z.enum(["prologue", "epilogue"]).nullable().optional(),
   part: z.number().int().positive().optional(),
   chapter: z.number().int().positive().optional(),
   chapter_title: z.string().min(1).optional(),

package/src/tools/search.js

@@ -112,6 +112,7 @@ export function registerSearchTools(s, {
                s.save_the_cat_beat, s.timeline_position, s.story_time,
                s.word_count, s.metadata_stale
         FROM scenes s
+        LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
       `;
       const joins = [];
       const conditions = [];
@@ -139,7 +140,7 @@ export function registerSearchTools(s, {
 
       if (joins.length)      query += " " + joins.join(" ");
       if (conditions.length) query += " WHERE " + conditions.join(" AND ");
-      query += " ORDER BY s.part, s.chapter, s.timeline_position, s.scene_id";
+      query += " ORDER BY s.part, COALESCE(c.sort_index, s.chapter), s.timeline_position, s.scene_id";
 
       const rows = db.prepare(query).all(...params);
       if (rows.length === 0) {
@@ -424,7 +425,7 @@ export function registerSearchTools(s, {
   // ---- get_arc -------------------------------------------------------------
   s.tool(
     "get_arc",
-    "Get every scene a character appears in, ordered by part/chapter/position. Returns scene metadata only — no prose. Use this as the primary structural entry point when the question is about a character's progression through the manuscript. Supports pagination via page/page_size and auto-paginates large result sets with total_count. Use list_characters only when you need help finding a character_id. Response shape note: always returns a structured envelope (`results`, `total_count`, with pagination fields when paging is active).",
+    "Get every scene a character appears in, ordered by part, canonical chapter order, and scene position. Returns scene metadata only — no prose. Use this as the primary structural entry point when the question is about a character's progression through the manuscript. Supports pagination via page/page_size and auto-paginates large result sets with total_count. Use list_characters only when you need help finding a character_id. Response shape note: always returns a structured envelope (`results`, `total_count`, with pagination fields when paging is active).",
     {
       character_id: z.string().describe("The character_id to trace (e.g. 'char-mira-nystrom'). Use list_characters to find valid IDs."),
       project_id:   z.string().optional().describe("Limit to a specific project (e.g. 'the-lamb')."),
@@ -438,11 +439,12 @@ export function registerSearchTools(s, {
                s.save_the_cat_beat, s.timeline_position, s.story_time, s.pov, s.metadata_stale
         FROM scenes s
         JOIN scene_characters sc ON sc.scene_id = s.scene_id AND sc.project_id = s.project_id
+        LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
         WHERE sc.character_id = ?
       `;
       const params = [character_id];
       if (project_id) { query += ` AND s.project_id = ?`; params.push(project_id); }
-      query += ` ORDER BY s.part, s.chapter, s.timeline_position`;
+      query += ` ORDER BY s.part, COALESCE(c.sort_index, s.chapter), s.timeline_position, s.scene_id`;
 
       const rows = db.prepare(query).all(...params);
       if (rows.length === 0) {
@@ -1000,7 +1002,8 @@ export function registerSearchTools(s, {
                st.beat AS thread_beat, s.timeline_position, s.story_time, s.metadata_stale
         FROM scenes s
         JOIN scene_threads st ON st.scene_id = s.scene_id AND st.project_id = s.project_id AND st.thread_id = ?
-        ORDER BY s.part, s.chapter, s.timeline_position, s.scene_id
+        LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
+        ORDER BY s.part, COALESCE(c.sort_index, s.chapter), s.timeline_position, s.scene_id
       `).all(thread_id);
       const staleCount = rows.filter(r => r.metadata_stale).length;
       const warning = staleCount > 0 ? `${staleCount} scene(s) have stale metadata.` : undefined;
@@ -1047,11 +1050,12 @@ export function registerSearchTools(s, {
         FROM character_relationships r
         LEFT JOIN scenes s ON s.scene_id = r.scene_id
           AND (r.scene_id IS NULL OR s.project_id = COALESCE(?, s.project_id))
+        LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
         WHERE r.from_character = ? AND r.to_character = ?
       `;
       const params = [project_id ?? null, from_character, to_character];
       if (project_id) { query += ` AND (s.project_id = ? OR r.scene_id IS NULL)`; params.push(project_id); }
-      query += ` ORDER BY s.part, s.chapter, s.timeline_position, s.scene_id`;
+      query += ` ORDER BY s.part, COALESCE(c.sort_index, s.chapter), s.timeline_position, s.scene_id`;
 
       const rows = db.prepare(query).all(...params);
       if (rows.length === 0) {