@hanna84/mcp-writing 2.10.3 → 2.10.5

package/CHANGELOG.md

@@ -4,11 +4,31 @@ 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).
 
+#### [v2.10.5](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.4...v2.10.5)
+
+- refactor(index): extract workflow catalogue module [`#109`](https://github.com/hannasdev/mcp-writing.git
+/pull/109)
+
+#### [v2.10.4](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.3...v2.10.4)
+
+> 27 April 2026
+
+- fix(review-bundles): guard oversized scene_ids in planner [`#108`](https://github.com/hannasdev/mcp-writing.git
+/pull/108)
+- Release 2.10.4 [`6afb4e5`](https://github.com/hannasdev/mcp-writing.git
+/commit/6afb4e51408ce9a42ade76087f4a2f86a6b13c19)
+
 #### [v2.10.3](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.2...v2.10.3)
 
+> 26 April 2026
+
 - refactor(helpers): extract domain helpers and path safety utilities from index.js [`#107`](https://github.com/hannasdev/mcp-writing.git
 /pull/107)
+- Release 2.10.3 [`f3b296a`](https://github.com/hannasdev/mcp-writing.git
+/commit/f3b296a9dbbedafcedab12ca8492d479aaa68180)
 
 #### [v2.10.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.1...v2.10.2)

package/git.js

@@ -35,7 +35,7 @@ export function initGitRepository(dirPath) {
     }
     return true;
   } catch (err) {
-    throw new Error(`Failed to initialize git repository: ${err.message}`);
+    throw new Error(`Failed to initialize git repository: ${err.message}`, { cause: err });
   }
 }
 
@@ -98,7 +98,7 @@ export function createSnapshot(dirPath, filePath, sceneId, instruction, options
         reason: "no changes to commit",
       };
     }
-    throw new Error(`Failed to create snapshot: ${err.message}`);
+    throw new Error(`Failed to create snapshot: ${err.message}`, { cause: err });
   }
 }
 
@@ -137,7 +137,7 @@ export function listSnapshots(dirPath, filePath) {
     if (err.message.includes("your current branch") || err.status === 128) {
       return [];
     }
-    throw new Error(`Failed to list snapshots: ${err.message}`);
+    throw new Error(`Failed to list snapshots: ${err.message}`, { cause: err });
   }
 }
 
@@ -163,10 +163,16 @@ export function getSceneProseAtCommit(dirPath, filePath, commitHash) {
 
     return content;
   } catch (err) {
+    // ENOENT from execFileSync means the git binary was not found on PATH — not a missing file in the commit.
     if (err.code === "ENOENT") {
-      throw new Error(`File not found in commit ${commitHash}`);
+      throw new Error("git executable not found; ensure git is installed and on PATH", { cause: err });
     }
-    throw new Error(`Failed to retrieve scene prose: ${err.message}`);
+    // git exit 128 with "path ... does not exist in" or "bad object" indicates missing path/commit.
+    const stderr = err?.stderr ? String(err.stderr) : "";
+    if (err.status === 128 && (stderr.includes("does not exist in") || stderr.includes("bad object"))) {
+      throw new Error(`File not found in commit ${commitHash}`, { cause: err });
+    }
+    throw new Error(`Failed to retrieve scene prose: ${err.message}`, { cause: err });
   }
 }
 

package/index.js

@@ -25,6 +25,7 @@ import { registerMetadataTools } from "./tools/metadata.js";
 import { registerReviewBundleTools } from "./tools/review-bundles.js";
 import { registerStyleguideTools } from "./tools/styleguide.js";
 import { registerEditingTools } from "./tools/editing.js";
+import { WORKFLOW_CATALOGUE } from "./workflow-catalogue.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -357,102 +358,6 @@ function maxScenesNextStep(matchedCount) {
   return `Re-run with max_scenes set to at least ${matchedCount}.`;
 }
 
