@hanna84/mcp-writing 3.21.2 → 3.21.3

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.21.3](https://github.com/hannasdev/mcp-writing/compare/v3.21.2...v3.21.3)
+
+- fix(metadata): preserve sidecar structure fields on generic writes [`#224`](https://github.com/hannasdev/mcp-writing/pull/224)
+
 #### [v3.21.2](https://github.com/hannasdev/mcp-writing/compare/v3.21.1...v3.21.2)
 
+> 28 May 2026
+
 - docs: accept architecture snapshot milestone [`#223`](https://github.com/hannasdev/mcp-writing/pull/223)
+- Release 3.21.2 [`7f0e627`](https://github.com/hannasdev/mcp-writing/commit/7f0e62741059ad487577e7295ea75564fd64d33a)
 
 #### [v3.21.1](https://github.com/hannasdev/mcp-writing/compare/v3.21.0...v3.21.1)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.21.2",
+  "version": "3.21.3",
   "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/scripts/normalize-scene-characters.mjs

@@ -2,7 +2,7 @@
 import path from "node:path";
 import { openDb } from "../core/db.js";
 import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../sync/scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../sync/sync.js";
+import { readMeta, readSourceMeta, syncAll, writeMeta } from "../sync/sync.js";
 
 function readRequiredValue(argv, index, option) {
   const value = argv[index + 1];
@@ -138,11 +138,11 @@ function runNormalization({ syncDir, projectId, write, limit }) {
       if (!normalized.changed) continue;
 
       if (write) {
-        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
-          ...meta,
+        const { sourceMeta } = readSourceMeta(scene.file_path, syncDir, { writable: true });
+        writeMeta(scene.file_path, {
+          ...sourceMeta,
           characters: normalized.after,
-        }).meta;
-        writeMeta(scene.file_path, updatedMeta, { syncDir });
+        }, { syncDir });
       }
 
       changed.push({

package/src/sync/scene-character-batch.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import matter from "gray-matter";
 import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
+import { readSourceMeta, writeMeta } from "./sync.js";
 
 function normalizeCharacterRows(rows) {
   return buildCharacterNormalizationContext(rows);
@@ -138,7 +138,7 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
     try {
       const raw = fs.readFileSync(scene.file_path, "utf8");
       const { content: prose } = matter(raw);
-      const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
+      const { sourceMeta: meta } = readSourceMeta(scene.file_path, syncDir, { writable: !dry_run });
 
       const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
       const normalized_before_characters = [...new Set(
@@ -169,10 +169,10 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
       const changed = added.length > 0 || removed.length > 0;
 
       if (!dry_run && changed) {
-        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+        const updatedMeta = {
           ...meta,
           characters: after_characters,
-        }).meta;
+        };
 
         writeMeta(scene.file_path, updatedMeta, { syncDir });
       }

package/src/sync/sync.js

@@ -494,11 +494,12 @@ export function parseFile(filePath) {
 }
 
 /**
- * Read metadata for a scene file. Priority: sidecar > frontmatter.
- * If sidecar doesn't exist but frontmatter does, auto-generates the sidecar.
- * Returns { meta, sidecarGenerated }.
+ * Read source metadata for a scene file. Priority: sidecar > frontmatter.
+ * Does not apply path-derived structural normalization or auto-generate sidecars.
+ * Generic metadata writers use this so non-structural updates do not mirror
+ * path-derived structure fields into sidecars.
  */
-export function readMeta(filePath, syncDir, { writable = false } = {}) {
+export function readSourceMeta(filePath, syncDir, { writable = false } = {}) {
   const sidecar = sidecarPath(filePath);
   const syncDirAbs = path.resolve(syncDir);
 
@@ -517,26 +518,45 @@ export function readMeta(filePath, syncDir, { writable = false } = {}) {
     }
     const raw = fs.readFileSync(sidecar, "utf8");
     const parsed = parseYaml(raw) ?? {};
-    return { ...normalizeSceneMetaForPath(syncDir, filePath, parsed), sourceMeta: parsed, sidecarGenerated: false };
+    return { meta: parsed, sourceMeta: parsed, source: "sidecar", sidecarGenerated: false };
   }
 
   // Fall back to frontmatter
   const { data: frontmatter } = parseFile(filePath);
   if (!Object.keys(frontmatter).length) {
-    return { ...normalizeSceneMetaForPath(syncDir, filePath, {}), sourceMeta: {}, sidecarGenerated: false };
+    return { meta: {}, sourceMeta: {}, source: "empty", sidecarGenerated: false };
+  }
+
+  return { meta: frontmatter, sourceMeta: frontmatter, source: "frontmatter", sidecarGenerated: false };
+}
+
+/**
+ * Read metadata for a scene file. Priority: sidecar > frontmatter.
+ * If sidecar doesn't exist but frontmatter does, auto-generates the sidecar.
+ * Returns { meta, sidecarGenerated }.
+ */
+export function readMeta(filePath, syncDir, { writable = false } = {}) {
+  const sourceRead = readSourceMeta(filePath, syncDir, { writable });
+
+  if (sourceRead.source === "sidecar" || sourceRead.source === "empty") {
+    return {
+      ...normalizeSceneMetaForPath(syncDir, filePath, sourceRead.sourceMeta),
+      sourceMeta: sourceRead.sourceMeta,
+      sidecarGenerated: false,
+    };
   }
 
-  const normalized = normalizeSceneMetaForPath(syncDir, filePath, frontmatter);
+  const normalized = normalizeSceneMetaForPath(syncDir, filePath, sourceRead.sourceMeta);
 
   // Auto-migrate: write sidecar from frontmatter (only if writable)
   if (writable) {
     try {
       writeMeta(filePath, normalized.meta, { syncDir });
-      return { ...normalized, sourceMeta: frontmatter, sidecarGenerated: true };
+      return { ...normalized, sourceMeta: sourceRead.sourceMeta, sidecarGenerated: true };
     } catch { /* empty */ }
   }
 
-  return { ...normalized, sourceMeta: frontmatter, sidecarGenerated: false };
+  return { ...normalized, sourceMeta: sourceRead.sourceMeta, sidecarGenerated: false };
 }
 
 /**

package/src/tools/metadata.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { readMeta, writeMeta, indexSceneFile, isManagedStructureProject } from "../sync/sync.js";
+import { readMeta, readSourceMeta, writeMeta, indexSceneFile, isManagedStructureProject, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
 import {
@@ -33,7 +33,7 @@ import {
   refreshProjectBackupAfterMutation,
 } from "../structure/project-backup-refresh.js";
 
-const STRUCTURAL_SCENE_METADATA_FIELDS = ["part", "chapter", "chapter_id", "timeline_position"];
+const STRUCTURAL_SCENE_METADATA_FIELDS = ["part", "chapter", "chapter_id", "chapter_title", "timeline_position"];
 
 function emptyBackupMutationResult() {
   return {
@@ -1641,7 +1641,7 @@ export function registerMetadataTools(s, {
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",
-    "Update one or more non-structural metadata fields for a scene. Writes to the .meta.yaml sidecar — never modifies prose. Structural fields (part, chapter, chapter_id, timeline_position) are rejected here; use assign_scene_to_chapter or move_scene for chapter placement and ordering. Changes are immediately reflected in the index. Only available when the sync dir is writable.",
+    "Update one or more non-structural metadata fields for a scene. Writes only supplied non-structural fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose or mirrors path-derived structure. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Changes are immediately reflected in the index. Only available when the sync dir is writable.",
     {
       scene_id:   z.string().describe("The scene_id to update (e.g. 'sc-011-sebastian')."),
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
@@ -1654,6 +1654,7 @@ export function registerMetadataTools(s, {
         part:              z.number().int().optional().describe("Rejected by update_scene_metadata. Structural placement must use explicit structure workflows."),
         chapter:           z.number().int().optional().describe("Rejected by update_scene_metadata. Use assign_scene_to_chapter or move_scene with canonical chapter_id."),
         chapter_id:        z.string().nullable().optional().describe("Rejected by update_scene_metadata. Use list_chapters, then assign_scene_to_chapter or move_scene."),
+        chapter_title:     z.string().nullable().optional().describe("Rejected by update_scene_metadata. Use rename_chapter for canonical chapter title changes."),
         timeline_position: z.number().int().optional().describe("Rejected by update_scene_metadata. Use move_scene for ordering changes."),
         story_time:        z.string().optional(),
         tags:              z.array(z.string()).optional(),
@@ -1674,22 +1675,23 @@ export function registerMetadataTools(s, {
       if (structuralFields.length > 0) {
         return errorResponse(
           "VALIDATION_ERROR",
-          "update_scene_metadata cannot change structural fields. Use assign_scene_to_chapter for chapter assignment or move_scene for chapter and timeline placement.",
+          "update_scene_metadata cannot change structural fields. Use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structural changes.",
           {
             project_id,
             scene_id,
             blocked_fields: structuralFields,
-            allowed_structure_tools: ["assign_scene_to_chapter", "move_scene"],
+            allowed_structure_tools: ["list_chapters", "assign_scene_to_chapter", "move_scene", "rename_chapter", "reorder_chapter"],
           }
         );
       }
       try {
-        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
-        const updated = { ...meta, ...fields };
+        const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const updated = { ...sourceMeta, ...fields };
         writeMeta(scene.file_path, updated, { syncDir: SYNC_DIR });
+        const normalizedUpdated = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, updated).meta;
 
         const { content: prose } = matter(fs.readFileSync(scene.file_path, "utf8"));
-        indexSceneFile(db, SYNC_DIR, scene.file_path, updated, prose, {
+        indexSceneFile(db, SYNC_DIR, scene.file_path, normalizedUpdated, prose, {
           managedStructure: isManagedStructureProject(db, project_id),
         });
         const backupResult = refreshProjectScopedBackupAfterMutation(db, {
@@ -1707,7 +1709,7 @@ export function registerMetadataTools(s, {
               scene_id,
               project_id,
               fields: Object.keys(fields).sort().reduce((acc, key) => {
-                acc[key] = meta[key] ?? null;
+                acc[key] = sourceMeta[key] ?? null;
                 return acc;
               }, {}),
             },
@@ -1717,7 +1719,7 @@ export function registerMetadataTools(s, {
               scene_id,
               project_id,
               fields: Object.keys(fields).sort().reduce((acc, key) => {
-                acc[key] = updated[key] ?? null;
+                acc[key] = normalizedUpdated[key] ?? null;
                 return acc;
               }, {}),
             },
@@ -1928,10 +1930,10 @@ export function registerMetadataTools(s, {
         return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
       }
       try {
-        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
-        const flags = meta.flags ?? [];
+        const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const flags = sourceMeta.flags ?? [];
         flags.push({ note, flagged_at: new Date().toISOString() });
-        writeMeta(scene.file_path, { ...meta, flags }, { syncDir: SYNC_DIR });
+        writeMeta(scene.file_path, { ...sourceMeta, flags }, { syncDir: SYNC_DIR });
         return { content: [{ type: "text", text: `Flagged scene '${scene_id}': ${note}` }] };
       } catch (err) {
         if (err?.name === "CoreValidationError") {

package/src/tools/reference-link-persistence.js

@@ -1,4 +1,4 @@
-import { readMeta, writeMeta, normalizeReferenceLinkList } from "../sync/sync.js";
+import { readSourceMeta, writeMeta, normalizeReferenceLinkList } from "../sync/sync.js";
 
 let savepointCounter = 0;
 
@@ -13,7 +13,7 @@ export function upsertSerializedReferenceLinks(existing, targetDocId, relation,
 }
 
 export function persistSceneReferenceLink({ scenePath, syncDir, targetDocId, relation }) {
-  const { meta } = readMeta(scenePath, syncDir, { writable: true });
+  const { sourceMeta: meta } = readSourceMeta(scenePath, syncDir, { writable: true });
   const existingExplicit = [
     ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
     ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),

package/src/tools/sync.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { syncAll, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, isManagedStructureProject } from "../sync/sync.js";
+import { syncAll, writeMeta, readSourceMeta, indexSceneFile, normalizeSceneMetaForPath, isManagedStructureProject } from "../sync/sync.js";
 import { importScrivenerSync, validateProjectId } from "../sync/importer.js";
 import { runStructureDiagnostics } from "../structure/structure-diagnostics.js";
 import {
@@ -951,20 +951,21 @@ export function registerSyncTools(s, {
       try {
         const raw = fs.readFileSync(scene.file_path, "utf8");
         const { content: prose } = matter(raw);
-        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const { sourceMeta: meta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
 
         const inferredLogline = deriveLoglineFromProse(prose);
         const inferredCharacters = inferCharacterIdsFromProse(db, prose, scene.project_id);
 
-        const updatedMeta = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, {
+        const sourceUpdatedMeta = {
           ...meta,
           ...(inferredLogline ? { logline: inferredLogline } : {}),
           ...((inferredCharacters.length > 0 || (meta.characters?.length ?? 0) > 0)
             ? { characters: inferredCharacters.length > 0 ? inferredCharacters : meta.characters }
             : {}),
-        }).meta;
+        };
+        const updatedMeta = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, sourceUpdatedMeta).meta;
 
-        writeMeta(scene.file_path, updatedMeta, { syncDir: SYNC_DIR });
+        writeMeta(scene.file_path, sourceUpdatedMeta, { syncDir: SYNC_DIR });
         indexSceneFile(db, SYNC_DIR, scene.file_path, updatedMeta, prose, {
           managedStructure: isManagedStructureProject(db, scene.project_id),
         });