@hanna84/mcp-writing 3.27.0 → 3.28.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.28.0](https://github.com/hannasdev/mcp-writing/compare/v3.27.0...v3.28.0)
+
+- feat: make restore plans easier to scan [`#238`](https://github.com/hannasdev/mcp-writing/pull/238)
+
 #### [v3.27.0](https://github.com/hannasdev/mcp-writing/compare/v3.26.0...v3.27.0)
 
+> 6 June 2026
+
 - feat(metadata): accept forgiving relationship evidence inputs [`#237`](https://github.com/hannasdev/mcp-writing/pull/237)
+- Release 3.27.0 [`ef5423b`](https://github.com/hannasdev/mcp-writing/commit/ef5423b044274b75bf60327772c9a944b94123c1)
 
 #### [v3.26.0](https://github.com/hannasdev/mcp-writing/compare/v3.25.0...v3.26.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.27.0",
+  "version": "3.28.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/project-backup-restore.js

@@ -873,6 +873,88 @@ function buildRestorePlan(currentSnapshot, backupSnapshot, { projectId }) {
   };
 }
 
+function buildPlanSummary(plan) {
+  return {
+    totals: { ...plan.totals },
+    by_domain: plan.by_domain,
+    destructive_change_count: plan.destructive_change_count,
+    cross_scope_change_count: plan.cross_scope_change_count,
+    has_destructive_changes: plan.destructive_change_count > 0,
+    has_cross_scope_changes: plan.cross_scope_change_count > 0,
+    requires_destructive_confirmation: plan.destructive_change_count > 0,
+    requires_cross_scope_confirmation: plan.cross_scope_change_count > 0,
+  };
+}
+
+function buildPlanDetailPolicy({ includeUnchanged, omittedUnchangedChangeCount }) {
+  return {
+    include_unchanged: includeUnchanged,
+    unchanged_rows_included: includeUnchanged,
+    omitted_unchanged_change_count: omittedUnchangedChangeCount,
+    full_plan_available: true,
+    full_plan_next_step: includeUnchanged
+      ? "This response includes unchanged rows. Pass include_unchanged=false to suppress unchanged row details while keeping plan_summary counts."
+      : "Rerun the restore plan with include_unchanged=true or omit include_unchanged to retrieve unchanged row details.",
+  };
+}
+
+function applyPlanDetailPolicy(plan, { includeUnchanged }) {
+  if (includeUnchanged) {
+    return {
+      plan,
+      planDetailPolicy: buildPlanDetailPolicy({
+        includeUnchanged,
+        omittedUnchangedChangeCount: 0,
+      }),
+    };
+  }
+
+  const visibleChanges = [];
+  let omittedUnchangedChangeCount = 0;
+  for (const change of plan.changes) {
+    if (change.action === "unchanged") {
+      omittedUnchangedChangeCount += 1;
+    } else {
+      visibleChanges.push(change);
+    }
+  }
+
+  return {
+    plan: {
+      ...plan,
+      changes: visibleChanges,
+    },
+    planDetailPolicy: buildPlanDetailPolicy({
+      includeUnchanged,
+      omittedUnchangedChangeCount,
+    }),
+  };
+}
+
+const BLOCKING_REQUIREMENT_PRIORITY = new Map([
+  ["project_restore_current_snapshot_confirmation_required", 0],
+  ["project_restore_current_snapshot_changed", 1],
+  ["project_restore_destructive_confirmation_required", 2],
+  ["project_restore_cross_scope_confirmation_required", 3],
+]);
+
+function buildBlockingRequirements(diagnostics) {
+  return [...diagnostics]
+    .sort((left, right) => {
+      const priorityDelta =
+        (BLOCKING_REQUIREMENT_PRIORITY.get(left.type) ?? 99) -
+        (BLOCKING_REQUIREMENT_PRIORITY.get(right.type) ?? 99);
+      if (priorityDelta !== 0) return priorityDelta;
+      return left.type.localeCompare(right.type);
+    })
+    .map(diagnostic => ({
+      type: diagnostic.type,
+      message: diagnostic.message,
+      next_step: diagnostic.next_step ?? null,
+      details: diagnostic.details,
+    }));
+}
+
 function placeholders(values) {
   return values.map(() => "?").join(",") || "NULL";
 }
@@ -1059,6 +1141,7 @@ export function restoreProjectFromBackup(db, {
   confirmDestructive = false,
   confirmCrossScope = false,
   expectedCurrentSnapshotChecksum = null,
+  includeUnchanged = true,
   applicationVersion = "0.0.0",
 } = {}) {
   const resolvedBackupDir = resolveBackupDir(backupPath ?? path.join(syncDir, "project-backups", projectId));
@@ -1150,6 +1233,10 @@ export function restoreProjectFromBackup(db, {
   }
 
   const plan = buildRestorePlan(current.snapshot, snapshot, { projectId });
+  const planSummary = buildPlanSummary(plan);
+  const { plan: responsePlan, planDetailPolicy } = applyPlanDetailPolicy(plan, {
+    includeUnchanged: includeUnchanged !== false,
+  });
   const applyDiagnostics = [];
   if (dryRun === false) {
     if (typeof expectedCurrentSnapshotChecksum !== "string" || expectedCurrentSnapshotChecksum === "") {
@@ -1222,8 +1309,11 @@ export function restoreProjectFromBackup(db, {
       dry_run: Boolean(dryRun),
       project_id: projectId,
       backup_dir: resolvedBackupDir,
+      blocking_requirements: buildBlockingRequirements(applyDiagnostics),
       diagnostics: applyDiagnostics,
-      plan,
+      plan_summary: planSummary,
+      plan_detail_policy: planDetailPolicy,
+      plan: responsePlan,
       next_step: "Resolve confirmation requirements before applying this trusted backup.",
     };
   }
@@ -1259,7 +1349,9 @@ export function restoreProjectFromBackup(db, {
           },
           { severity: "error", nextStep: "Review the database error and retry after resolving conflicts." }
         )],
-        plan,
+        plan_summary: planSummary,
+        plan_detail_policy: planDetailPolicy,
+        plan: responsePlan,
         next_step: "Resolve restore write diagnostics before retrying.",
       };
     }
@@ -1279,7 +1371,9 @@ export function restoreProjectFromBackup(db, {
     },
     current_snapshot_checksum: current.checksum,
     backup_snapshot_checksum: manifest.checksums.canonical_snapshot_sha256,
-    plan,
+    plan_summary: planSummary,
+    plan_detail_policy: planDetailPolicy,
+    plan: responsePlan,
     applied: dryRun ? null : {
       restored: true,
       destructive_confirmed: Boolean(confirmDestructive),

package/src/tools/sync.js

@@ -338,7 +338,7 @@ export function registerSyncTools(s, {
 
   s.tool(
     "restore_project_from_backup",
-    "Explicitly restore a project from a trusted generated project backup bundle. Defaults to dry-run planning; dry_run=false applies canonical SQLite changes transactionally after the reviewed current snapshot checksum and required destructive or cross-scope confirmations are provided.",
+    "Explicitly restore a project from a trusted generated project backup bundle. Defaults to dry-run planning; dry_run=false applies canonical SQLite changes transactionally after the reviewed current snapshot checksum and required destructive or cross-scope confirmations are provided. Restore plan and confirmation-refusal responses include compact plan_summary details; confirmation refusals include blocking_requirements. include_unchanged=false suppresses unchanged row details while preserving summary counts.",
     {
       project_id: z.string().describe("Project ID to restore (e.g. 'test-novel' or 'universe-1/book-1-the-lamb')."),
       backup_path: z.string().optional().describe("Path under WRITING_SYNC_DIR to a project backup directory, manifest.json, or canonical.snapshot.json. Defaults to project-backups/<project_id>."),
@@ -346,8 +346,9 @@ export function registerSyncTools(s, {
       confirm_destructive: z.boolean().optional().describe("Required with dry_run=false when the restore plan includes delete candidates."),
       confirm_cross_scope: z.boolean().optional().describe("Required with dry_run=false when the restore plan changes universe-scoped records."),
       expected_current_snapshot_checksum: z.string().optional().describe("Required with dry_run=false; pass the current_snapshot_checksum returned by the reviewed dry-run plan to guard against state changes before apply."),
+      include_unchanged: z.boolean().optional().describe("If false, suppress unchanged rows from plan.changes while preserving plan_summary counts. Defaults to true for compatibility."),
     },
-    async ({ project_id, backup_path, dry_run = true, confirm_destructive = false, confirm_cross_scope = false, expected_current_snapshot_checksum = null } = {}) => {
+    async ({ project_id, backup_path, dry_run = true, confirm_destructive = false, confirm_cross_scope = false, expected_current_snapshot_checksum = null, include_unchanged = true } = {}) => {
       if (!SYNC_DIR_WRITABLE && dry_run === false) {
         return errorResponse("READ_ONLY", "Cannot restore project from backup: server is in read-only mode for canonical structure mutations.");
       }
@@ -374,6 +375,7 @@ export function registerSyncTools(s, {
           confirmDestructive: confirm_destructive,
           confirmCrossScope: confirm_cross_scope,
           expectedCurrentSnapshotChecksum: expected_current_snapshot_checksum,
+          includeUnchanged: include_unchanged,
           applicationVersion: MCP_SERVER_VERSION,
         }));
       } catch (error) {