@hanna84/mcp-writing 3.11.0 → 3.12.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.12.0](https://github.com/hannasdev/mcp-writing/compare/v3.11.0...v3.12.0)
+
+- feat(structure): normalize chapter compatibility resolution [`#204`](https://github.com/hannasdev/mcp-writing/pull/204)
+
 #### [v3.11.0](https://github.com/hannasdev/mcp-writing/compare/v3.10.0...v3.11.0)
 
+> 18 May 2026
+
 - feat(structure): add explicit scene chapter assignment [`#203`](https://github.com/hannasdev/mcp-writing/pull/203)
+- Release 3.11.0 [`7e73355`](https://github.com/hannasdev/mcp-writing/commit/7e73355bb4bb38845daf90e0d438e3c7e3c9c268)
 
 #### [v3.10.0](https://github.com/hannasdev/mcp-writing/compare/v3.9.5...v3.10.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.11.0",
+  "version": "3.12.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/chapter-resolution.js

@@ -1,29 +1,85 @@
-export function resolveChapterByCompatibilityKey(db, { projectId, chapterNumber, chapterId }) {
-  if (!projectId) return null;
-  if (chapterId) {
-    return db.prepare(`
-      SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
-      FROM chapters
-      WHERE project_id = ? AND chapter_id = ?
-    `).get(projectId, chapterId);
-  }
-  if (chapterNumber == null) return null;
+function chapterNotFoundError({ chapterNumber, chapterId }) {
+  return {
+    code: "NOT_FOUND",
+    message: "Chapter not found for the provided project and identifier.",
+    details: {
+      chapter: chapterNumber ?? null,
+      chapter_id: chapterId ?? null,
+    },
+  };
+}
+
+function ambiguousChapterError({ projectId, chapterNumber, candidates }) {
+  return {
+    code: "AMBIGUOUS_CHAPTER",
+    message: `Compatibility chapter ${chapterNumber} resolves to multiple canonical chapter identities in project '${projectId}'. Use chapter_id instead.`,
+    details: {
+      project_id: projectId,
+      chapter: chapterNumber,
+      candidate_chapter_ids: candidates.map(row => row.chapter_id),
+    },
+  };
+}
+
+function selectCanonicalChapterById(db, { projectId, chapterId }) {
+  return db.prepare(`
+    SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, chapterId);
+}
 
-  const canonicalChapter = db.prepare(`
+function selectCanonicalChaptersByNumber(db, { projectId, chapterNumber }) {
+  return db.prepare(`
     SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
     FROM chapters
     WHERE project_id = ? AND sort_index = ?
-  `).get(projectId, chapterNumber);
-  if (canonicalChapter) return canonicalChapter;
+    ORDER BY chapter_id
+  `).all(projectId, chapterNumber);
+}
 
+function selectSceneDerivedChaptersByNumber(db, { projectId, chapterNumber }) {
   return db.prepare(`
-    SELECT chapter_id, project_id, chapter_title AS title, chapter AS sort_index, NULL AS logline, MAX(metadata_stale) AS metadata_stale
+    SELECT
+      chapter_id,
+      project_id,
+      COALESCE(MAX(chapter_title), chapter_id) AS title,
+      chapter AS sort_index,
+      NULL AS logline,
+      MAX(metadata_stale) AS metadata_stale
     FROM scenes
-    WHERE project_id = ? AND chapter = ? AND chapter_id IS NOT NULL
-    GROUP BY chapter_id, project_id, chapter_title, chapter
+    WHERE project_id = ?
+      AND chapter = ?
+      AND chapter_id IS NOT NULL
+      AND chapter_id != ''
+    GROUP BY chapter_id, project_id, chapter
     ORDER BY chapter_id
-    LIMIT 1
-  `).get(projectId, chapterNumber);
+  `).all(projectId, chapterNumber);
+}
+
+export function resolveChapterByCompatibilityKey(db, { projectId, chapterNumber, chapterId }) {
+  const result = resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber, chapterId });
+  return result?.chapter ?? null;
+}
+
+export function resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber, chapterId }) {
+  if (!projectId) return { chapter: null };
+  if (chapterId) {
+    return { chapter: selectCanonicalChapterById(db, { projectId, chapterId }) ?? null };
+  }
+  if (chapterNumber == null) return { chapter: null };
+
+  const canonicalChapters = selectCanonicalChaptersByNumber(db, { projectId, chapterNumber });
+  if (canonicalChapters.length > 1) {
+    return { error: ambiguousChapterError({ projectId, chapterNumber, candidates: canonicalChapters }) };
+  }
+  if (canonicalChapters.length === 1) return { chapter: canonicalChapters[0] };
+
+  const sceneDerivedChapters = selectSceneDerivedChaptersByNumber(db, { projectId, chapterNumber });
+  if (sceneDerivedChapters.length > 1) {
+    return { error: ambiguousChapterError({ projectId, chapterNumber, candidates: sceneDerivedChapters }) };
+  }
+  return { chapter: sceneDerivedChapters[0] ?? null };
 }
 
 export function resolveValidatedChapterFilter(db, { projectId, chapterNumber, chapterId }) {
@@ -31,31 +87,103 @@ export function resolveValidatedChapterFilter(db, { projectId, chapterNumber, ch
   if (!chapterId && chapterNumber == null) return { chapter: null };
 
   const resolvedById = chapterId
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterId })
+    ? resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterId })
     : null;
   const resolvedByNumber = chapterNumber != null
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterNumber })
+    ? resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber })
     : null;
 
