@hanna84/mcp-writing 2.18.1 → 3.0.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).
 
+#### [v3.0.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.18.1...v3.0.0)
+
+- feat!: improve MCP tooling usability and harden scene-id safety [`#165`](https://github.com/hannasdev/mcp-writing.git
+/pull/165)
+
 #### [v2.18.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.18.0...v2.18.1)
 
+> 1 May 2026
+
 - docs: finalize reference docs PRD status [`#164`](https://github.com/hannasdev/mcp-writing.git
 /pull/164)
+- Release 2.18.1 [`ed9d0e7`](https://github.com/hannasdev/mcp-writing.git
+/commit/ed9d0e70b6ea17ea22f84d257d71c33d0350fe5f)
 
 #### [v2.18.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.17.1...v2.18.0)

package/README.md

@@ -41,6 +41,47 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 | [docs/tools.md](docs/tools.md) | Full tool reference — auto-generated from source |
 | [docs/development.md](docs/development.md) | Running locally, tests, environment variables, troubleshooting |
 
+## Breaking changes
+
+### `describe_workflows` surface redesign
+
+`describe_workflows` now exposes an outcome-first, discovery-first workflow map. This is a breaking change if your prompts or automation depend on previous workflow IDs or ordering.
+
+Update integrations using this mapping:
+
+- `manuscript_exploration` -> `question_driven_discovery` (or `targeted_scene_reading` when the task is prose inspection)
+- `prose_editing` -> `safe_scene_revision`
+- `character_management` -> `character_understanding`
+- `place_management` -> `place_understanding`
+- `review_bundle` -> `review_preparation`
+
+New workflow IDs added:
+
+- `thread_understanding`
+- `parity_recovery`
+
+Styleguide workflows are still available, but no longer positioned as part of the primary daily workflow surface.
+
+### `find_scenes` and `get_arc` response-shape standardization
+
+`find_scenes` and `get_arc` now always return structured envelopes, including non-paginated calls.
+
+- Envelope fields: `results`, `total_count`.
+- Pagination fields are included when paging is active.
+- `warning` / `next_step` are included when relevant.
+
+If your integration previously handled raw arrays for non-paginated calls, update it to parse envelopes consistently.
+
+Safe parsing pattern:
+
+```js
+const parsed = JSON.parse(toolText);
+const scenes = parsed.results ?? [];
+const totalCount = parsed.total_count ?? scenes.length;
+const warning = parsed.warning ?? null;
+const nextStep = parsed.next_step ?? null;
+```
+
 ## Usage scenarios
 
 ### 1) Continuity pass before sending chapters to beta readers
@@ -99,5 +140,17 @@ Goal: rebuild scene-to-character links in a controlled way after imported prose
 
 Outcome: character-link maintenance becomes a preview-first batch operation instead of a one-off regex script or manual sidecar cleanup.
 
+### 6) Post-upgrade recovery after legacy migration warnings
+
+Goal: recover index confidence quickly when legacy upgrade warnings indicate ambiguous rows were skipped.
+
+1. Start by checking `get_runtime_config` (or `describe_workflows`) and confirm whether `db_migration_warnings` contains `LEGACY_JOIN_ROWS_SKIPPED`.
+2. If present, run `sync` immediately to rebuild scene relationships from current sidecars and prose metadata.
+3. Continue normal discovery (`find_scenes`, `get_arc`, `get_thread_arc`) and watch for stale-metadata warnings.
+4. When you touch stale scenes, run `enrich_scene(scene_id, project_id)` to recover metadata parity incrementally.
+5. If many scenes remain stale, switch to `enrich_scene_characters_batch` (dry-run first) for broader catch-up.
+
+Outcome: upgrade-related data loss risk becomes an explicit, operator-visible recovery workflow instead of a silent state mismatch.
+
 ## License
 AGPL-3.0-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.18.1",
+  "version": "3.0.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/core/db.js

@@ -1,5 +1,36 @@
 import { DatabaseSync } from "node:sqlite";
 
