@hanna84/mcp-writing 3.17.2 → 3.18.0

package/CHANGELOG.md

@@ -4,9 +4,16 @@ 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)
 

package/README.md

@@ -31,7 +31,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 - **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, chapter-structure follow-up, and embeddings search.
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.17.2",
+  "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",

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/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) {