+  if (resolvedById?.error) return { error: resolvedById.error };
+  if (resolvedByNumber?.error) return { error: resolvedByNumber.error };
+
+  if (chapterId && !resolvedById?.chapter) {
+    return { error: chapterNotFoundError({ chapterNumber, chapterId }) };
+  }
+  if (chapterNumber != null && !resolvedByNumber?.chapter) {
+    return { error: chapterNotFoundError({ chapterNumber, chapterId }) };
+  }
+
   if (chapterId && chapterNumber != null) {
-    if (!resolvedById || !resolvedByNumber) {
+    if (resolvedById.chapter.chapter_id !== resolvedByNumber.chapter.chapter_id) {
       return {
         error: {
-          code: "NOT_FOUND",
-          message: "Chapter not found for the provided project and identifier.",
+          code: "VALIDATION_ERROR",
+          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
+          details: {
+            chapter_id: resolvedById.chapter.chapter_id,
+            chapter: chapterNumber,
+            resolved_chapter_id: resolvedByNumber.chapter.chapter_id,
+          },
         },
       };
     }
-    if (resolvedById.chapter_id !== resolvedByNumber.chapter_id) {
+    return { chapter: resolvedById.chapter };
+  }
+
+  return { chapter: resolvedById?.chapter ?? resolvedByNumber?.chapter ?? null };
+}
+
+export function resolveValidatedChapterNumberFilters(db, { projectId, chapterNumbers }) {
+  if (!projectId || chapterNumbers == null) return { chapters: [] };
+  const invalidChapterNumbers = chapterNumbers.filter(value => !Number.isInteger(value));
+  if (invalidChapterNumbers.length > 0) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "chapters must contain only integer chapter numbers.",
+        details: {
+          project_id: projectId,
+          invalid_chapters: invalidChapterNumbers,
+          requested_chapters: chapterNumbers,
+        },
+      },
+    };
+  }
+  const normalizedChapterNumbers = Array.from(new Set(chapterNumbers)).sort((a, b) => a - b);
+  const chapters = [];
+  const seenChapterIds = new Set();
+
+  for (const chapterNumber of normalizedChapterNumbers) {
+    const resolved = resolveValidatedChapterFilter(db, {
+      projectId,
+      chapterNumber,
+    });
+
+    if (resolved.error) {
       return {
         error: {
-          code: "VALIDATION_ERROR",
-          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
+          ...resolved.error,
+          details: {
+            ...(resolved.error.details ?? {}),
+            project_id: projectId,
+            requested_chapters: normalizedChapterNumbers,
+          },
         },
       };
     }
-    return { chapter: resolvedById };
+
+    if (!resolved.chapter) {
+      return {
+        error: {
+          code: "NOT_FOUND",
+          message: "Chapter not found for the provided project and identifier.",
+          details: {
+            project_id: projectId,
+            chapter: chapterNumber,
+            requested_chapters: normalizedChapterNumbers,
+          },
+        },
+      };
+    }
+
+    if (!seenChapterIds.has(resolved.chapter.chapter_id)) {
+      chapters.push(resolved.chapter);
+      seenChapterIds.add(resolved.chapter.chapter_id);
+    }
   }
 