-const WORKFLOW_CATALOGUE = [
-  {
-    id: "first_time_setup",
-    label: "First-time setup",
-    use_when: "Connecting to a project for the first time or verifying the runtime is correctly configured.",
-    steps: [
-      { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
-      { tool: "sync", note: "Index scenes from disk." },
-    ],
-  },
-  {
-    id: "styleguide_setup_new",
-    label: "Styleguide setup (new project)",
-    use_when: "No prose styleguide config exists and you want to create one based on the manuscript's existing conventions.",
-    steps: [
-      { tool: "describe_workflows", note: "Check context.scene_count; use that value as max_scenes in the next call." },
-      { tool: "bootstrap_prose_styleguide_config", note: "Detect dominant conventions. Confirm suggestions with the user before applying." },
-      { tool: "setup_prose_styleguide_config", note: "Only if ALL context.styleguide_exists fields are false — a config at any scope is sufficient. Create at project_root scope (requires project_id and language e.g. 'english_us'), or sync_root if no project_id is known." },
-      { tool: "update_prose_styleguide_config", note: "Apply the fields accepted from bootstrap suggestions." },
-    ],
-  },
-  {
-    id: "styleguide_drift_check",
-    label: "Styleguide drift check",
-    use_when: "A styleguide config exists and you want to check whether recent scenes conform to it.",
-    steps: [
-      { tool: "get_prose_styleguide_config", note: "Confirm the currently resolved config." },
-      { tool: "check_prose_styleguide_drift", note: "Detect non-conforming scenes. Pass project_id from context.project_id and set max_scenes from context.scene_count." },
-      { tool: "update_prose_styleguide_config", note: "If drift found and user approves, update config or note the outliers." },
-    ],
-  },
-  {
-    id: "manuscript_exploration",
-    label: "Manuscript exploration",
-    use_when: "Answering questions about the manuscript, finding scenes, or getting an overview.",
-    steps: [
-      { tool: "find_scenes", note: "Filter by character, beat, tag, part, chapter, or POV. No filters returns all scenes." },
-      { tool: "get_scene_prose", note: "Load prose for specific scenes identified by find_scenes." },
-      { tool: "get_chapter_prose", note: "Load all prose for a chapter. Use sparingly — large chapters can overflow context." },
-      { tool: "search_metadata", note: "Full-text search across scene metadata fields." },
-    ],
-  },
-  {
-    id: "prose_editing",
-    label: "Prose editing",
-    use_when: "Revising scene prose. All edits require explicit user confirmation before writing.",
-    steps: [
-      { tool: "find_scenes", note: "Identify the target scene." },
-      { tool: "get_scene_prose", note: "Load the current prose." },
-      { tool: "propose_edit", note: "Stage a revision; returns a diff preview and a proposal_id." },
-      { tool: "commit_edit", note: "Write the revision after the user confirms. Runs preflight checks before writing." },
-      { tool: "discard_edit", note: "Reject the revision if the user does not approve." },
-    ],
-  },
-  {
-    id: "character_management",
-    label: "Character management",
-    use_when: "Finding characters, reading their sheets, or updating character details.",
-    steps: [
-      { tool: "list_characters", note: "Find character_id values." },
-      { tool: "get_character_sheet", note: "Read full character details." },
-      { tool: "create_character_sheet", note: "Create a new character. Requires exactly one of project_id or universe_id." },
-      { tool: "update_character_sheet", note: "Edit character metadata." },
-    ],
-  },
-  {
-    id: "place_management",
-    label: "Place management",
-    use_when: "Finding locations, reading place sheets, or updating place details.",
-    steps: [
-      { tool: "list_places", note: "Find place_id values." },
-      { tool: "get_place_sheet", note: "Read full place details." },
-      { tool: "create_place_sheet", note: "Create a new place. Requires exactly one of project_id or universe_id." },
-      { tool: "update_place_sheet", note: "Edit place metadata." },
-    ],
-  },
-  {
-    id: "review_bundle",
-    label: "Review bundle",
-    use_when: "Preparing a formatted bundle for human review (outline, editorial, or beta read profile).",
-    steps: [
-      { tool: "preview_review_bundle", note: "Check which scenes would be included and the estimated size. Requires project_id and profile." },
-      { tool: "create_review_bundle", note: "Generate the bundle. Requires project_id." },
-    ],
-  },
-  {
-    id: "async_job_tracking",
-    label: "Async job tracking",
-    use_when: "A tool returned a job_id instead of an immediate result (e.g. import_scrivener_sync_async).",
-    steps: [
-      { tool: "get_async_job_status", note: "Poll with the job_id until status is 'completed' or 'failed'." },
-      { tool: "sync", note: "Call after a completed job that modified files on disk." },
-    ],
-  },
-];
-
 // ---------------------------------------------------------------------------
 // MCP server factory
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.10.3",
+  "version": "2.10.5",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -16,6 +16,7 @@
     "sync.js",
     "git.js",
     "world-entity-templates.js",
+    "workflow-catalogue.js",
     "metadata-lint.js",
     "scene-character-normalization.js",
     "review-bundles.js",
@@ -44,7 +45,7 @@
     "normalize:scene-characters": "node --experimental-sqlite scripts/normalize-scene-characters.mjs",
     "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/ tools/",
+    "lint": "eslint *.js scripts/ tools/",
     "docs": "node scripts/generate-tool-docs.mjs",
     "lint:metadata": "node scripts/lint-metadata.mjs",
     "test:unit": "node --experimental-sqlite --test test/unit/*.test.mjs",

package/review-bundles-planner.js

@@ -1,4 +1,5 @@
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
+const MAX_SCENE_ID_FILTER_PARAMS = 900;
 
 export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
 export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
@@ -15,7 +16,7 @@ export class ReviewBundlePlanError extends Error {
 
 export function normalizeRecipientDisplayName(recipientName) {
   const normalized = String(recipientName ?? "")
-    .replace(/[\x00-\x1f\x7f]+/g, " ")
+    .replace(/[\x00-\x1f\x7f]+/g, " ") // eslint-disable-line no-control-regex
     .replace(/\s+/g, " ")
     .trim()
     .slice(0, 100);
@@ -99,14 +100,22 @@ function resolveRequestedSceneIds(dbHandle, projectId, sceneIds) {
     return { requested: [], existing: new Set() };
   }
 
-  const placeholders = sceneIds.map(() => "?").join(",");
-  const rows = dbHandle.prepare(
-    `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
-  ).all(projectId, ...sceneIds);
+  const existing = new Set();
+
+  for (let i = 0; i < sceneIds.length; i += MAX_SCENE_ID_FILTER_PARAMS) {
+    const chunk = sceneIds.slice(i, i + MAX_SCENE_ID_FILTER_PARAMS);
+    const placeholders = chunk.map(() => "?").join(",");
+    const rows = dbHandle.prepare(
+      `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
+    ).all(projectId, ...chunk);
+    for (const row of rows) {
+      existing.add(row.scene_id);
+    }
+  }
 
   return {
     requested: sceneIds,
-    existing: new Set(rows.map(row => row.scene_id)),
+    existing,
   };
 }
 
@@ -129,6 +138,17 @@ export function buildReviewBundlePlan(dbHandle, {
     throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
   }
 
+  if (Array.isArray(scene_ids) && scene_ids.length > MAX_SCENE_ID_FILTER_PARAMS) {
+    throw new ReviewBundlePlanError(
+      "SCENE_IDS_TOO_LARGE",
+      `scene_ids supports at most ${MAX_SCENE_ID_FILTER_PARAMS} entries per request.`,
+      {
+        max_scene_ids: MAX_SCENE_ID_FILTER_PARAMS,
+        received_scene_ids: scene_ids.length,
+      }
+    );
+  }
+
   assertProfile(profile);
   assertStrictness(strictness);
   assertFormat(format);

package/review-bundles-renderer.js

@@ -7,7 +7,7 @@ import { ReviewBundlePlanError, normalizeRecipientDisplayName } from "./review-b
 function escapeMarkdown(text) {
   return String(text ?? "")
     .replace(/\\/g, "\\\\")
-    .replace(/([*_`\[\]#])/g, "\\$1");
+    .replace(/([*_`[\]#])/g, "\\$1");
 }
 
 function renderBetaNoticeMarkdown({ projectId, recipientName }) {

package/scrivener-direct.js

@@ -705,7 +705,7 @@ export function mergeScrivenerProjectMetadata({
       });
     }
 
-    let didRelocate = false;
+    let didRelocate;
 
     if (dryRun) {
       logger(`  DRY   ${filename}`);

package/workflow-catalogue.js

@@ -0,0 +1,95 @@
+export const WORKFLOW_CATALOGUE = [
+  {
+    id: "first_time_setup",
+    label: "First-time setup",
+    use_when: "Connecting to a project for the first time or verifying the runtime is correctly configured.",
+    steps: [
+      { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
+      { tool: "sync", note: "Index scenes from disk." },
+    ],
+  },
+  {
+    id: "styleguide_setup_new",
+    label: "Styleguide setup (new project)",
+    use_when: "No prose styleguide config exists and you want to create one based on the manuscript's existing conventions.",
+    steps: [
+      { tool: "describe_workflows", note: "Check context.scene_count; use that value as max_scenes in the next call." },
+      { tool: "bootstrap_prose_styleguide_config", note: "Detect dominant conventions. Confirm suggestions with the user before applying." },
+      { tool: "setup_prose_styleguide_config", note: "Only if ALL context.styleguide_exists fields are false — a config at any scope is sufficient. Create at project_root scope (requires project_id and language e.g. 'english_us'), or sync_root if no project_id is known." },
+      { tool: "update_prose_styleguide_config", note: "Apply the fields accepted from bootstrap suggestions." },
+    ],
+  },
+  {
+    id: "styleguide_drift_check",
+    label: "Styleguide drift check",
+    use_when: "A styleguide config exists and you want to check whether recent scenes conform to it.",
+    steps: [
+      { tool: "get_prose_styleguide_config", note: "Confirm the currently resolved config." },
+      { tool: "check_prose_styleguide_drift", note: "Detect non-conforming scenes. Pass project_id from context.project_id and set max_scenes from context.scene_count." },
+      { tool: "update_prose_styleguide_config", note: "If drift found and user approves, update config or note the outliers." },
+    ],
+  },
+  {
+    id: "manuscript_exploration",
+    label: "Manuscript exploration",
+    use_when: "Answering questions about the manuscript, finding scenes, or getting an overview.",
+    steps: [
+      { tool: "find_scenes", note: "Filter by character, beat, tag, part, chapter, or POV. No filters returns all scenes." },
+      { tool: "get_scene_prose", note: "Load prose for specific scenes identified by find_scenes." },
+      { tool: "get_chapter_prose", note: "Load all prose for a chapter. Use sparingly — large chapters can overflow context." },
+      { tool: "search_metadata", note: "Full-text search across scene metadata fields." },
+    ],
+  },
+  {
+    id: "prose_editing",
+    label: "Prose editing",
+    use_when: "Revising scene prose. All edits require explicit user confirmation before writing.",
+    steps: [
+      { tool: "find_scenes", note: "Identify the target scene." },
+      { tool: "get_scene_prose", note: "Load the current prose." },
+      { tool: "propose_edit", note: "Stage a revision; returns a diff preview and a proposal_id." },
+      { tool: "commit_edit", note: "Write the revision after the user confirms. Runs preflight checks before writing." },
+      { tool: "discard_edit", note: "Reject the revision if the user does not approve." },
+    ],
+  },
+  {
+    id: "character_management",
+    label: "Character management",
+    use_when: "Finding characters, reading their sheets, or updating character details.",
+    steps: [
+      { tool: "list_characters", note: "Find character_id values." },
+      { tool: "get_character_sheet", note: "Read full character details." },
+      { tool: "create_character_sheet", note: "Create a new character. Requires exactly one of project_id or universe_id." },
+      { tool: "update_character_sheet", note: "Edit character metadata." },
+    ],
+  },
+  {
+    id: "place_management",
+    label: "Place management",
+    use_when: "Finding locations, reading place sheets, or updating place details.",
+    steps: [
+      { tool: "list_places", note: "Find place_id values." },
+      { tool: "get_place_sheet", note: "Read full place details." },
+      { tool: "create_place_sheet", note: "Create a new place. Requires exactly one of project_id or universe_id." },
+      { tool: "update_place_sheet", note: "Edit place metadata." },
+    ],
+  },
+  {
+    id: "review_bundle",
+    label: "Review bundle",
+    use_when: "Preparing a formatted bundle for human review (outline, editorial, or beta read profile).",
+    steps: [
+      { tool: "preview_review_bundle", note: "Check which scenes would be included and the estimated size. Requires project_id and profile." },
+      { tool: "create_review_bundle", note: "Generate the bundle. Requires project_id." },
+    ],
+  },
+  {
+    id: "async_job_tracking",
+    label: "Async job tracking",
+    use_when: "A tool returned a job_id instead of an immediate result (e.g. import_scrivener_sync_async).",
+    steps: [
+      { tool: "get_async_job_status", note: "Poll with the job_id until status is 'completed' or 'failed'." },
+      { tool: "sync", note: "Call after a completed job that modified files on disk." },
+    ],
+  },
+];