@hanna84/mcp-writing 3.7.1 → 3.8.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.8.0](https://github.com/hannasdev/mcp-writing/compare/v3.7.1...v3.8.0)
+
+- feat: add canonical chapter and epigraph indexing [`#193`](https://github.com/hannasdev/mcp-writing/pull/193)
+
 #### [v3.7.1](https://github.com/hannasdev/mcp-writing/compare/v3.7.0...v3.7.1)
 
+> 14 May 2026
+
 - Docs/chapter epigraph migration gates [`#192`](https://github.com/hannasdev/mcp-writing/pull/192)
+- Release 3.7.1 [`3516818`](https://github.com/hannasdev/mcp-writing/commit/3516818e333b4f6667116eb86657d07b31a9b761)
 
 #### [v3.7.0](https://github.com/hannasdev/mcp-writing/compare/v3.6.2...v3.7.0)
 

package/README.md

@@ -28,9 +28,9 @@ 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 delivered:** Guideline generation is now delivered and tracked in done PRDs.
-- **Active development:** OpenClaw integration is the current focus area.
-- **Deferred backlog:** embeddings search is intentionally deferred for later exploration.
+- **Active development:** OpenClaw integration, the client-agnostic setup contract, and chapter-structure follow-up work after the first-class chapter/epigraph rollout.
+- **Deferred backlog:** 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.7.1",
+  "version": "3.8.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/db.js

@@ -2,6 +2,19 @@ import { DatabaseSync } from "node:sqlite";
 
 const dbStartupWarnings = [];
 
+function slugifyLegacyChapterValue(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function formatLegacyChapterId(sortIndex, title) {
+  const chapterNumber = String(sortIndex).padStart(2, "0");
+  const chapterSlug = slugifyLegacyChapterValue(title) || `chapter-${sortIndex}`;
+  return `ch-${chapterNumber}-${chapterSlug}`;
+}
+
 function cloneWarningDetails(details) {
   if (!details) return details;
 
@@ -46,6 +59,8 @@ export const SCHEMA = `
   CREATE TABLE IF NOT EXISTS scenes (
     scene_id          TEXT NOT NULL,
     project_id        TEXT NOT NULL REFERENCES projects(project_id),
+    chapter_id        TEXT,
+    scene_role        TEXT,
     title             TEXT,
     part              INTEGER,
     chapter           INTEGER,
@@ -67,6 +82,47 @@ export const SCHEMA = `
     PRIMARY KEY (scene_id, project_id)
   );
 
+  CREATE TABLE IF NOT EXISTS chapters (
+    chapter_id        TEXT NOT NULL,
+    project_id        TEXT NOT NULL REFERENCES projects(project_id),
+    title             TEXT NOT NULL,
+    sort_index        INTEGER NOT NULL,
+    logline           TEXT,
+    source_path       TEXT,
+    source_checksum   TEXT,
+    metadata_stale    INTEGER NOT NULL DEFAULT 0,
+    updated_at        TEXT NOT NULL,
+    PRIMARY KEY (chapter_id, project_id),
+    UNIQUE (project_id, sort_index)
+  );
+
+  CREATE TABLE IF NOT EXISTS epigraphs (
+    epigraph_id       TEXT NOT NULL,
+    project_id        TEXT NOT NULL REFERENCES projects(project_id),
+    chapter_id        TEXT NOT NULL,
+    body              TEXT NOT NULL,
+    file_path         TEXT NOT NULL,
+    prose_checksum    TEXT,
+    metadata_stale    INTEGER NOT NULL DEFAULT 0,
+    updated_at        TEXT NOT NULL,
+    PRIMARY KEY (epigraph_id, project_id),
+    UNIQUE (project_id, chapter_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS epigraph_characters (
+    epigraph_id       TEXT NOT NULL,
+    project_id        TEXT NOT NULL,
+    character_id      TEXT NOT NULL,
+    PRIMARY KEY (epigraph_id, project_id, character_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS epigraph_tags (
+    epigraph_id       TEXT NOT NULL,
+    project_id        TEXT NOT NULL,
+    tag               TEXT NOT NULL,
+    PRIMARY KEY (epigraph_id, project_id, tag)
+  );
+
   CREATE TABLE IF NOT EXISTS scene_characters (
     scene_id     TEXT NOT NULL,
     project_id   TEXT NOT NULL,
@@ -484,6 +540,141 @@ const MIGRATIONS = [
       });
     }
   },
+  // 8: add canonical chapter/epigraph entities and scene linkage fields
+  (db) => {
+    const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
+    if (!sceneColumns.some(c => c.name === "chapter_id")) {
+      db.exec(`ALTER TABLE scenes ADD COLUMN chapter_id TEXT;`);
+    }
+    if (!sceneColumns.some(c => c.name === "scene_role")) {
+      db.exec(`ALTER TABLE scenes ADD COLUMN scene_role TEXT;`);
+    }
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS chapters (
+        chapter_id        TEXT NOT NULL,
+        project_id        TEXT NOT NULL REFERENCES projects(project_id),
+        title             TEXT NOT NULL,
+        sort_index        INTEGER NOT NULL,
+        logline           TEXT,
+        source_path       TEXT,
+        source_checksum   TEXT,
+        metadata_stale    INTEGER NOT NULL DEFAULT 0,
+        updated_at        TEXT NOT NULL,
+        PRIMARY KEY (chapter_id, project_id),
+        UNIQUE (project_id, sort_index)
+      );
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS epigraphs (
+        epigraph_id       TEXT NOT NULL,
+        project_id        TEXT NOT NULL REFERENCES projects(project_id),
+        chapter_id        TEXT NOT NULL,
+        body              TEXT NOT NULL,
+        file_path         TEXT NOT NULL,
+        prose_checksum    TEXT,
+        metadata_stale    INTEGER NOT NULL DEFAULT 0,
+        updated_at        TEXT NOT NULL,
+        PRIMARY KEY (epigraph_id, project_id),
+        UNIQUE (project_id, chapter_id)
+      );
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS epigraph_characters (
+        epigraph_id       TEXT NOT NULL,
+        project_id        TEXT NOT NULL,
+        character_id      TEXT NOT NULL,
+        PRIMARY KEY (epigraph_id, project_id, character_id)
+      );
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS epigraph_tags (
+        epigraph_id       TEXT NOT NULL,
+        project_id        TEXT NOT NULL,
+        tag               TEXT NOT NULL,
+        PRIMARY KEY (epigraph_id, project_id, tag)
+      );
+    `);
+  },
+  // 9: backfill canonical chapters and scene chapter_id values from legacy scene chapter fields
+  (db) => {
+    const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
+    const hasChapterId = sceneColumns.some((column) => column.name === "chapter_id");
+    const hasLegacyChapter = sceneColumns.some((column) => column.name === "chapter");
+    const hasLegacyChapterTitle = sceneColumns.some((column) => column.name === "chapter_title");
+    if (!hasChapterId || !hasLegacyChapter || !hasLegacyChapterTitle) {
+      return;
+    }
+
+    const legacyChapters = db.prepare(`
+      SELECT
+        project_id,
+        chapter AS sort_index,
+        COALESCE(NULLIF(TRIM(chapter_title), ''), '') AS chapter_title,
+        COALESCE(NULLIF(TRIM(file_path), ''), '') AS file_path,
+        COALESCE(NULLIF(TRIM(updated_at), ''), '') AS updated_at
+      FROM scenes
+      WHERE chapter IS NOT NULL
+      ORDER BY project_id, chapter, timeline_position, scene_id
+    `).all();
+
+    const chapterRows = new Map();
+    for (const row of legacyChapters) {
+      const key = `${row.project_id}::${row.sort_index}`;
+      if (chapterRows.has(key)) continue;
+      const title = row.chapter_title || `Chapter ${row.sort_index}`;
+      chapterRows.set(key, {
+        chapter_id: formatLegacyChapterId(row.sort_index, title),
+        project_id: row.project_id,
+        title,
+        sort_index: row.sort_index,
+        source_path: row.file_path ? row.file_path.replace(/[\\/][^\\/]+$/, "") : null,
+        updated_at: row.updated_at || new Date().toISOString(),
+      });
+    }
+
+    const insertChapter = db.prepare(`
+      INSERT INTO chapters (
+        chapter_id, project_id, title, sort_index, logline, source_path, source_checksum, metadata_stale, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (project_id, sort_index) DO UPDATE SET
+        title = COALESCE(chapters.title, excluded.title),
+        source_path = COALESCE(chapters.source_path, excluded.source_path),
+        updated_at = CASE
+          WHEN chapters.updated_at IS NULL OR chapters.updated_at = '' THEN excluded.updated_at
+          ELSE chapters.updated_at
+        END
+    `);
+
+    for (const chapter of chapterRows.values()) {
+      insertChapter.run(
+        chapter.chapter_id,
+        chapter.project_id,
+        chapter.title,
+        chapter.sort_index,
+        null,
+        chapter.source_path,
+        null,
+        0,
+        chapter.updated_at
+      );
+    }
+
+    db.exec(`
+      UPDATE scenes
+      SET chapter_id = (
+        SELECT c.chapter_id
+        FROM chapters c
+        WHERE c.project_id = scenes.project_id
+          AND c.sort_index = scenes.chapter
+      )
+      WHERE chapter IS NOT NULL
+        AND (chapter_id IS NULL OR chapter_id = '');
+    `);
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —

package/src/core/helpers.js

@@ -105,6 +105,7 @@ export function resolveBatchTargetScenes(dbHandle, {
   sceneIds,
   part,
   chapter,
+  chapterId,
   onlyStale,
 }) {
   const projectExists = Boolean(
@@ -139,6 +140,10 @@ export function resolveBatchTargetScenes(dbHandle, {
     conditions.push("chapter = ?");
     params.push(chapter);
   }
+  if (chapterId !== undefined) {
+    conditions.push("chapter_id = ?");
+    params.push(chapterId);
+  }
   if (onlyStale) {
     conditions.push("metadata_stale = 1");
   }
@@ -147,7 +152,7 @@ export function resolveBatchTargetScenes(dbHandle, {
     SELECT scene_id, project_id, file_path
     FROM scenes
     WHERE ${conditions.join(" AND ")}
-    ORDER BY part, chapter, timeline_position
+    ORDER BY part, chapter, timeline_position, scene_id
   `;
 
   return {

package/src/review-bundles/review-bundles-planner.js

@@ -125,6 +125,7 @@ export function buildReviewBundlePlan(dbHandle, {
   profile,
   part,
   chapter,
+  chapter_id,
   chapters,
   tag,
   scene_ids,
@@ -167,11 +168,12 @@ export function buildReviewBundlePlan(dbHandle, {
   assertProfile(profile);
   assertStrictness(strictness);
   assertFormat(format);
-  if (chapter !== undefined && chapters !== undefined) {
+  const chapterFilterCount = [chapter !== undefined, chapter_id !== undefined, chapters !== undefined].filter(Boolean).length;
+  if (chapterFilterCount > 1) {
     throw new ReviewBundlePlanError(
       "INVALID_CHAPTER_FILTER",
-      "Use either chapter or chapters, not both.",
-      { chapter, chapters }
+      "Use one of chapter, chapter_id, or chapters.",
+      { chapter, chapter_id, chapters }
     );
   }
   let normalizedChapters;
@@ -222,6 +224,10 @@ export function buildReviewBundlePlan(dbHandle, {
     conditions.push("s.chapter = ?");
     conditionParams.push(chapter);
   }
+  if (chapter_id !== undefined) {
+    conditions.push("s.chapter_id = ?");
+    conditionParams.push(chapter_id);
+  }
   if (Array.isArray(normalizedChapters) && normalizedChapters.length > 0) {
     const placeholders = normalizedChapters.map(() => "?").join(",");
     conditions.push(`s.chapter IN (${placeholders})`);
@@ -259,6 +265,7 @@ export function buildReviewBundlePlan(dbHandle, {
         filters: {
           ...(part !== undefined ? { part } : {}),
           ...(chapter !== undefined ? { chapter } : {}),
+          ...(chapter_id !== undefined ? { chapter_id } : {}),
           ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
           ...(tag ? { tag } : {}),
           ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
@@ -345,6 +352,7 @@ export function buildReviewBundlePlan(dbHandle, {
   const appliedFilters = {
     ...(part !== undefined ? { part } : {}),
     ...(chapter !== undefined ? { chapter } : {}),
+    ...(chapter_id !== undefined ? { chapter_id } : {}),
     ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
     ...(tag ? { tag } : {}),
     ...(Array.isArray(normalizedSceneIds) ? { scene_ids: normalizedSceneIds } : {}),

package/src/review-bundles/review-bundles-renderer.js

@@ -75,19 +75,23 @@ function loadBundleSceneRowsWithTags(dbHandle, projectId, sceneIds) {
     const placeholders = chunk.map(() => "?").join(",");
     const chunkRows = dbHandle.prepare(`
       SELECT
-        scene_id,
-        project_id,
-        title,
-        part,
-        chapter,
-        chapter_title,
-        timeline_position,
-        logline,
-        pov,
-        save_the_cat_beat,
-        file_path
+        s.scene_id,
+        s.project_id,
+        s.chapter_id,
+        s.scene_role,
+        s.title,
+        s.part,
+        s.chapter,
+        COALESCE(c.title, s.chapter_title) AS chapter_title,
+        s.timeline_position,
+        s.logline,
+        s.pov,
+        s.save_the_cat_beat,
+        s.file_path
       FROM scenes
-      WHERE project_id = ? AND scene_id IN (${placeholders})
+      s
+      LEFT JOIN chapters c ON c.chapter_id = s.chapter_id AND c.project_id = s.project_id
+      WHERE s.project_id = ? AND s.scene_id IN (${placeholders})
     `).all(projectId, ...chunk);
     rows.push(...chunkRows);
   }
@@ -145,6 +149,26 @@ function loadBundleSceneRowsWithTags(dbHandle, projectId, sceneIds) {
   return orderedRows;
 }
 
+function loadEpigraphsByChapter(dbHandle, projectId) {
+  const rows = dbHandle.prepare(`
+    SELECT e.epigraph_id, e.chapter_id, e.body, c.title AS chapter_title, c.sort_index AS chapter
+    FROM epigraphs e
+    JOIN chapters c ON c.chapter_id = e.chapter_id AND c.project_id = e.project_id
+    WHERE e.project_id = ?
+    ORDER BY c.sort_index, e.epigraph_id
+  `).all(projectId);
+
+  return new Map(rows.map(row => [row.chapter_id, {
+    scene_id: row.epigraph_id,
+    chapter_id: row.chapter_id,
+    chapter: row.chapter,
+    chapter_title: row.chapter_title,
+    title: "Epigraph",
+    prose: String(row.body ?? "").trim(),
+    tags: ["epigraph"],
+  }]));
+}
+
 function normalizeRelativePath(inputPath) {
   return String(inputPath).replace(/\\/g, "/").replace(/^\.\//, "");
 }
@@ -381,6 +405,7 @@ function renderProseWithInlineEmphasis(doc, prose, {
 }
 
 function isEpigraphScene(scene) {
+  if (scene?.entity_kind === "epigraph") return true;
   const tags = Array.isArray(scene?.tags)
     ? scene.tags
       .map(tag => String(tag ?? "").trim().toLowerCase())
@@ -392,6 +417,10 @@ function isEpigraphScene(scene) {
   return /^epigraph(?:\b|\s|[-:])/i.test(title);
 }
 
+function isCanonicalEpigraphInsert(scene) {
+  return scene?.entity_kind === "epigraph";
+}
+
 function renderSceneBlock(scene, options) {
   const {
     profile,
@@ -402,7 +431,9 @@ function renderSceneBlock(scene, options) {
   } = options;
 
   const isBetaProfile = profile === "beta_reader_personalized";
-  const isEpigraph = isBetaProfile && isEpigraphScene(scene);
+  const isOutlineProfile = profile === "outline_discussion";
+  const isEpigraph = (isBetaProfile || isOutlineProfile) && isEpigraphScene(scene);
+  const isCanonicalEpigraph = isCanonicalEpigraphInsert(scene);
 
   const parts = [];
 
@@ -421,6 +452,11 @@ function renderSceneBlock(scene, options) {
   }
 
   if (profile === "outline_discussion") {
+    if (isCanonicalEpigraph) {
+      const prose = normalizeHardWrappedProse(scene.prose ?? "");
+      if (prose) parts.push(prose);
+      return parts.join("\n\n");
+    }
     const summaryParts = [];
     if (scene.pov) summaryParts.push(`POV: ${scene.pov}`);
     if (scene.save_the_cat_beat) summaryParts.push(`Beat: ${scene.save_the_cat_beat}`);
@@ -535,6 +571,7 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
 
   const sceneIds = plan.ordering.map(row => row.scene_id);
   const rows = loadBundleSceneRowsWithTags(dbHandle, plan.resolved_scope.project_id, sceneIds);
+  const epigraphsByChapter = loadEpigraphsByChapter(dbHandle, plan.resolved_scope.project_id);
   const sections = [];
   const recipientName = plan.resolved_scope?.options?.recipient_name;
   const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
@@ -586,12 +623,24 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
     const showChapterHeading = isBetaProfile
       && Boolean(scene.chapter_title)
       && (!prevScene || prevScene.chapter !== scene.chapter);
+    if ((!prevScene || prevScene.chapter_id !== scene.chapter_id) && scene.chapter_id && epigraphsByChapter.has(scene.chapter_id)) {
+      sections.push(renderSceneBlock({
+        ...epigraphsByChapter.get(scene.chapter_id),
+        entity_kind: "epigraph",
+      }, {
+        profile,
+        includeSceneIds: false,
+        includeMetadataSidebar: false,
+        includeParagraphAnchors: false,
+        showChapterHeading,
+      }));
+    }
     sections.push(renderSceneBlock(withProse, {
       profile,
       includeSceneIds,
       includeMetadataSidebar,
       includeParagraphAnchors,
-      showChapterHeading,
+      showChapterHeading: showChapterHeading && !epigraphsByChapter.has(scene.chapter_id),
     }));
   }
 
@@ -623,6 +672,7 @@ export function renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt,
 
   const sceneIds = plan.ordering.map(row => row.scene_id);
   const rows = loadBundleSceneRowsWithTags(dbHandle, plan.resolved_scope.project_id, sceneIds);
+  const epigraphsByChapter = loadEpigraphsByChapter(dbHandle, plan.resolved_scope.project_id);
   const recipientName = plan.resolved_scope?.options?.recipient_name;
   const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
   const footerRecipientDisplayName = sanitizeFooterRecipientDisplayName(recipientDisplayName);
@@ -858,6 +908,28 @@ export function renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt,
           }
         }
 
+        if ((!prevScene || prevScene.chapter_id !== scene.chapter_id) && scene.chapter_id && epigraphsByChapter.has(scene.chapter_id)) {
+          const epigraph = epigraphsByChapter.get(scene.chapter_id);
+          const textWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+          const epigraphWidth = Math.round(textWidth * 0.68);
+          const epigraphIndent = Math.round((textWidth - epigraphWidth) / 2);
+          const savedX = doc.x;
+          doc.moveDown(isBetaProfile ? 0.5 : 0.8);
+          doc.x = doc.page.margins.left + epigraphIndent;
+          renderProseWithInlineEmphasis(doc, epigraph.prose, {
+            bodyFont: italicFont,
+            italicFont: bodyFont,
+            fontSize: proseFontSize,
+            align: "left",
+            width: epigraphWidth,
+            lineGap: proseLineGap,
+            paragraphGap: 0,
+            blankLineMoveDown: 0.65,
+          });
+          doc.x = savedX;
+          doc.moveDown(1.0);
+        }
+
         // Skip title for epigraphs in beta and outline profiles.
         const isEpigraph = (isBetaProfile || isOutlineProfile) && isEpigraphScene(scene);
         if (!isEpigraph) {