@hanna84/mcp-writing 3.4.4 → 3.5.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.5.0](https://github.com/hannasdev/mcp-writing/compare/v3.4.4...v3.5.0)
+
+- feat: add accountable beta-reader bundle fingerprinting [`#182`](https://github.com/hannasdev/mcp-writing/pull/182)
+
 #### [v3.4.4](https://github.com/hannasdev/mcp-writing/compare/v3.4.3...v3.4.4)
 
+> 8 May 2026
+
 - chore(copilot): tune instructions based on analysis [`#181`](https://github.com/hannasdev/mcp-writing/pull/181)
+- Release 3.4.4 [`c76d472`](https://github.com/hannasdev/mcp-writing/commit/c76d47214be566dd52d5260f97b29e078e1047b6)
 
 #### [v3.4.3](https://github.com/hannasdev/mcp-writing/compare/v3.4.2...v3.4.3)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.4.4",
+  "version": "3.5.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/review-bundles/review-bundles-planner.js

@@ -1,5 +1,6 @@
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
 const MAX_SCENE_ID_FILTER_PARAMS = 900;
+const MAX_CHAPTER_FILTER_PARAMS = 900;
 
 export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
 export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
@@ -124,12 +125,14 @@ export function buildReviewBundlePlan(dbHandle, {
   profile,
   part,
   chapter,
+  chapters,
   tag,
   scene_ids,
   strictness = "warn",
   include_scene_ids = true,
   include_metadata_sidebar = false,
   include_paragraph_anchors = false,
+  beta_accountability,
   bundle_name,
   recipient_name,
   format = "pdf",
@@ -148,10 +151,46 @@ export function buildReviewBundlePlan(dbHandle, {
       }
     );
   }
+  if (Array.isArray(chapters) && chapters.length > MAX_CHAPTER_FILTER_PARAMS) {
+    throw new ReviewBundlePlanError(
+      "CHAPTERS_FILTER_TOO_LARGE",
+      `chapters supports at most ${MAX_CHAPTER_FILTER_PARAMS} entries per request.`,
+      {
+        max_chapters: MAX_CHAPTER_FILTER_PARAMS,
+        received_chapters: chapters.length,
+      }
+    );
+  }
 
   assertProfile(profile);
   assertStrictness(strictness);
   assertFormat(format);
+  if (chapter !== undefined && chapters !== undefined) {
+    throw new ReviewBundlePlanError(
+      "INVALID_CHAPTER_FILTER",
+      "Use either chapter or chapters, not both.",
+      { chapter, chapters }
+    );
+  }
+  let normalizedChapters;
+  if (chapters !== undefined) {
+    if (!Array.isArray(chapters) || chapters.length === 0) {
+      throw new ReviewBundlePlanError(
+        "INVALID_CHAPTER_FILTER",
+        "chapters must be a non-empty array of integers when provided.",
+        { chapters }
+      );
+    }
+    if (!chapters.every(value => Number.isInteger(value))) {
+      throw new ReviewBundlePlanError(
+        "INVALID_CHAPTER_FILTER",
+        "chapters must contain only integer chapter numbers.",
+        { chapters }
+      );
+    }
+    // Normalize to a stable set to avoid plan drift from duplicated or reordered values.
+    normalizedChapters = Array.from(new Set(chapters)).sort((a, b) => a - b);
+  }
 
   const projectRow = dbHandle.prepare(`SELECT project_id FROM projects WHERE project_id = ?`).get(project_id);
   if (!projectRow) {
@@ -181,6 +220,11 @@ export function buildReviewBundlePlan(dbHandle, {
     conditions.push("s.chapter = ?");
     conditionParams.push(chapter);
   }
+  if (Array.isArray(normalizedChapters) && normalizedChapters.length > 0) {
+    const placeholders = normalizedChapters.map(() => "?").join(",");
+    conditions.push(`s.chapter IN (${placeholders})`);
+    conditionParams.push(...normalizedChapters);
+  }
 
   let query = `
     SELECT DISTINCT
@@ -213,6 +257,7 @@ export function buildReviewBundlePlan(dbHandle, {
         filters: {
           ...(part !== undefined ? { part } : {}),
           ...(chapter !== undefined ? { chapter } : {}),
+          ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
           ...(tag ? { tag } : {}),
           ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
         },
@@ -293,9 +338,13 @@ export function buildReviewBundlePlan(dbHandle, {
   const appliedFilters = {
     ...(part !== undefined ? { part } : {}),
     ...(chapter !== undefined ? { chapter } : {}),
+    ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
     ...(tag ? { tag } : {}),
     ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
   };
+  const resolvedBetaAccountability = profile === "beta_reader_personalized"
+    ? Boolean(beta_accountability ?? true)
+    : false;
 
   return {
     ok: true,
@@ -307,6 +356,7 @@ export function buildReviewBundlePlan(dbHandle, {
         include_scene_ids: Boolean(include_scene_ids),
         include_metadata_sidebar: Boolean(include_metadata_sidebar),
         include_paragraph_anchors: Boolean(include_paragraph_anchors),
+        beta_accountability: resolvedBetaAccountability,
         ...(resolvedRecipientName ? { recipient_name: resolvedRecipientName } : {}),
       },
     },

package/src/review-bundles/review-bundles-renderer.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import matter from "gray-matter";
 import PDFDocument from "pdfkit";
 import { ReviewBundlePlanError, normalizeRecipientDisplayName } from "./review-bundles-planner.js";
@@ -296,6 +297,55 @@ function renderSceneBlock(scene, options) {
   return parts.join("\n\n");
 }
 
+function normalizeFingerprintFilters(filters) {
+  const normalized = { ...(filters ?? {}) };
+  if (Array.isArray(normalized.scene_ids)) {
+    normalized.scene_ids = [...new Set(normalized.scene_ids.map(sceneId => String(sceneId)))].sort();
+  }
+  return normalized;
+}
+
+function stableSerializeForFingerprint(value) {
+  if (Array.isArray(value)) {
+    return value.map(item => stableSerializeForFingerprint(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce((result, key) => {
+        result[key] = stableSerializeForFingerprint(value[key]);
+        return result;
+      }, {});
+  }
+  return value;
+}
+
+function buildFingerprintSeed(plan, generatedAt, recipientDisplayName) {
+  const base = {
+    project_id: plan.resolved_scope?.project_id ?? "",
+    profile: plan.profile ?? "",
+    recipient_name: recipientDisplayName ?? "",
+    filters: normalizeFingerprintFilters(plan.resolved_scope?.filters),
+    scene_ids: (plan.ordering ?? []).map(row => row.scene_id),
+    generated_at: generatedAt ?? "",
+  };
+  return JSON.stringify(stableSerializeForFingerprint(base));
+}
+
+function buildFingerprintSeedHash(seed) {
+  return crypto.createHash("sha256").update(String(seed)).digest("hex");
+}
+
+function buildPageFingerprintToken({ seedHash, pageNumber }) {
+  const digest = crypto
+    .createHash("sha256")
+    .update(`${seedHash}|page:${pageNumber}`)
+    .digest("hex")
+    .slice(0, 12)
+    .toUpperCase();
+  return `BR-${digest}-P${String(pageNumber).padStart(3, "0")}`;
+}
+
 export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir: syncDirOpt } = {}) {
   const profile = plan.profile;
   const includeSceneIds = Boolean(plan.resolved_scope?.options?.include_scene_ids);
@@ -365,6 +415,11 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
 }
 
 export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: syncDirOpt } = {}) {
+  return renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt, syncDir: syncDirOpt })
+    .then(result => result.pdf_buffer);
+}
+
+export function renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt, syncDir: syncDirOpt } = {}) {
   const profile = plan.profile;
   const includeSceneIds = Boolean(plan.resolved_scope?.options?.include_scene_ids);
   const syncDir = syncDirOpt ?? process.env.WRITING_SYNC_DIR ?? null;
@@ -373,16 +428,57 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
   const rows = loadBundleSceneRows(dbHandle, plan.resolved_scope.project_id, sceneIds);
   const recipientName = plan.resolved_scope?.options?.recipient_name;
   const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
-
+  const betaAccountabilityEnabled = profile === "beta_reader_personalized"
+    && Boolean(plan.resolved_scope?.options?.beta_accountability);
+  const effectiveGeneratedAt = generatedAt ?? new Date().toISOString();
+  const fingerprintSeed = betaAccountabilityEnabled
+    ? buildFingerprintSeed(plan, effectiveGeneratedAt, recipientDisplayName)
+    : null;
+  const fingerprintSeedHash = fingerprintSeed ? buildFingerprintSeedHash(fingerprintSeed) : null;
+  const pageTokens = [];
+  let pageNumber = 0;
+
+  const pdfOptions = profile === "beta_reader_personalized"
+    ? {
+        size: [432, 648], // 6x9in in PDF points
+        margins: { top: 64, right: 58, bottom: 72, left: 58 },
+        autoFirstPage: false,
+      }
+    : {
+        size: "Letter",
+        margin: 50,
+        autoFirstPage: false,
+      };
   const doc = new PDFDocument({
-    size: "Letter",
-    margin: 50,
+    ...pdfOptions,
   });
 
+  const drawAccountabilityFooter = () => {
+    if (!betaAccountabilityEnabled || !fingerprintSeedHash) return;
+    pageNumber += 1;
+    const token = buildPageFingerprintToken({
+      seedHash: fingerprintSeedHash,
+      pageNumber,
+    });
+    pageTokens.push({ page: pageNumber, token });
+    const footerY = doc.page.height - doc.page.margins.bottom - 12;
+    const footerWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const footerText = `For: ${recipientDisplayName} | Fingerprint: ${token} | Page ${pageNumber}`;
+    doc.save();
+    doc.font("Helvetica").fontSize(8).fillColor("#555555");
+    doc.text(footerText, doc.page.margins.left, footerY, {
+      width: footerWidth,
+      align: "left",
+      lineBreak: false,
+    });
+    doc.restore();
+  };
+  doc.on("pageAdded", drawAccountabilityFooter);
+
   // Register listeners before any content is written so render-time errors
   // always reject the returned Promise.
-  const chunks = [];
   return new Promise((resolve, reject) => {
+    const chunks = [];
     let settled = false;
     const fail = (err) => {
       if (settled) return;
@@ -395,10 +491,20 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
     doc.on("end", () => {
       if (settled) return;
       settled = true;
-      resolve(Buffer.concat(chunks));
+      resolve({
+        pdf_buffer: Buffer.concat(chunks),
+        fingerprint: betaAccountabilityEnabled
+          ? {
+              mode: "visible_footer",
+              recipient_display_name: recipientDisplayName,
+              page_tokens: pageTokens,
+            }
+          : null,
+      });
     });
 
     try {
+      doc.addPage();
       doc.fontSize(24).font("Helvetica-Bold").text(`Review Bundle: ${plan.resolved_scope.project_id}`, { align: "left" });
       doc.moveDown(0.5);
       doc.fontSize(11).font("Helvetica");
@@ -406,7 +512,7 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
       if (profile === "beta_reader_personalized") {
         doc.text(`Recipient: ${recipientDisplayName}`, { align: "left" });
       }
-      doc.text(`Generated: ${generatedAt ?? new Date().toISOString()}`, { align: "left" });
+      doc.text(`Generated: ${effectiveGeneratedAt}`, { align: "left" });
       doc.text(`Scenes: ${plan.summary.scene_count}`, { align: "left" });
       doc.moveDown();
 
@@ -470,7 +576,7 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
           doc.text(prose, {
             align: "left",
             width: textWidth,
-            lineGap: 3,
+            lineGap: profile === "beta_reader_personalized" ? 4.5 : 3,
           });
         }
 
@@ -495,4 +601,10 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
   });
 }
 
-export { renderBetaNoticeMarkdown, renderBetaFeedbackFormMarkdown };
+export {
+  renderBetaNoticeMarkdown,
+  renderBetaFeedbackFormMarkdown,
+  buildPageFingerprintToken,
+  buildFingerprintSeed,
+  buildFingerprintSeedHash,
+};

package/src/review-bundles/review-bundles-writer.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { ReviewBundlePlanError } from "./review-bundles-planner.js";
-import { renderReviewBundleMarkdown, renderReviewBundlePdf, renderBetaNoticeMarkdown, renderBetaFeedbackFormMarkdown } from "./review-bundles-renderer.js";
+import { renderReviewBundleMarkdown, renderReviewBundlePdfWithMetadata, renderBetaNoticeMarkdown, renderBetaFeedbackFormMarkdown } from "./review-bundles-renderer.js";
 
 function resolveOutputFilePath(outputDir, fileName) {
   const normalizedOutputDir = path.resolve(outputDir);
@@ -82,8 +82,11 @@ export async function createReviewBundleArtifacts(dbHandle, {
   const markdown = markdownPath ? renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir }) : null;
 
   let pdfBuffer = null;
+  let fingerprintMetadata = null;
   if (pdfPath) {
-    pdfBuffer = await renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir });
+    const pdfResult = await renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt, syncDir });
+    pdfBuffer = pdfResult.pdf_buffer;
+    fingerprintMetadata = pdfResult.fingerprint;
   }
 
   const recipientName = plan.resolved_scope?.options?.recipient_name;
@@ -108,6 +111,7 @@ export async function createReviewBundleArtifacts(dbHandle, {
     warnings: plan.warnings,
     resolved_scope: plan.resolved_scope,
     scene_ids: plan.ordering.map(row => row.scene_id),
+    ...(fingerprintMetadata ? { fingerprint: fingerprintMetadata } : {}),
   };
 
   for (const outputPath of [markdownPath, pdfPath, manifestPath, noticePath, feedbackPath].filter(Boolean)) {

package/src/review-bundles/review-bundles.js

@@ -9,6 +9,10 @@ export {
 export {
   renderReviewBundleMarkdown,
   renderReviewBundlePdf,
+  renderReviewBundlePdfWithMetadata,
+  buildPageFingerprintToken,
+  buildFingerprintSeed,
+  buildFingerprintSeedHash,
 } from "./review-bundles-renderer.js";
 
 export { createReviewBundleArtifacts } from "./review-bundles-writer.js";

package/src/tools/review-bundles.js

@@ -28,6 +28,7 @@ export function registerReviewBundleTools(s, {
       profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       part: z.number().int().optional().describe("Optional part filter."),
       chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),
@@ -35,6 +36,7 @@ export function registerReviewBundleTools(s, {
       include_metadata_sidebar: z.boolean().optional().describe("Rendering option (default false). Echoed in resolved_scope.options for downstream rendering; does not change planning results."),
       include_paragraph_anchors: z.boolean().optional().describe("Rendering option (default false). Echoed in resolved_scope.options for downstream rendering; does not change planning results."),
       recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized profile."),
+      beta_accountability: z.boolean().optional().describe("Enable accountability footer + fingerprint metadata for beta_reader_personalized output (default true for beta profile)."),
       bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in planned outputs)."),
       format: z.enum(["pdf", "markdown", "both"]).optional().describe("Planned output format: pdf (default), markdown, or both. Affects planned_outputs filenames only; preview_review_bundle does not render artifacts."),
     },
@@ -43,6 +45,7 @@ export function registerReviewBundleTools(s, {
       profile,
       part,
       chapter,
+      chapters,
       tag,
       scene_ids,
       strictness = "warn",
@@ -50,6 +53,7 @@ export function registerReviewBundleTools(s, {
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
       recipient_name,
+      beta_accountability,
       bundle_name,
       format = "pdf",
     }) => {
@@ -64,6 +68,7 @@ export function registerReviewBundleTools(s, {
           profile,
           part,
           chapter,
+          chapters,
           tag,
           scene_ids,
           strictness,
@@ -71,6 +76,7 @@ export function registerReviewBundleTools(s, {
           include_metadata_sidebar,
           include_paragraph_anchors,
           recipient_name,
+          beta_accountability,
           bundle_name,
           format,
         });
@@ -110,6 +116,7 @@ export function registerReviewBundleTools(s, {
       output_dir: z.string().describe("Directory path to write bundle artifacts into."),
       part: z.number().int().optional().describe("Optional part filter."),
       chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),
@@ -117,6 +124,7 @@ export function registerReviewBundleTools(s, {
       include_metadata_sidebar: z.boolean().optional().describe("Include metadata sidebar in markdown output (default false). Markdown only — no effect on PDF."),
       include_paragraph_anchors: z.boolean().optional().describe("Include paragraph anchors in markdown output (default false). Markdown only — no effect on PDF."),
       recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized profile."),
+      beta_accountability: z.boolean().optional().describe("Enable accountability footer + fingerprint metadata for beta_reader_personalized output (default true for beta profile)."),
       bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in filenames)."),
       source_commit: z.string().optional().describe("Optional explicit source commit for provenance. Defaults to current HEAD when available."),
       format: z.enum(["pdf", "markdown", "both"]).optional().describe("Output format: pdf (default), markdown, or both."),
@@ -127,6 +135,7 @@ export function registerReviewBundleTools(s, {
       output_dir,
       part,
       chapter,
+      chapters,
       tag,
       scene_ids,
       strictness = "warn",
@@ -134,6 +143,7 @@ export function registerReviewBundleTools(s, {
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
       recipient_name,
+      beta_accountability,
       bundle_name,
       source_commit,
       format = "pdf",
@@ -162,6 +172,7 @@ export function registerReviewBundleTools(s, {
           profile,
           part,
           chapter,
+          chapters,
           tag,
           scene_ids,
           strictness,
@@ -169,6 +180,7 @@ export function registerReviewBundleTools(s, {
           include_metadata_sidebar,
           include_paragraph_anchors,
           recipient_name,
+          beta_accountability,
           bundle_name,
           format,
         });