@hanna84/mcp-writing 3.13.1 → 3.14.1

package/CHANGELOG.md

@@ -4,9 +4,23 @@ 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.14.1](https://github.com/hannasdev/mcp-writing/compare/v3.14.0...v3.14.1)
+
+- ci: optimize validation workflow [`#208`](https://github.com/hannasdev/mcp-writing/pull/208)
+
+#### [v3.14.0](https://github.com/hannasdev/mcp-writing/compare/v3.13.1...v3.14.0)
+
+> 19 May 2026
+
+- feat: add deterministic structure exports [`#207`](https://github.com/hannasdev/mcp-writing/pull/207)
+- Release 3.14.0 [`94fc46b`](https://github.com/hannasdev/mcp-writing/commit/94fc46bc98996688479a2bee9fc73415f69c3a86)
+
 #### [v3.13.1](https://github.com/hannasdev/mcp-writing/compare/v3.13.0...v3.13.1)
 
+> 19 May 2026
+
 - docs(product): mark M7 complete [`#206`](https://github.com/hannasdev/mcp-writing/pull/206)
+- Release 3.13.1 [`6f984b9`](https://github.com/hannasdev/mcp-writing/commit/6f984b9d53ad8187749b4038338e380704e398c6)
 
 #### [v3.13.0](https://github.com/hannasdev/mcp-writing/compare/v3.12.0...v3.13.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.13.1",
+  "version": "3.14.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",
@@ -74,6 +74,9 @@
     "lint": "eslint *.js src/index.js src/core src/review-bundles src/runtime src/setup src/scripts src/structure src/styleguide src/sync src/tools src/workflows src/world",
     "guard:legacy-root-imports": "node src/scripts/check-legacy-root-imports.mjs",
     "docs": "node src/scripts/generate-tool-docs.mjs",
+    "check:docs": "npm run docs && git diff --exit-code -- docs/agents/tools.md",
+    "check:static": "npm run lint && npm run guard:legacy-root-imports && npm run check:docs",
+    "check:pr": "npm run check:static && npm test",
     "lint:metadata": "node src/scripts/lint-metadata.mjs",
     "sync:server-json-version": "node src/scripts/sync-server-json-version.mjs",
     "test:unit": "node --experimental-sqlite --test src/test/unit/*.test.mjs",

package/src/structure/structure-export.js

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const STRUCTURE_EXPORT_SCHEMA_VERSION = 1;
+
+function normalizePathForExport(syncDir, filePath) {
+  if (!filePath) return null;
+  const syncRoot = path.resolve(syncDir);
+  const resolvedPath = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(syncRoot, filePath);
+  const normalized = path.relative(syncRoot, resolvedPath);
+  if (normalized.startsWith("..") || path.isAbsolute(normalized)) {
+    throw new Error(`Cannot export path outside sync_dir: ${filePath}`);
+  }
+  return normalized.split(path.sep).join("/");
+}
+
+function stableStringify(value, indent = 2) {
+  const seen = new WeakSet();
+  function normalize(input) {
+    if (input === null || typeof input !== "object") return input;
+    if (seen.has(input)) {
+      throw new TypeError("Cannot stable-stringify circular structure.");
+    }
+    seen.add(input);
+    if (Array.isArray(input)) {
+      const array = input.map(normalize);
+      seen.delete(input);
+      return array;
+    }
+    const object = {};
+    for (const key of Object.keys(input).sort()) {
+      object[key] = normalize(input[key]);
+    }
+    seen.delete(input);
+    return object;
+  }
+
+  return JSON.stringify(normalize(value), null, indent);
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function defaultStructureExportFileName(projectId) {
+  const slug = String(projectId ?? "project")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "project";
+  return `${slug}.structure.json`;
+}
+
+export function buildStructureExport(db, { projectId, syncDir }) {
+  const project = db.prepare(`
+    SELECT project_id, universe_id, name
+    FROM projects
+    WHERE project_id = ?
+  `).get(projectId);
+  if (!project) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Project '${projectId}' not found.`,
+        details: { project_id: projectId },
+      },
+    };
+  }
+
+  const chapters = db.prepare(`
+    SELECT chapter_id, title, sort_index, logline, source_path, source_checksum, metadata_stale, updated_at
+    FROM chapters
+    WHERE project_id = ?
+    ORDER BY sort_index, chapter_id
+  `).all(projectId).map(row => ({
+    chapter_id: row.chapter_id,
+    title: row.title,
+    sort_index: row.sort_index,
+    logline: row.logline ?? null,
+    source_path: normalizePathForExport(syncDir, row.source_path),
+    source_checksum: row.source_checksum ?? null,
+    metadata_stale: row.metadata_stale,
+    updated_at: row.updated_at,
+  }));
+
+  const scenes = db.prepare(`
+    SELECT
+      s.scene_id,
+      s.title,
+      s.chapter_id,
+      s.scene_role,
+      s.part,
+      s.chapter,
+      s.chapter_title,
+      s.timeline_position,
+      s.file_path,
+      s.prose_checksum,
+      s.metadata_stale,
+      s.updated_at
+    FROM scenes s
+    LEFT JOIN chapters c
+      ON c.project_id = s.project_id
+     AND c.chapter_id = s.chapter_id
+    WHERE s.project_id = ?
+    ORDER BY
+      CASE WHEN c.sort_index IS NULL THEN 2147483647 ELSE c.sort_index END,
+      CASE WHEN s.timeline_position IS NULL THEN 1 ELSE 0 END,
+      s.timeline_position,
+      s.scene_id
+  `).all(projectId).map(row => ({
+    scene_id: row.scene_id,
+    title: row.title ?? null,
+    chapter_id: row.chapter_id ?? null,
+    scene_role: row.scene_role ?? null,
+    part: row.part ?? null,
+    compatibility_chapter: row.chapter ?? null,
+    compatibility_chapter_title: row.chapter_title ?? null,
+    timeline_position: row.timeline_position ?? null,
+    file_path: normalizePathForExport(syncDir, row.file_path),
+    prose_checksum: row.prose_checksum ?? null,
+    metadata_stale: row.metadata_stale,
+    updated_at: row.updated_at,
+  }));
+
+  const epigraphs = db.prepare(`
+    SELECT
+      e.epigraph_id,
+      e.chapter_id,
+      e.file_path,
+      e.prose_checksum,
+      e.metadata_stale,
+      e.updated_at
+    FROM epigraphs e
+    LEFT JOIN chapters c
+      ON c.project_id = e.project_id
+     AND c.chapter_id = e.chapter_id
+    WHERE e.project_id = ?
+    ORDER BY
+      CASE WHEN c.sort_index IS NULL THEN 2147483647 ELSE c.sort_index END,
+      e.epigraph_id
+  `).all(projectId).map(row => ({
+    epigraph_id: row.epigraph_id,
+    chapter_id: row.chapter_id,
+    file_path: normalizePathForExport(syncDir, row.file_path),
+    prose_checksum: row.prose_checksum ?? null,
+    metadata_stale: row.metadata_stale,
+    updated_at: row.updated_at,
+  }));
+
+  const baseSnapshot = {
+    export: {
+      schema_version: STRUCTURE_EXPORT_SCHEMA_VERSION,
+      canonical_source: "sqlite",
+      project_id: project.project_id,
+      generated_transparency: true,
+      mutation_surface: false,
+    },
+    project: {
+      project_id: project.project_id,
+      universe_id: project.universe_id ?? null,
+      name: project.name,
+    },
+    summary: {
+      chapter_count: chapters.length,
+      scene_count: scenes.length,
+      epigraph_count: epigraphs.length,
+    },
+    chapters,
+    scenes,
+    epigraphs,
+  };
+
+  const structureChecksum = sha256(stableStringify(baseSnapshot, 0));
+  return {
+    ok: true,
+    snapshot: {
+      ...baseSnapshot,
+      export: {
+        ...baseSnapshot.export,
+        structure_checksum: structureChecksum,
+      },
+    },
+  };
+}
+
+export function renderStructureExport(snapshot) {
+  return `${stableStringify(snapshot, 2)}\n`;
+}
+
+export function writeStructureExportFile(snapshot, { outputDir, fileName }) {
+  const normalizedOutputDir = path.resolve(outputDir);
+  const targetPath = path.resolve(normalizedOutputDir, fileName);
+  const relative = path.relative(normalizedOutputDir, targetPath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Output file '${fileName}' resolves outside output_dir.`);
+  }
+
+  if (!fs.existsSync(normalizedOutputDir)) {
+    fs.mkdirSync(normalizedOutputDir, { recursive: true });
+  } else {
+    const outputDirStat = fs.lstatSync(normalizedOutputDir);
+    if (!outputDirStat.isDirectory()) {
+      throw new Error(`output_dir exists but is not a directory: ${normalizedOutputDir}`);
+    }
+  }
+  fs.accessSync(normalizedOutputDir, fs.constants.W_OK);
+
+  const stat = (() => {
+    try {
+      return fs.lstatSync(targetPath);
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    }
+  })();
+  if (stat?.isSymbolicLink()) {
+    throw new Error(`Refusing to write: target path is a symlink: ${targetPath}`);
+  }
+  if (stat && !stat.isFile()) {
+    throw new Error(`Refusing to write: target path exists but is not a regular file: ${targetPath}`);
+  }
+
+  fs.writeFileSync(targetPath, renderStructureExport(snapshot), "utf8");
+  return targetPath;
+}

package/src/tools/sync.js

@@ -5,6 +5,11 @@ import matter from "gray-matter";
 import { syncAll, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { importScrivenerSync, validateProjectId } from "../sync/importer.js";
 import { runStructureDiagnostics } from "../structure/structure-diagnostics.js";
+import {
+  buildStructureExport,
+  defaultStructureExportFileName,
+  writeStructureExportFile,
+} from "../structure/structure-export.js";
 
 export function registerSyncTools(s, {
   db,
@@ -23,6 +28,7 @@ export function registerSyncTools(s, {
   resolveBatchTargetScenes,
   maxScenesNextStep,
   isPathInsideSyncDir,
+  resolveOutputDirWithinSync,
   deriveLoglineFromProse,
   inferCharacterIdsFromProse,
 }) {
@@ -67,6 +73,81 @@ export function registerSyncTools(s, {
     }
   );
 
+  s.tool(
+    "export_structure_snapshot",
+    "Generate a deterministic JSON structure export from SQLite canonical state for Git review and future explicit recovery workflows. The export is generated transparency only: editing it does not change canonical state.",
+    {
+      project_id: z.string().describe("Project ID to export (e.g. 'test-novel')."),
+      output_dir: z.string().optional().describe("Directory under WRITING_SYNC_DIR where the export JSON should be written. Defaults to structure-exports."),
+    },
+    async ({ project_id, output_dir }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot export structure snapshot: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      try {
+        const requestedOutputDir = output_dir
+          ? (path.isAbsolute(output_dir) ? output_dir : path.join(SYNC_DIR_ABS, output_dir))
+          : path.join(SYNC_DIR_ABS, "structure-exports");
+        const { resolvedOutputDir, relativeToSyncDir } = resolveOutputDirWithinSync(requestedOutputDir);
+        const outputDirSegments = relativeToSyncDir
+          .split(path.sep)
+          .filter(Boolean)
+          .map(segment => segment.toLowerCase());
+        if (outputDirSegments.includes("scenes")) {
+          return errorResponse(
+            "INVALID_OUTPUT_DIR",
+            "output_dir cannot be inside a scenes directory. Choose a dedicated generated export folder under WRITING_SYNC_DIR.",
+            { output_dir: resolvedOutputDir }
+          );
+        }
+
+        const built = buildStructureExport(db, {
+          projectId: project_id,
+          syncDir: SYNC_DIR_ABS,
+        });
+        if (!built.ok) {
+          return errorResponse(built.error.code, built.error.message, built.error.details);
+        }
+
+        const fileName = defaultStructureExportFileName(project_id);
+        const outputPath = writeStructureExportFile(built.snapshot, {
+          outputDir: resolvedOutputDir,
+          fileName,
+        });
+
+        return jsonResponse({
+          ok: true,
+          action: "exported",
+          project_id,
+          output_path: outputPath,
+          relative_output_path: path.join(relativeToSyncDir, fileName).split(path.sep).join("/"),
+          export: built.snapshot.export,
+          summary: built.snapshot.summary,
+          next_step: "Review or commit the generated structure export. Do not edit it as a mutation surface; use explicit structure tools for canonical changes.",
+        });
+      } catch (error) {
+        if (
+          error &&
+          typeof error === "object" &&
+          error.name === "CoreValidationError" &&
+          typeof error.code === "string"
+        ) {
+          return errorResponse(error.code, error.message ?? "Request failed.", error.details);
+        }
+        return errorResponse(
+          "EXPORT_STRUCTURE_FAILED",
+          error instanceof Error ? error.message : "Failed to export structure snapshot."
+        );
+      }
+    }
+  );
+
   s.tool(
     "import_scrivener_sync",
     "[STABLE] Import Scrivener External Folder Sync Draft files into this server's WRITING_SYNC_DIR by generating scene sidecars and reconciling by Scrivener binder ID. This is the recommended default path for first-time setup before sync().",

package/src/workflows/workflow-catalogue.js

@@ -89,6 +89,7 @@ export const WORKFLOW_CATALOGUE = [
       { tool: "move_scene", note: "Use when a scene should move to another canonical chapter and/or unused timeline_position; this does not move the scene source file." },
       { 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." },
+      { tool: "export_structure_snapshot", note: "Generate a deterministic SQLite-derived structure export for Git review after canonical structure changes; editing the export does not mutate structure." },
     ],
   },
   {