@hanna84/mcp-writing 1.16.2 → 1.17.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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).
 
+#### [v1.17.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.16.2...v1.17.0)
+
+- feat: add beta_reader_personalized review bundle profile [`#77`](https://github.com/hannasdev/mcp-writing.git
+/pull/77)
+
 #### [v1.16.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.16.1...v1.16.2)
 
+> 25 April 2026
+
 - docs: close out review bundles M1 and add troubleshooting guidance [`#76`](https://github.com/hannasdev/mcp-writing.git
 /pull/76)
+- Release 1.16.2 [`557623a`](https://github.com/hannasdev/mcp-writing.git
+/commit/557623afb18e4f5f5dbec565eee1cbd481051275)
 
 #### [v1.16.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.16.0...v1.16.1)

package/index.js

@@ -1352,7 +1352,7 @@ function createMcpServer() {
     "Dry-run planning tool for review bundles. Resolves scene scope, deterministic ordering, warnings, and planned output filenames without writing files. Note: include_scene_ids/include_metadata_sidebar/include_paragraph_anchors are advisory placeholders in Phase 4A.1 and do not alter planning semantics yet.",
     {
       project_id: z.string().describe("Project ID to scope the review bundle (e.g. 'test-novel')."),
-      profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion or editor_detailed."),
+      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."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
@@ -1361,6 +1361,7 @@ function createMcpServer() {
       include_scene_ids: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default true). Included in preview output options, but does not change planning results in Phase 4A.1."),
       include_metadata_sidebar: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default false). Included in preview output options, but does not change planning results in Phase 4A.1."),
       include_paragraph_anchors: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default false). Included in preview output options, but does not change planning results in Phase 4A.1."),
