@hanna84/mcp-writing 3.10.0 → 3.11.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.11.0](https://github.com/hannasdev/mcp-writing/compare/v3.10.0...v3.11.0)
+
+- feat(structure): add explicit scene chapter assignment [`#203`](https://github.com/hannasdev/mcp-writing/pull/203)
+
 #### [v3.10.0](https://github.com/hannasdev/mcp-writing/compare/v3.9.5...v3.10.0)
 
+> 18 May 2026
+
 - feat: add read-only structure diagnostics [`#202`](https://github.com/hannasdev/mcp-writing/pull/202)
+- Release 3.10.0 [`d9b1dfb`](https://github.com/hannasdev/mcp-writing/commit/d9b1dfbce6e0391d035725f3c0671253f53ad455)
 
 #### [v3.9.5](https://github.com/hannasdev/mcp-writing/compare/v3.9.4...v3.9.5)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.10.0",
+  "version": "3.11.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/structure/scene-chapter-assignment.js

@@ -0,0 +1,77 @@
+import { applySceneStructurePatch } from "./structure-inference.js";
+
+export function buildSceneChapterAssignmentPlan(syncDir, filePath, meta = {}, { chapter } = {}) {
+  if (chapter === undefined) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a canonical chapter or null to clear the scene chapter link.",
+      },
+    };
+  }
+
+  const currentStructure = applySceneStructurePatch(syncDir, filePath, meta);
+  const pathChapter = currentStructure.chapterStructure.chapter ?? null;
+  const pathChapterNumber = currentStructure.derived.chapter ?? null;
+
+  if (chapter === null) {
+    if (pathChapter || pathChapterNumber !== null) {
+      return {
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "chapter_id cannot be cleared for a scene whose file path implies a chapter.",
+          details: {
+            path_chapter: pathChapter?.chapter_id ?? pathChapterNumber,
+          },
+        },
+      };
+    }
+
+    return {
+      ok: true,
+      meta: applySceneStructurePatch(syncDir, filePath, meta, { chapter: null }).meta,
+      assignedChapter: null,
+      previousChapterId: meta.chapter_id ?? null,
+    };
+  }
+
+  if (pathChapter && pathChapter.chapter_id !== chapter.chapter_id) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Cannot assign a scene to a different chapter while its file path implies another canonical chapter.",
+        details: {
+          requested_chapter_id: chapter.chapter_id,
+          requested_chapter: chapter.sort_index,
+          path_chapter: pathChapter.chapter_id,
+          path_chapter_number: pathChapterNumber,
+        },
+      },
+    };
+  }
+
+  if (!pathChapter && pathChapterNumber !== null && pathChapterNumber !== chapter.sort_index) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Cannot assign a scene to a different chapter while its file path implies another compatibility chapter.",
+        details: {
+          requested_chapter_id: chapter.chapter_id,
+          requested_chapter: chapter.sort_index,
+          path_chapter: pathChapterNumber,
+        },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    meta: applySceneStructurePatch(syncDir, filePath, meta, { chapter }).meta,
+    assignedChapter: chapter,
+    previousChapterId: meta.chapter_id ?? null,
+  };
+}

package/src/tools/metadata.js

@@ -4,6 +4,7 @@ import matter from "gray-matter";
 import { readMeta, writeMeta, indexSceneFile, applySceneStructurePatch } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
+import { buildSceneChapterAssignmentPlan } from "../structure/scene-chapter-assignment.js";
 import {
   persistSceneReferenceLink,
   upsertExplicitReferenceLinkRow,
@@ -510,6 +511,92 @@ export function registerMetadataTools(s, {
     }
   );
 
+  // ---- assign_scene_to_chapter --------------------------------------------
+  s.tool(
+    "assign_scene_to_chapter",
+    "Assign a scene to a canonical chapter through the explicit structure workflow. Writes chapter_id plus compatibility chapter/chapter_title fields to the scene sidecar and refreshes the index. Pass chapter_id=null to clear an explicit chapter link on an unchaptered scene. Use list_chapters first to choose a valid canonical chapter_id.",
+    {
+      scene_id: z.string().describe("The scene_id to assign (e.g. 'sc-011-sebastian')."),
+      project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
+      chapter_id: z.string().nullable().describe("Canonical chapter identifier. Use list_chapters to find valid values. Pass null to clear an explicit chapter link on an unchaptered scene."),
+    },
+    async ({ scene_id, project_id, chapter_id }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot assign scene to chapter: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const scene = db.prepare(`
+        SELECT scene_id, project_id, chapter_id, file_path
+        FROM scenes
+        WHERE scene_id = ? AND project_id = ?
+      `).get(scene_id, project_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+      }
+
+      let chapter = null;
+      if (chapter_id !== null) {
+        const resolvedChapterFilter = resolveValidatedChapterFilter(db, {
+          projectId: project_id,
+          chapterId: chapter_id,
+        });
+
+        if (resolvedChapterFilter.error) {
+          return errorResponse(
+            resolvedChapterFilter.error.code,
+            resolvedChapterFilter.error.message,
+            { project_id, chapter_id }
+          );
+        }
+
+        chapter = resolvedChapterFilter.chapter;
+        if (!chapter) {
+          return errorResponse("NOT_FOUND", "Chapter not found for the provided project and identifier.", {
+            project_id,
+            chapter_id,
+          });
+        }
+      }
+
+      try {
+        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const plan = buildSceneChapterAssignmentPlan(SYNC_DIR, scene.file_path, meta, { chapter });
+        if (!plan.ok) {
+          return errorResponse(plan.error.code, plan.error.message, {
+            project_id,
+            scene_id,
+            chapter_id,
+            ...(plan.error.details ?? {}),
+          });
+        }
+
+        writeMeta(scene.file_path, plan.meta);
+
+        const { content: prose } = matter(fs.readFileSync(scene.file_path, "utf8"));
+        indexSceneFile(db, SYNC_DIR, scene.file_path, plan.meta, prose);
+
+        return jsonResponse({
+          ok: true,
+          action: chapter === null ? "cleared" : "assigned",
+          scene_id,
+          project_id,
+          previous_chapter_id: plan.previousChapterId ?? scene.chapter_id ?? null,
+          chapter: plan.assignedChapter,
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path — the file may have moved. Run sync() to refresh.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to assign scene '${scene_id}' to chapter: ${err.message}`);
+      }
+    }
+  );
+
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",

package/src/workflows/workflow-catalogue.js

@@ -75,6 +75,17 @@ export const WORKFLOW_CATALOGUE = [
       { tool: "suggest_scene_references", note: "Use when low parity is specifically about missing scene-to-reference relationships." },
     ],
   },
+  {
+    id: "structure_assignment",
+    label: "Assign a scene to a chapter",
+    use_when: "Use when the user wants to move an unchaptered scene into a canonical chapter, repair an explicit scene chapter link, or clear a scene's explicit chapter assignment.",
+    steps: [
+      { tool: "find_scenes", note: "Identify the target scene and confirm project_id if the user did not provide both." },
+      { tool: "list_chapters", note: "Choose the canonical chapter_id for the target project before assigning." },
+      { tool: "assign_scene_to_chapter", note: "Use this named structure workflow for chapter assignment or clearing instead of editing chapter fields through generic metadata updates." },
+      { tool: "diagnose_structure", note: "Run when the assignment is part of a drift repair workflow or when folder-derived structure may disagree with the requested link." },
+    ],
+  },
   {
     id: "review_preparation",
     label: "Prepare material for human review",