+const dbStartupWarnings = [];
+
+function cloneWarningDetails(details) {
+  if (!details) return details;
+
+  if (typeof structuredClone === "function") {
+    try {
+      return structuredClone(details);
+    } catch {
+      // Fall through to JSON clone for plain data payloads.
+    }
+  }
+
+  try {
+    return JSON.parse(JSON.stringify(details));
+  } catch {
+    return { ...details };
+  }
+}
+
+export function getDbStartupWarnings() {
+  return dbStartupWarnings.map((warning) => ({
+    ...warning,
+    details: cloneWarningDetails(warning.details),
+  }));
+}
+
+function resetDbStartupWarnings() {
+  dbStartupWarnings.length = 0;
+}
+
 export const SCHEMA = `
   CREATE TABLE IF NOT EXISTS universes (
     universe_id TEXT PRIMARY KEY,
@@ -38,27 +69,31 @@ export const SCHEMA = `
 
   CREATE TABLE IF NOT EXISTS scene_characters (
     scene_id     TEXT NOT NULL,
+    project_id   TEXT NOT NULL,
     character_id TEXT NOT NULL,
-    PRIMARY KEY (scene_id, character_id)
+    PRIMARY KEY (scene_id, project_id, character_id)
   );
 
   CREATE TABLE IF NOT EXISTS scene_places (
-    scene_id TEXT NOT NULL,
-    place_id TEXT NOT NULL,
-    PRIMARY KEY (scene_id, place_id)
+    scene_id   TEXT NOT NULL,
+    project_id TEXT NOT NULL,
+    place_id   TEXT NOT NULL,
+    PRIMARY KEY (scene_id, project_id, place_id)
   );
 
   CREATE TABLE IF NOT EXISTS scene_tags (
-    scene_id TEXT NOT NULL,
-    tag      TEXT NOT NULL,
-    PRIMARY KEY (scene_id, tag)
+    scene_id   TEXT NOT NULL,
+    project_id TEXT NOT NULL,
+    tag        TEXT NOT NULL,
+    PRIMARY KEY (scene_id, project_id, tag)
   );
 
   CREATE TABLE IF NOT EXISTS scene_threads (
-    scene_id  TEXT NOT NULL,
-    thread_id TEXT NOT NULL,
-    beat      TEXT,
-    PRIMARY KEY (scene_id, thread_id)
+    scene_id   TEXT NOT NULL,
+    project_id TEXT NOT NULL,
+    thread_id  TEXT NOT NULL,
+    beat       TEXT,
+    PRIMARY KEY (scene_id, project_id, thread_id)
   );
 
   CREATE TABLE IF NOT EXISTS characters (
@@ -160,6 +195,33 @@ export const SCHEMA = `
 // Each migration runs inside a transaction with the version bump — crash-safe.
 // Migrations must be idempotent (guard against already-applied state).
 // Never edit existing entries — add new ones at the end.
+function migrateSceneJoinTableToProjectScope(db, tableName, tableSql, insertSql) {
+  const columns = db.prepare(`PRAGMA table_info(${tableName})`).all();
+  if (columns.some((column) => column.name === "project_id")) {
+    return {
+      migrated: false,
+      sourceCount: 0,
+      migratedCount: 0,
+      droppedCount: 0,
+    };
+  }
+
+  const sourceCount = db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get()?.count ?? 0;
+  db.exec(tableSql);
+  db.exec(insertSql);
+  const migratedCount = db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}_migrating`).get()?.count ?? 0;
+  const droppedCount = Math.max(0, sourceCount - migratedCount);
+  db.exec(`DROP TABLE ${tableName};`);
+  db.exec(`ALTER TABLE ${tableName}_migrating RENAME TO ${tableName};`);
+
+  return {
+    migrated: true,
+    sourceCount,
+    migratedCount,
+    droppedCount,
+  };
+}
+
 const MIGRATIONS = [
   // 1: add chapter_title column to scenes
   (db) => {
@@ -282,6 +344,146 @@ const MIGRATIONS = [
       db.exec(`ALTER TABLE reference_links ADD COLUMN origin TEXT NOT NULL DEFAULT 'inferred';`);
     }
   },
+  // 7: scope scene join tables by project_id so duplicate scene IDs across projects are safe
+  (db) => {
+    const charactersMigration = migrateSceneJoinTableToProjectScope(
+      db,
+      "scene_characters",
+      `
+        CREATE TABLE scene_characters_migrating (
+          scene_id     TEXT NOT NULL,
+          project_id   TEXT NOT NULL,
+          character_id TEXT NOT NULL,
+          PRIMARY KEY (scene_id, project_id, character_id)
+        );
+      `,
+      `
+        INSERT OR IGNORE INTO scene_characters_migrating (scene_id, project_id, character_id)
+        SELECT sc.scene_id, s.project_id, sc.character_id
+        FROM scene_characters sc
+        JOIN scenes s ON s.scene_id = sc.scene_id
+        WHERE (
+          SELECT COUNT(*)
+          FROM scenes sx
+          WHERE sx.scene_id = sc.scene_id
+        ) = 1;
+      `
+    );
+
+    const placesMigration = migrateSceneJoinTableToProjectScope(
+      db,
+      "scene_places",
+      `
+        CREATE TABLE scene_places_migrating (
+          scene_id   TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          place_id   TEXT NOT NULL,
+          PRIMARY KEY (scene_id, project_id, place_id)
+        );
+      `,
+      `
+        INSERT OR IGNORE INTO scene_places_migrating (scene_id, project_id, place_id)
+        SELECT sp.scene_id, s.project_id, sp.place_id
+        FROM scene_places sp
+        JOIN scenes s ON s.scene_id = sp.scene_id
+        WHERE (
+          SELECT COUNT(*)
+          FROM scenes sx
+          WHERE sx.scene_id = sp.scene_id
+        ) = 1;
+      `
+    );
+
+    const tagsMigration = migrateSceneJoinTableToProjectScope(
+      db,
+      "scene_tags",
+      `
+        CREATE TABLE scene_tags_migrating (
+          scene_id   TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          tag        TEXT NOT NULL,
+          PRIMARY KEY (scene_id, project_id, tag)
+        );
+      `,
+      `
+        INSERT OR IGNORE INTO scene_tags_migrating (scene_id, project_id, tag)
+        SELECT st.scene_id, s.project_id, st.tag
+        FROM scene_tags st
+        JOIN scenes s ON s.scene_id = st.scene_id
+        WHERE (
+          SELECT COUNT(*)
+          FROM scenes sx
+          WHERE sx.scene_id = st.scene_id
+        ) = 1;
+      `
+    );
+
+    const threadsMigration = migrateSceneJoinTableToProjectScope(
+      db,
+      "scene_threads",
+      `
+        CREATE TABLE scene_threads_migrating (
+          scene_id   TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          thread_id  TEXT NOT NULL,
+          beat       TEXT,
+          PRIMARY KEY (scene_id, project_id, thread_id)
+        );
+      `,
+      `
+        INSERT OR IGNORE INTO scene_threads_migrating (scene_id, project_id, thread_id, beat)
+        SELECT st.scene_id, t.project_id, st.thread_id, st.beat
+        FROM scene_threads st
+        JOIN threads t ON t.thread_id = st.thread_id
+        JOIN scenes s
+          ON s.scene_id = st.scene_id
+         AND s.project_id = t.project_id;
+
+        INSERT OR IGNORE INTO scene_threads_migrating (scene_id, project_id, thread_id, beat)
+        SELECT st.scene_id, s.project_id, st.thread_id, st.beat
+        FROM scene_threads st
+        JOIN scenes s ON s.scene_id = st.scene_id
+        LEFT JOIN threads t ON t.thread_id = st.thread_id
+        WHERE t.thread_id IS NULL
+          AND (
+            SELECT COUNT(*)
+            FROM scenes sx
+            WHERE sx.scene_id = st.scene_id
+          ) = 1;
+      `
+    );
+
+    const migrationSummaries = [
+      ["scene_characters", charactersMigration],
+      ["scene_places", placesMigration],
+      ["scene_tags", tagsMigration],
+      ["scene_threads", threadsMigration],
+    ];
+    const droppedByTable = {};
+    let totalDropped = 0;
+
+    for (const [tableName, summary] of migrationSummaries) {
+      if (!summary?.migrated || summary.droppedCount <= 0) continue;
+      droppedByTable[tableName] = {
+        source_rows: summary.sourceCount,
+        migrated_rows: summary.migratedCount,
+        skipped_rows: summary.droppedCount,
+      };
+      totalDropped += summary.droppedCount;
+    }
+
+    if (totalDropped > 0) {
+      dbStartupWarnings.push({
+        code: "LEGACY_JOIN_ROWS_SKIPPED",
+        message: "Legacy scene relationship rows were skipped during migration because scene_id was ambiguous across projects or duplicate links could not be preserved safely.",
+        details: {
+          skipped_rows_total: totalDropped,
+          skipped_rows_by_table: droppedByTable,
+          next_step: "Run sync() immediately after upgrade, then run enrich_scene(scene_id, project_id) for any stale scenes you touch.",
+        },
+      });
+    }
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —
@@ -312,6 +514,7 @@ function applyMigrations(db) {
 }
 
 export function openDb(dbPath) {
+  resetDbStartupWarnings();
   const db = new DatabaseSync(dbPath);
   db.exec(SCHEMA);
   applyMigrations(db);

package/src/index.js

@@ -6,7 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { openDb, checkpointJobFinish, loadStalledJobs, pruneJobCheckpoints } from "./core/db.js";
+import { openDb, getDbStartupWarnings, checkpointJobFinish, loadStalledJobs, pruneJobCheckpoints } from "./core/db.js";
 import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, isStructuralProjectId } from "./sync/sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, getSceneProseAtCommit } from "./core/git.js";
 import { createAsyncJobManager, readJsonIfExists } from "./runtime/async-jobs.js";
@@ -134,6 +134,7 @@ function errorResponse(code, message, details) {
 // Database setup
 // ---------------------------------------------------------------------------
 const db = openDb(DB_PATH);
+const DB_STARTUP_WARNINGS = getDbStartupWarnings();
 
 // Recover jobs that were in-flight when the server last exited.
 const stalledJobs = loadStalledJobs(db);
@@ -166,6 +167,12 @@ const { pruneAsyncJobs, startAsyncJob, toPublicJob } = createAsyncJobManager({
 
 process.stderr.write(`[mcp-writing] Sync dir: ${SYNC_DIR_ABS}\n`);
 process.stderr.write(`[mcp-writing] DB path: ${DB_PATH_DISPLAY}\n`);
+if (DB_STARTUP_WARNINGS.length > 0) {
+  process.stderr.write(`[mcp-writing] WARNING: ${DB_STARTUP_WARNINGS.length} DB migration warning(s) detected.\n`);
+  for (const warning of DB_STARTUP_WARNINGS) {
+    process.stderr.write(`[mcp-writing] - ${warning.code}: ${warning.message}\n`);
+  }
+}
 
 // Check sync dir writability once at startup (needed for Phase 2 sidecar writes)
 const SYNC_DIR_WRITABLE = isSyncDirWritable(SYNC_DIR);
@@ -307,7 +314,7 @@ function createMcpServer() {
   // ---- describe_workflows --------------------------------------------------
   s.tool(
     "describe_workflows",
-    "Return a map of available task workflows and the current project context. Call this at the start of a session or whenever you are unsure what to do next. Never write scripts to invoke tools — call them directly.",
+    "Return the default workflow map and current project context for this server. Call this first in most sessions and again whenever you are unsure what to do next. Never write scripts to invoke tools — call them directly.",
     {},
     async () => {
       const projectRow = db.prepare(
@@ -352,14 +359,19 @@ function createMcpServer() {
           },
           git_available: GIT_AVAILABLE,
           pending_proposals: pendingProposals.size,
+          db_migration_warnings: DB_STARTUP_WARNINGS,
         },
         workflows: WORKFLOW_CATALOGUE,
         notes: [
           "Never write JavaScript or shell scripts to invoke tools. Call them directly.",
+          "Use describe_workflows as the default starting point for most sessions and whenever you are uncertain which tool path fits the task.",
           "If a tool returns a next_step field (in a success or error response), follow it before trying anything else.",
           "Use find_scenes without filters to discover what project_ids are indexed.",
           "When calling bootstrap_prose_styleguide_config or check_prose_styleguide_drift, set max_scenes to context.scene_count to avoid the default limit.",
           "Styleguide tools resolve config in priority order: project_root > universe_root > sync_root. If any styleguide_exists field is true, a config exists and styleguide tools will work — do not run setup_prose_styleguide_config unless ALL styleguide_exists fields are false.",
+          ...(DB_STARTUP_WARNINGS.length > 0
+            ? ["Database migration warnings are present in context.db_migration_warnings. Run sync() now, then run enrich_scene(scene_id, project_id) for stale scenes you touch."]
+            : []),
         ],
       });
     }
@@ -416,6 +428,7 @@ function createMcpServer() {
         server_version: MCP_SERVER_VERSION,
         sync_dir: SYNC_DIR_ABS,
         db_path: DB_PATH_DISPLAY,
+        db_migration_warnings: DB_STARTUP_WARNINGS,
         sync_dir_writable: SYNC_DIR_WRITABLE,
         ownership_guard_mode: OWNERSHIP_GUARD_MODE,
         permission_diagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,

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

@@ -160,25 +160,26 @@ export function buildReviewBundlePlan(dbHandle, {
 
   const requestedSceneIds = resolveRequestedSceneIds(dbHandle, project_id, scene_ids);
   const conditions = ["s.project_id = ?"];
-  const params = [project_id];
   const joins = [];
+  const joinParams = [];
+  const conditionParams = [project_id];
 
   if (tag) {
-    joins.push("JOIN scene_tags st ON st.scene_id = s.scene_id AND st.tag = ?");
-    params.push(tag);
+    joins.push("JOIN scene_tags st ON st.scene_id = s.scene_id AND st.project_id = s.project_id AND st.tag = ?");
+    joinParams.push(tag);
   }
   if (Array.isArray(scene_ids) && scene_ids.length > 0) {
     const placeholders = scene_ids.map(() => "?").join(",");
     conditions.push(`s.scene_id IN (${placeholders})`);
-    params.push(...scene_ids);
+    conditionParams.push(...scene_ids);
   }
   if (part !== undefined) {
     conditions.push("s.part = ?");
-    params.push(part);
+    conditionParams.push(part);
   }
   if (chapter !== undefined) {
     conditions.push("s.chapter = ?");
-    params.push(chapter);
+    conditionParams.push(chapter);
   }
 
   let query = `
@@ -202,7 +203,7 @@ export function buildReviewBundlePlan(dbHandle, {
   }
   query += ` WHERE ${conditions.join(" AND ")}`;
 
-  const rows = dbHandle.prepare(query).all(...params).sort(sceneSort);
+  const rows = dbHandle.prepare(query).all(...joinParams, ...conditionParams).sort(sceneSort);
   if (rows.length === 0) {
     throw new ReviewBundlePlanError(
       "NO_RESULTS",

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

@@ -442,7 +442,7 @@ export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: sy
           doc.moveDown(0.2);
         }
 
-        if (scene.logline) {
+        if (profile === "outline_discussion" && scene.logline) {
           doc.fontSize(10).font("Helvetica-Oblique");
           const textWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
           doc.text(`"${scene.logline}"`, { align: "left", width: textWidth });

package/src/scripts/manual/README.md

@@ -0,0 +1,27 @@
+# Manual Script Conventions
+
+Manual scripts under this folder should use `mcp-result.mjs` for MCP tool parsing.
+
+## Use the shared parser
+
+Import and call:
+
+```js
+import { callToolParsed } from "./mcp-result.mjs";
+
+const result = await callToolParsed(client, "get_scene_prose", { scene_id: "sc-001" });
+```
+
+`callToolParsed(...)` returns:
+
+- `raw`: original MCP response object
+- `text`: `raw.content?.[0]?.text ?? ""`
+- `data`: parsed JSON object when `text` is valid JSON, otherwise `null`
+- `structured`: `raw.structuredContent` (if present)
+- `isError`: `true` when `raw.isError` is set or parsed `data.ok === false`
+
+## Why this is required
+
+Some tools now return advisory metadata in `structuredContent` (for example stale-metadata guidance on prose tools). Scripts that only read `content[0].text` can silently lose those warnings.
+
+Using `callToolParsed` keeps text, JSON payloads, and structured metadata handled consistently across all manual scripts.

package/src/scripts/manual/mcp-result.mjs

@@ -0,0 +1,27 @@
+export function parseToolResult(result) {
+  const text = result?.content?.[0]?.text ?? "";
+  let data = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = null;
+    }
+  }
+
+  return {
+    raw: result,
+    text,
+    data,
+    structured: result?.structuredContent,
+    isError: Boolean(
+      result?.isError
+      || (data && typeof data === "object" && data.ok === false)
+    ),
+  };
+}
+
+export async function callToolParsed(client, name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  return parseToolResult(result);
+}

package/src/scripts/manual/run_create_review_bundle.js

@@ -3,6 +3,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import path from "path";
 import process from "process";
 import fs from "node:fs";
+import { callToolParsed } from "./mcp-result.mjs";
 
 async function main() {
   const [projectId, profile, outputDir, ...flags] = process.argv.slice(2);
@@ -64,29 +65,29 @@ async function main() {
     await client.connect(transport);
 
     if (!skipPreview) {
-      const previewResult = await client.callTool({
-        name: "preview_review_bundle",
-        arguments: baseArguments,
-      });
-      const previewText = previewResult.content?.[0]?.text ?? "";
+      const previewResult = await callToolParsed(client, "preview_review_bundle", baseArguments);
+      const previewText = previewResult.text;
       console.log("\n=== preview_review_bundle ===");
       console.log(previewText);
+      if (previewResult.structured) {
+        console.log("structuredContent:", JSON.stringify(previewResult.structured, null, 2));
+      }
     }
 
-    const result = await client.callTool({
-      name: "create_review_bundle",
-      arguments: {
-        ...baseArguments,
-        output_dir: outputDir,
-      }
+    const result = await callToolParsed(client, "create_review_bundle", {
+      ...baseArguments,
+      output_dir: outputDir,
     });
 
-    const resultText = result.content?.[0]?.text ?? "";
+    const resultText = result.text;
     console.log("\n=== create_review_bundle ===");
     console.log(resultText);
+    if (result.structured) {
+      console.log("structuredContent:", JSON.stringify(result.structured, null, 2));
+    }
 
     if (showFiles) {
-      const parsed = JSON.parse(resultText);
+      const parsed = result.data ?? {};
       if (parsed.ok && parsed.output_paths) {
         printArtifactExcerpt("Bundle Markdown", parsed.output_paths.bundle_markdown);
         printArtifactExcerpt("Manifest JSON", parsed.output_paths.manifest_json);

package/src/scripts/manual/run_mcp_and_review.js

@@ -2,13 +2,11 @@ import path from "node:path";
 import process from "node:process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { callToolParsed } from "./mcp-result.mjs";
 
 async function callCreateBundle(client, args) {
-  const result = await client.callTool({
-    name: "create_review_bundle",
-    arguments: args,
-  });
-  console.log(JSON.stringify(result, null, 2));
+  const parsed = await callToolParsed(client, "create_review_bundle", args);
+  console.log(JSON.stringify(parsed.raw, null, 2));
 }
 
 async function main() {

package/src/scripts/manual/run_mcp_test.js

@@ -2,6 +2,7 @@ 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 { callToolParsed } from "./mcp-result.mjs";
 
 function usage() {
   console.log("Usage: node src/scripts/manual/run_mcp_test.js <source_project_dir> [project_id] [sync_dir]");
@@ -30,17 +31,18 @@ async function runCase(env, args) {
     await client.connect(transport);
     
     // Start the async merge job
-    const startResult = await client.callTool({
-      name: "merge_scrivener_project_beta",
-      arguments: args
-    });
+    const startResult = await callToolParsed(client, "merge_scrivener_project_beta", args);
 
     if (startResult.isError) {
-      console.log(`error: ${startResult.content[0].text}`);
+      console.log(`error: ${startResult.text}`);
       return;
     }
 
-    const startData = JSON.parse(startResult.content[0].text);
+    const startData = startResult.data;
+    if (!startData) {
+      console.log("error: invalid start payload");
+      return;
+    }
     if (!startData.ok) {
       console.log(`error: ${startData.error?.code || 'unknown'}`);
       return;
@@ -57,22 +59,20 @@ async function runCase(env, args) {
     while (!settled && attempts < maxAttempts) {
       await new Promise(resolve => setTimeout(resolve, 500));
       
-      const statusResult = await client.callTool({
-        name: "get_async_job_status",
-        arguments: { job_id: jobId, include_result: true }
+      const statusResult = await callToolParsed(client, "get_async_job_status", {
+        job_id: jobId,
+        include_result: true,
       });
 
       if (statusResult.isError) {
-        console.log(`error.code/message: ${statusResult.content?.[0]?.text || "status query failed"}`);
+        console.log(`error.code/message: ${statusResult.text || "status query failed"}`);
         settled = true;
         break;
       }
 
-      let statusData;
-      try {
-        statusData = JSON.parse(statusResult.content[0].text);
-      } catch (parseError) {
-        console.log(`error.code/message: invalid status payload: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+      const statusData = statusResult.data;
+      if (!statusData) {
+        console.log("error.code/message: invalid status payload");
         settled = true;
         break;
       }