+      recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized profile."),
       bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in planned outputs)."),
     },
     async ({
@@ -1374,6 +1375,7 @@ function createMcpServer() {
       include_scene_ids = true,
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
+      recipient_name,
       bundle_name,
     }) => {
       const projectIdCheck = validateProjectId(project_id);
@@ -1393,6 +1395,7 @@ function createMcpServer() {
           include_scene_ids,
           include_metadata_sidebar,
           include_paragraph_anchors,
+          recipient_name,
           bundle_name,
         });
         return jsonResponse(plan);
@@ -1414,7 +1417,7 @@ function createMcpServer() {
     "Generate markdown review bundle artifacts from planned scene scope. Writes files only under output_dir and returns manifest/provenance details.",
     {
       project_id: z.string().describe("Project ID to scope the review bundle (e.g. 'test-novel')."),
-      profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion or editor_detailed."),
+      profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       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."),
@@ -1424,6 +1427,7 @@ function createMcpServer() {
       include_scene_ids: z.boolean().optional().describe("Include scene IDs in markdown headings (default true)."),
       include_metadata_sidebar: z.boolean().optional().describe("Include metadata sidebar in markdown output (default false)."),
       include_paragraph_anchors: z.boolean().optional().describe("Include paragraph anchors in markdown output (default false)."),
+      recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized 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."),
     },
@@ -1439,6 +1443,7 @@ function createMcpServer() {
       include_scene_ids = true,
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
+      recipient_name,
       bundle_name,
       source_commit,
     }) => {
@@ -1472,6 +1477,7 @@ function createMcpServer() {
           include_scene_ids,
           include_metadata_sidebar,
           include_paragraph_anchors,
+          recipient_name,
           bundle_name,
         });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.16.2",
+  "version": "1.17.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -29,6 +29,7 @@
     "manual:test": "node scripts/manual/test.mjs",
     "manual:scenarios": "node scripts/manual/test-scenarios.mjs",
     "manual:merge-beta-test": "node scripts/manual/run_mcp_test.js",
+    "manual:review-bundle": "node scripts/manual/run_create_review_bundle.js",
     "setup:openclaw-env": "sh scripts/setup-openclaw-env.sh",
     "release": "release-it",
     "lint": "eslint index.js importer.js db.js sync.js metadata-lint.js scripts/",

package/review-bundles.js

@@ -4,7 +4,7 @@ import matter from "gray-matter";
 
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
 
-export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed"];
+export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
 export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
 
 export class ReviewBundlePlanError extends Error {
@@ -63,6 +63,62 @@ function escapeMarkdown(text) {
     .replace(/([*_`\[\]#])/g, "\\$1");
 }
 
+function normalizeRecipientDisplayName(recipientName) {
+  const normalized = String(recipientName ?? "")
+    .replace(/[\x00-\x1f\x7f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 100);
+
+  return normalized || "Beta Reader";
+}
+
+function renderBetaNoticeMarkdown({ projectId, recipientName }) {
+  const displayName = normalizeRecipientDisplayName(recipientName);
+  return [
+    "# Non-Distribution Notice",
+    "",
+    `This review packet is prepared for ${escapeMarkdown(displayName)} for private beta-reading purposes only.`,
+    "",
+    "Please do not distribute, repost, or share this material without explicit author permission.",
+    "",
+    "This notice is informational only and is not legal advice.",
+    "",
+    `Project: ${escapeMarkdown(projectId)}`,
+  ].join("\n") + "\n";
+}
+
+function renderBetaFeedbackFormMarkdown({ projectId, recipientName, generatedAt }) {
+  const displayName = normalizeRecipientDisplayName(recipientName);
+  const feedbackDate = String(generatedAt ?? new Date().toISOString()).slice(0, 10);
+  return [
+    "# Beta Reader Feedback Form",
+    "",
+    `- Project: ${escapeMarkdown(projectId)}`,
+    `- Reader: ${escapeMarkdown(displayName)}`,
+    `- Date: ${feedbackDate}`,
+    "",
+    "## Big-Picture Questions",
+    "",
+    "1. Which sections felt most compelling, and why?",
+    "2. Where did pacing feel slow, rushed, or unclear?",
+    "3. Were any character motivations confusing or unconvincing?",
+    "",
+    "## Scene-Level Notes",
+    "",
+    "Use scene IDs when possible.",
+    "",
+    "- Scene ID:",
+    "- Comment:",
+    "- Severity (nit / moderate / major):",
+    "",
+    "## Final Thoughts",
+    "",
+    "- What should be prioritized in the next revision?",
+    "- Any continuity concerns to flag?",
+  ].join("\n") + "\n";
+}
+
 function resolveOutputFilePath(outputDir, fileName) {
   const normalizedOutputDir = path.resolve(outputDir);
   const target = path.resolve(normalizedOutputDir, fileName);
@@ -125,6 +181,7 @@ export function buildReviewBundlePlan(dbHandle, {
   include_metadata_sidebar = false,
   include_paragraph_anchors = false,
   bundle_name,
+  recipient_name,
 } = {}) {
   if (!project_id) {
     throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
@@ -264,6 +321,9 @@ export function buildReviewBundlePlan(dbHandle, {
     const count = Number(row.word_count);
     return sum + (Number.isFinite(count) ? count : 0);
   }, 0);
+  const resolvedRecipientName = profile === "beta_reader_personalized"
+    ? normalizeRecipientDisplayName(recipient_name)
+    : undefined;
 
   const safeBundleName = slugifyBundleName(bundle_name || `${project_id}-${profile}`);
   const appliedFilters = {
@@ -283,6 +343,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),
+        ...(resolvedRecipientName ? { recipient_name: resolvedRecipientName } : {}),
       },
     },
     ordering: rows.map(row => ({
@@ -308,6 +369,12 @@ export function buildReviewBundlePlan(dbHandle, {
     },
     planned_outputs: [
       `${safeBundleName}.md`,
+      ...(profile === "beta_reader_personalized"
+        ? [
+            `${safeBundleName}.notice.md`,
+            `${safeBundleName}.feedback-form.md`,
+          ]
+        : []),
       `${safeBundleName}.manifest.json`,
     ],
   };
@@ -567,19 +634,35 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
   const sceneIds = plan.ordering.map(row => row.scene_id);
   const rows = loadBundleSceneRows(dbHandle, plan.resolved_scope.project_id, sceneIds);
   const sections = [];
+  const recipientName = plan.resolved_scope?.options?.recipient_name;
+  const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
 
   const headerLines = [
     `# Review Bundle: ${escapeMarkdown(plan.resolved_scope.project_id)}`,
     "",
     `- Profile: ${profile}`,
+    ...(profile === "beta_reader_personalized"
+      ? [`- Recipient: ${escapeMarkdown(recipientDisplayName)}`]
+      : []),
     `- Generated at: ${generatedAt ?? new Date().toISOString()}`,
     `- Scene count: ${plan.summary.scene_count}`,
   ];
   sections.push(headerLines.join("\n"));
 
+  if (profile === "beta_reader_personalized") {
+    sections.push(
+      [
+        "## Usage Notice",
+        "",
+        "This beta-reader draft is intended for private review and feedback.",
+        "Please do not redistribute without explicit author permission.",
+      ].join("\n")
+    );
+  }
+
   for (const scene of rows) {
     let prose = "";
-    if (profile === "editor_detailed") {
+    if (profile === "editor_detailed" || profile === "beta_reader_personalized") {
       const resolved = readProse(scene.file_path, { syncDir });
       if (resolved === null) {
         throw new ReviewBundlePlanError(
@@ -636,7 +719,14 @@ export function createReviewBundleArtifacts(dbHandle, {
     );
   }
 
-  const markdownFileName = plan.planned_outputs.find(name => name.endsWith(".md"));
+  const noticeFileName = plan.planned_outputs.find(name => name.endsWith(".notice.md")) ?? null;
+  const feedbackFileName = plan.planned_outputs.find(name => name.endsWith(".feedback-form.md")) ?? null;
+  const markdownFileName = plan.planned_outputs.find(
+    name =>
+      name.endsWith(".md") &&
+      !name.endsWith(".notice.md") &&
+      !name.endsWith(".feedback-form.md")
+  );
   const manifestFileName = plan.planned_outputs.find(name => name.endsWith(".manifest.json"));
   if (!markdownFileName || !manifestFileName) {
     throw new ReviewBundlePlanError(
@@ -647,9 +737,18 @@ export function createReviewBundleArtifacts(dbHandle, {
 
   const markdownPath = resolveOutputFilePath(normalizedOutputDir, markdownFileName);
   const manifestPath = resolveOutputFilePath(normalizedOutputDir, manifestFileName);
+  const noticePath = noticeFileName ? resolveOutputFilePath(normalizedOutputDir, noticeFileName) : null;
+  const feedbackPath = feedbackFileName ? resolveOutputFilePath(normalizedOutputDir, feedbackFileName) : null;
 
   const generatedAt = new Date().toISOString();
   const markdown = renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir });
+  const recipientName = plan.resolved_scope?.options?.recipient_name;
+  const betaNotice = plan.profile === "beta_reader_personalized"
+    ? renderBetaNoticeMarkdown({ projectId: plan.resolved_scope.project_id, recipientName })
+    : null;
+  const betaFeedbackForm = plan.profile === "beta_reader_personalized"
+    ? renderBetaFeedbackFormMarkdown({ projectId: plan.resolved_scope.project_id, recipientName, generatedAt })
+    : null;
   const manifest = {
     bundle_id: path.basename(markdownFileName, ".md"),
     profile: plan.profile,
@@ -665,7 +764,7 @@ export function createReviewBundleArtifacts(dbHandle, {
     scene_ids: plan.ordering.map(row => row.scene_id),
   };
 
-  for (const outputPath of [markdownPath, manifestPath]) {
+  for (const outputPath of [markdownPath, manifestPath, noticePath, feedbackPath].filter(Boolean)) {
     try {
       const stat = fs.lstatSync(outputPath);
       if (stat.isSymbolicLink()) {
@@ -692,12 +791,20 @@ export function createReviewBundleArtifacts(dbHandle, {
 
   fs.writeFileSync(markdownPath, markdown, "utf8");
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  if (noticePath && betaNotice != null) {
+    fs.writeFileSync(noticePath, betaNotice, "utf8");
+  }
+  if (feedbackPath && betaFeedbackForm != null) {
+    fs.writeFileSync(feedbackPath, betaFeedbackForm, "utf8");
+  }
 
   return {
     bundle_id: manifest.bundle_id,
     output_paths: {
       bundle_markdown: markdownPath,
       manifest_json: manifestPath,
+      ...(noticePath ? { notice_md: noticePath } : {}),
+      ...(feedbackPath ? { feedback_form_md: feedbackPath } : {}),
     },
     generated_at: generatedAt,
   };

package/scripts/manual/run_create_review_bundle.js

@@ -2,11 +2,12 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import path from "path";
 import process from "process";
+import fs from "node:fs";
 
 async function main() {
   const [projectId, profile, outputDir, ...flags] = process.argv.slice(2);
   if (!projectId || !profile || !outputDir) {
-    console.error("Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_create_review_bundle.js <project_id> <profile> <output_dir> [--anchors] [--bundle-name <name>]");
+    console.error("Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_create_review_bundle.js <project_id> <profile> <output_dir> [--anchors] [--recipient <name>] [--bundle-name <name>] [--skip-preview] [--show-files]");
     process.exit(1);
   }
 
@@ -19,8 +20,28 @@ async function main() {
   }
 
   const includeParagraphAnchors = flags.includes("--anchors");
+  const skipPreview = flags.includes("--skip-preview");
+  const showFiles = flags.includes("--show-files");
   const bundleNameIdx = flags.indexOf("--bundle-name");
   const bundleName = bundleNameIdx !== -1 ? flags[bundleNameIdx + 1] : undefined;
+  const recipientIdx = flags.indexOf("--recipient");
+  const recipientName = recipientIdx !== -1 ? flags[recipientIdx + 1] : undefined;
+
+  const baseArguments = {
+    project_id: projectId,
+    profile,
+    ...(includeParagraphAnchors ? { include_paragraph_anchors: true } : {}),
+    ...(bundleName ? { bundle_name: bundleName } : {}),
+    ...(recipientName ? { recipient_name: recipientName } : {}),
+  };
+
+  function printArtifactExcerpt(label, filePath) {
+    if (!filePath || !fs.existsSync(filePath)) return;
+    const content = fs.readFileSync(filePath, "utf8");
+    const excerpt = content.split("\n").slice(0, 20).join("\n");
+    console.log(`\n--- ${label}: ${filePath} ---`);
+    console.log(excerpt);
+  }
 
   const transport = new StdioClientTransport({
     command: process.execPath,
@@ -41,18 +62,38 @@ async function main() {
 
   try {
     await client.connect(transport);
+
+    if (!skipPreview) {
+      const previewResult = await client.callTool({
+        name: "preview_review_bundle",
+        arguments: baseArguments,
+      });
+      const previewText = previewResult.content?.[0]?.text ?? "";
+      console.log("\n=== preview_review_bundle ===");
+      console.log(previewText);
+    }
+
     const result = await client.callTool({
       name: "create_review_bundle",
       arguments: {
-        project_id: projectId,
-        profile: profile,
+        ...baseArguments,
         output_dir: outputDir,
-        ...(includeParagraphAnchors ? { include_paragraph_anchors: true } : {}),
-        ...(bundleName ? { bundle_name: bundleName } : {})
       }
     });
 
-    console.log(JSON.stringify(result, null, 2));
+    const resultText = result.content?.[0]?.text ?? "";
+    console.log("\n=== create_review_bundle ===");
+    console.log(resultText);
+
+    if (showFiles) {
+      const parsed = JSON.parse(resultText);
+      if (parsed.ok && parsed.output_paths) {
+        printArtifactExcerpt("Bundle Markdown", parsed.output_paths.bundle_markdown);
+        printArtifactExcerpt("Manifest JSON", parsed.output_paths.manifest_json);
+        printArtifactExcerpt("Notice Markdown", parsed.output_paths.notice_md);
+        printArtifactExcerpt("Feedback Form Markdown", parsed.output_paths.feedback_form_md);
+      }
+    }
   } catch (e) {
     console.error(e);
     process.exitCode = 1;