@hanna84/mcp-writing 3.8.2 → 3.9.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.9.0](https://github.com/hannasdev/mcp-writing/compare/v3.8.2...v3.9.0)
+
+- feat(chapters): align metadata tooling with chapter ids [`#196`](https://github.com/hannasdev/mcp-writing/pull/196)
+
 #### [v3.8.2](https://github.com/hannasdev/mcp-writing/compare/v3.8.1...v3.8.2)
 
+> 16 May 2026
+
 - docs(skills): align release-log path guidance [`#195`](https://github.com/hannasdev/mcp-writing/pull/195)
+- Release 3.8.2 [`b5284f1`](https://github.com/hannasdev/mcp-writing/commit/b5284f144702c3532f330cfb1dbdf85f83289131)
 
 #### [v3.8.1](https://github.com/hannasdev/mcp-writing/compare/v3.8.0...v3.8.1)
 

package/package.json

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

@@ -0,0 +1,61 @@
+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;
+
+  const canonicalChapter = 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;
+
+  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
+    FROM scenes
+    WHERE project_id = ? AND chapter = ? AND chapter_id IS NOT NULL
+    GROUP BY chapter_id, project_id, chapter_title, chapter
+    ORDER BY chapter_id
+    LIMIT 1
+  `).get(projectId, chapterNumber);
+}
+
+export function resolveValidatedChapterFilter(db, { projectId, chapterNumber, chapterId }) {
+  if (!projectId) return { chapter: null };
+  if (!chapterId && chapterNumber == null) return { chapter: null };
+
+  const resolvedById = chapterId
+    ? resolveChapterByCompatibilityKey(db, { projectId, chapterId })
+    : null;
+  const resolvedByNumber = chapterNumber != null
+    ? resolveChapterByCompatibilityKey(db, { projectId, chapterNumber })
+    : null;
+
+  if (chapterId && chapterNumber != null) {
+    if (!resolvedById || !resolvedByNumber) {
+      return {
+        error: {
+          code: "NOT_FOUND",
+          message: "Chapter not found for the provided project and identifier.",
+        },
+      };
+    }
+    if (resolvedById.chapter_id !== resolvedByNumber.chapter_id) {
+      return {
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
+        },
+      };
+    }
+    return { chapter: resolvedById };
+  }
+
+  return { chapter: resolvedById ?? resolvedByNumber ?? null };
+}

package/src/core/helpers.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import yaml from "js-yaml";
 import { sidecarPath, syncAll } from "../sync/sync.js";
+import { resolveValidatedChapterFilter } from "./chapter-resolution.js";
 import {
   slugifyEntityName,
   renderCharacterSheetTemplate,
@@ -126,6 +127,22 @@ export function resolveBatchTargetScenes(dbHandle, {
 
   const conditions = ["project_id = ?"];
   const params = [projectId];
+  const resolvedChapterFilter = (chapter !== undefined || chapterId !== undefined)
+    ? resolveValidatedChapterFilter(dbHandle, { projectId, chapterNumber: chapter, chapterId })
+    : { chapter: null };
+
+  if (resolvedChapterFilter.error) {
+    return {
+      ok: false,
+      code: resolvedChapterFilter.error.code,
+      message: resolvedChapterFilter.error.message,
+      details: {
+        project_id: projectId,
+        chapter: chapter ?? null,
+        chapter_id: chapterId ?? null,
+      },
+    };
+  }
 
   if (sceneIds?.length) {
     const placeholders = sceneIds.map(() => "?").join(",");
@@ -136,13 +153,15 @@ export function resolveBatchTargetScenes(dbHandle, {
     conditions.push("part = ?");
     params.push(part);
   }
-  if (chapter !== undefined) {
-    conditions.push("chapter = ?");
-    params.push(chapter);
-  }
-  if (chapterId !== undefined) {
+  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/sync/metadata-lint.js

@@ -16,7 +16,7 @@ import yaml from "js-yaml";
 
 const { load: parseYaml } = yaml;
 
-const metadataKindSchema = z.enum(["scene", "character", "place"]);
+const metadataKindSchema = z.enum(["scene", "character", "place", "epigraph"]);
 
 const threadLinkSchema = z.object({
   thread_id: z.string().min(1),
@@ -71,9 +71,22 @@ const placeSchema = z.object({
   tags: z.array(z.string().min(1)).optional(),
 });
 
+const epigraphSchema = z.object({
+  kind: z.literal("epigraph").optional(),
+  type: z.literal("epigraph").optional(),
+  epigraph_id: z.string().min(1).optional(),
+  scene_id: z.string().min(1).optional(),
+  chapter: z.number().int().positive().optional(),
+  chapter_id: z.string().min(1).optional(),
+  chapter_title: z.string().min(1).optional(),
+  characters: z.array(z.string().min(1)).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+});
+
 const sceneAllowedKeys = new Set(Object.keys(sceneSchema.shape));
 const characterAllowedKeys = new Set(Object.keys(characterSchema.shape));
 const placeAllowedKeys = new Set(Object.keys(placeSchema.shape));
+const epigraphAllowedKeys = new Set(Object.keys(epigraphSchema.shape));
 const sceneLegacyKeys = new Set(["synopsis", "save_the_cat", "change"]);
 
 function uniqueItems(items = []) {
@@ -82,6 +95,7 @@ function uniqueItems(items = []) {
 
 export function detectMetadataKind(meta) {
   if (meta && typeof meta === "object") {
+    if (meta.kind === "epigraph" || meta.type === "epigraph" || typeof meta.epigraph_id === "string") return "epigraph";
     if (typeof meta.character_id === "string") return "character";
     if (typeof meta.place_id === "string") return "place";
     return "scene";
@@ -92,18 +106,22 @@ export function detectMetadataKind(meta) {
 function allowedKeysFor(kind) {
   if (kind === "character") return characterAllowedKeys;
   if (kind === "place") return placeAllowedKeys;
+  if (kind === "epigraph") return epigraphAllowedKeys;
   return sceneAllowedKeys;
 }
 
 function schemaFor(kind) {
   if (kind === "character") return characterSchema;
   if (kind === "place") return placeSchema;
+  if (kind === "epigraph") return epigraphSchema;
   return sceneSchema;
 }
 
 function validateUniqueArrays(meta, kind, issues) {
   const fields = kind === "scene"
     ? ["characters", "places", "tags", "scene_functions", "versions"]
+    : kind === "epigraph"
+      ? ["characters", "tags"]
     : kind === "character"
       ? ["traits", "tags"]
       : ["associated_characters", "tags"];
@@ -119,7 +137,7 @@ function validateUniqueArrays(meta, kind, issues) {
   }
 }
 
-function validateSceneCharacterReferenceStyle(meta, issues) {
+function validateCanonicalCharacterReferenceStyle(meta, issues, { entityLabel }) {
   if (!Array.isArray(meta.characters) || meta.characters.length === 0) return;
 
   if (!meta.characters.every(value => typeof value === "string")) return;
@@ -132,7 +150,7 @@ function validateSceneCharacterReferenceStyle(meta, issues) {
   issues.push({
     level: "warning",
     code: "MIXED_CHARACTER_REFERENCE_STYLE",
-    message: "Scene characters contain mixed canonical and non-canonical references. Prefer canonical character_id values only.",
+    message: `${entityLabel} characters contain mixed canonical and non-canonical references. Prefer canonical character_id values only.`,
   });
 }
 
@@ -186,7 +204,11 @@ export function validateMetadataObject(meta, { sourcePath, kindHint } = {}) {
   validateUniqueArrays(meta, kind, issues);
 
   if (kind === "scene") {
-    validateSceneCharacterReferenceStyle(meta, issues);
+    validateCanonicalCharacterReferenceStyle(meta, issues, { entityLabel: "Scene" });
+  }
+
+  if (kind === "epigraph") {
+    validateCanonicalCharacterReferenceStyle(meta, issues, { entityLabel: "Epigraph" });
   }
 
   if (kind === "scene" && sourcePath) {

package/src/tools/metadata.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import matter from "gray-matter";
 import { readMeta, writeMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
+import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
 import {
   persistSceneReferenceLink,
   upsertExplicitReferenceLinkRow,
@@ -523,7 +524,8 @@ export function registerMetadataTools(s, {
         save_the_cat_beat: z.string().optional(),
         pov:               z.string().optional(),
         part:              z.number().int().optional(),
-        chapter:           z.number().int().optional(),
+        chapter:           z.number().int().optional().describe("Compatibility chapter number. When it resolves to a canonical chapter, update_scene_metadata also persists the matching chapter_id."),
+        chapter_id:        z.string().nullable().optional().describe("Canonical chapter identifier. Use list_chapters to find valid values. Pass null to clear an explicit chapter link on an unchaptered scene."),
         timeline_position: z.number().int().optional(),
         story_time:        z.string().optional(),
         tags:              z.array(z.string()).optional(),
@@ -542,7 +544,62 @@ export function registerMetadataTools(s, {
       }
       try {
         const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
-        const updated = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, { ...meta, ...fields }).meta;
+        const nextFields = { ...fields };
+
+        if (fields.chapter_id === null && fields.chapter !== undefined) {
+          return errorResponse(
+            "VALIDATION_ERROR",
+            "chapter_id cannot be null when chapter is also provided.",
+            {
+              project_id,
+              chapter_id: null,
+              chapter: fields.chapter,
+            }
+          );
+        }
+
+        if (fields.chapter_id === null) {
+          nextFields.chapter = null;
+          nextFields.chapter_title = null;
+        } else if (fields.chapter_id !== undefined || fields.chapter !== undefined) {
+          const resolvedChapterFilter = resolveValidatedChapterFilter(db, {
+            projectId: project_id,
+            chapterNumber: fields.chapter,
+            chapterId: fields.chapter_id,
+          });
+
+          if (resolvedChapterFilter.error) {
+            return errorResponse(
+              resolvedChapterFilter.error.code,
+              resolvedChapterFilter.error.message,
+              {
+                project_id,
+                chapter_id: fields.chapter_id ?? null,
+                chapter: fields.chapter ?? null,
+              }
+            );
+          }
+
+          const resolvedChapter = resolvedChapterFilter.chapter;
+
+          if (!resolvedChapter) {
+            return errorResponse(
+              "NOT_FOUND",
+              "Chapter not found for the provided project and identifier.",
+              {
+                project_id,
+                chapter_id: fields.chapter_id ?? null,
+                chapter: fields.chapter ?? null,
+              }
+            );
+          }
+
+          nextFields.chapter_id = resolvedChapter.chapter_id;
+          nextFields.chapter = resolvedChapter.sort_index;
+          nextFields.chapter_title = resolvedChapter.title ?? null;
+        }
+
+        const updated = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, { ...meta, ...nextFields }).meta;
         writeMeta(scene.file_path, updated);
 
         const { content: prose } = matter(fs.readFileSync(scene.file_path, "utf8"));

package/src/tools/search.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import matter from "gray-matter";
 import { readMeta } from "../sync/sync.js";
 import { persistSceneReferenceLink, upsertExplicitReferenceLinkRow } from "./reference-link-persistence.js";
+import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
 
 function accumulateSuggestionScore(scoreMap, rows, sourceLabel) {
   for (const row of rows) {
@@ -39,67 +40,6 @@ function readSceneEntityIdsFromMetadata({ scenePath, syncDir }) {
   };
 }
 
-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;
-  const canonicalChapter = 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;
-
-  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
-    FROM scenes
-    WHERE project_id = ? AND chapter = ? AND chapter_id IS NOT NULL
-    GROUP BY chapter_id, project_id, chapter_title, chapter
-    ORDER BY chapter_id
-    LIMIT 1
-  `).get(projectId, chapterNumber);
-}
-
-function resolveValidatedChapterFilter(db, { projectId, chapterNumber, chapterId }) {
-  if (!projectId) return { chapter: null };
-  if (!chapterId && chapterNumber == null) return { chapter: null };
-
-  const resolvedById = chapterId
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterId })
-    : null;
-  const resolvedByNumber = chapterNumber != null
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterNumber })
-    : null;
-
-  if (chapterId && chapterNumber != null) {
-    if (!resolvedById || !resolvedByNumber) {
-      return {
-        error: {
-          code: "NOT_FOUND",
-          message: "Chapter not found for the provided project and identifier.",
-        },
-      };
-    }
-    if (resolvedById.chapter_id !== resolvedByNumber.chapter_id) {
-      return {
-        error: {
-          code: "VALIDATION_ERROR",
-          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
-        },
-      };
-    }
-    return { chapter: resolvedById };
-  }
-
-  return { chapter: resolvedById ?? resolvedByNumber ?? null };
-}
-
 function selectApplyCandidates(enrichedCandidates, selectedDocIds, maxApply) {
   const selectedSet = selectedDocIds ? new Set(selectedDocIds) : null;
   const chosenByDocId = new Map();