-  return { chapter: resolvedById ?? resolvedByNumber ?? null };
+  return {
+    chapters,
+    chapter_numbers: normalizedChapterNumbers,
+  };
 }

package/src/core/helpers.js

@@ -156,12 +156,6 @@ export function resolveBatchTargetScenes(dbHandle, {
   if (resolvedChapterFilter.chapter) {
     conditions.push("chapter_id = ?");
     params.push(resolvedChapterFilter.chapter.chapter_id);
-  } else if (chapterId !== undefined) {
-    conditions.push("chapter_id = ?");
-    params.push(chapterId);
-  } else if (chapter !== undefined) {
-    conditions.push("chapter = ?");
-    params.push(chapter);
   }
   if (onlyStale) {
     conditions.push("metadata_stale = 1");

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

@@ -1,3 +1,8 @@
+import {
+  resolveValidatedChapterFilter,
+  resolveValidatedChapterNumberFilters,
+} from "../core/chapter-resolution.js";
+
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
 const MAX_SCENE_ID_FILTER_PARAMS = 900;
 const MAX_CHAPTER_FILTER_PARAMS = 900;
@@ -33,7 +38,7 @@ function sceneSort(a, b) {
   const partDiff = normalizeSortNumber(a.part) - normalizeSortNumber(b.part);
   if (partDiff !== 0) return partDiff;
 
-  const chapterDiff = normalizeSortNumber(a.chapter) - normalizeSortNumber(b.chapter);
+  const chapterDiff = normalizeSortNumber(a.canonical_chapter_sort ?? a.chapter) - normalizeSortNumber(b.canonical_chapter_sort ?? b.chapter);
   if (chapterDiff !== 0) return chapterDiff;
 
   const timelineDiff = normalizeSortNumber(a.timeline_position) - normalizeSortNumber(b.timeline_position);
@@ -201,6 +206,40 @@ export function buildReviewBundlePlan(dbHandle, {
     throw new ReviewBundlePlanError("NOT_FOUND", `Project '${project_id}' not found.`);
   }
 
+  const resolvedChapterFilter = (chapter !== undefined || chapter_id !== undefined)
+    ? resolveValidatedChapterFilter(dbHandle, {
+        projectId: project_id,
+        chapterNumber: chapter,
+        chapterId: chapter_id,
+      })
+    : { chapter: null };
+  if (resolvedChapterFilter.error) {
+    throw new ReviewBundlePlanError(
+      resolvedChapterFilter.error.code,
+      resolvedChapterFilter.error.message,
+      {
+        ...(resolvedChapterFilter.error.details ?? {}),
+        project_id,
+        chapter: chapter ?? null,
+        chapter_id: chapter_id ?? null,
+      }
+    );
+  }
+
+  const resolvedChapterSet = Array.isArray(normalizedChapters)
+    ? resolveValidatedChapterNumberFilters(dbHandle, {
+        projectId: project_id,
+        chapterNumbers: normalizedChapters,
+      })
+    : { chapters: [] };
+  if (resolvedChapterSet.error) {
+    throw new ReviewBundlePlanError(
+      resolvedChapterSet.error.code,
+      resolvedChapterSet.error.message,
+      resolvedChapterSet.error.details
+    );
+  }
+
   const requestedSceneIds = resolveRequestedSceneIds(dbHandle, project_id, scene_ids);
   const conditions = ["s.project_id = ?"];
   const joins = [];
@@ -220,24 +259,22 @@ export function buildReviewBundlePlan(dbHandle, {
     conditions.push("s.part = ?");
     conditionParams.push(part);
   }
-  if (chapter !== undefined) {
-    conditions.push("s.chapter = ?");
-    conditionParams.push(chapter);
-  }
-  if (chapter_id !== undefined) {
+  if (resolvedChapterFilter.chapter) {
     conditions.push("s.chapter_id = ?");
-    conditionParams.push(chapter_id);
+    conditionParams.push(resolvedChapterFilter.chapter.chapter_id);
   }
-  if (Array.isArray(normalizedChapters) && normalizedChapters.length > 0) {
-    const placeholders = normalizedChapters.map(() => "?").join(",");
-    conditions.push(`s.chapter IN (${placeholders})`);
-    conditionParams.push(...normalizedChapters);
+  if (resolvedChapterSet.chapters.length > 0) {
+    const placeholders = resolvedChapterSet.chapters.map(() => "?").join(",");
+    conditions.push(`s.chapter_id IN (${placeholders})`);
+    conditionParams.push(...resolvedChapterSet.chapters.map(row => row.chapter_id));
   }
 
   let query = `
     SELECT DISTINCT
       s.scene_id,
       s.project_id,
+      s.chapter_id,
+      c.sort_index AS canonical_chapter_sort,
       s.title,
       s.part,
       s.chapter,
@@ -248,6 +285,7 @@ export function buildReviewBundlePlan(dbHandle, {
       s.save_the_cat_beat,
       s.metadata_stale
     FROM scenes s
+    LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
   `;
 
   if (joins.length > 0) {
@@ -354,6 +392,10 @@ export function buildReviewBundlePlan(dbHandle, {
     ...(chapter !== undefined ? { chapter } : {}),
     ...(chapter_id !== undefined ? { chapter_id } : {}),
     ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
+    ...(resolvedChapterFilter.chapter ? { resolved_chapter_id: resolvedChapterFilter.chapter.chapter_id } : {}),
+    ...(resolvedChapterSet.chapters.length > 0
+      ? { resolved_chapter_ids: resolvedChapterSet.chapters.map(row => row.chapter_id) }
+      : {}),
     ...(tag ? { tag } : {}),
     ...(Array.isArray(normalizedSceneIds) ? { scene_ids: normalizedSceneIds } : {}),
   };
@@ -389,9 +431,11 @@ export function buildReviewBundlePlan(dbHandle, {
     ordering: rows.map(row => ({
       scene_id: row.scene_id,
       project_id: row.project_id,
+      chapter_id: row.chapter_id,
       title: row.title,
       part: row.part,
       chapter: row.chapter,
+      canonical_chapter_sort: row.canonical_chapter_sort,
       timeline_position: row.timeline_position,
       metadata_stale: Number(row.metadata_stale) === 1,
     })),

package/src/tools/review-bundles.js

@@ -27,9 +27,9 @@ export function registerReviewBundleTools(s, {
       project_id: z.string().describe("Project ID to scope the review bundle (e.g. 'test-novel')."),
       profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional compatibility chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
-      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional compatibility chapter-set filter resolved through canonical chapter identities. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),
@@ -124,9 +124,9 @@ export function registerReviewBundleTools(s, {
       profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       output_dir: z.string().describe("Directory path to write bundle artifacts into."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional compatibility chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
-      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional compatibility chapter-set filter resolved through canonical chapter identities. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),

package/src/tools/search.js

@@ -131,8 +131,10 @@ export function registerSearchTools(s, {
       if (resolvedChapterFilter.chapter) {
         conditions.push(`s.chapter_id = ?`);
         params.push(resolvedChapterFilter.chapter.chapter_id);
-      } else if (chapter_id)  { conditions.push(`s.chapter_id = ?`);         params.push(chapter_id); }
-      else if (chapter) { conditions.push(`s.chapter = ?`);           params.push(chapter); }
+      } else if (chapter != null && !project_id) {
+        conditions.push(`s.chapter = ?`);
+        params.push(chapter);
+      }
       if (pov)         { conditions.push(`s.pov = ?`);                params.push(pov); }
 
       if (joins.length)      query += " " + joins.join(" ");

package/src/tools/styleguide.js

@@ -382,7 +382,7 @@ export function registerStyleguideTools(s, {
       project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
       scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
       min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested fields (default: 0.6)."),
@@ -632,7 +632,7 @@ export function registerStyleguideTools(s, {
       project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
       scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
       min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested updates (default: 0.6)."),

package/src/tools/sync.js

@@ -355,7 +355,7 @@ export function registerSyncTools(s, {
       project_id: z.string().describe("Project ID (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
       scene_ids: z.array(z.string()).optional().describe("Optional allowlist of scene IDs to process before other filters are applied."),
       part: z.number().int().optional().describe("Optional part number filter."),
-      chapter: z.number().int().optional().describe("Optional chapter number filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       only_stale: z.boolean().optional().describe("If true, only process scenes currently marked metadata_stale."),
       dry_run: z.boolean().optional().describe("If true (default), returns preview results without writing sidecars."),