@hanna84/mcp-writing 1.11.5 → 1.11.7

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).
 
+#### [v1.11.7](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.6...v1.11.7)
+
+- refactor: consolidate merge_scrivener_project_beta to async-only [`#66`](https://github.com/hannasdev/mcp-writing.git
+/pull/66)
+
+#### [v1.11.6](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.5...v1.11.6)
+
+> 24 April 2026
+
+- fix: improve MCP discoverability hints and tool guidance [`#65`](https://github.com/hannasdev/mcp-writing.git
+/pull/65)
+- Release 1.11.6 [`fa60a4a`](https://github.com/hannasdev/mcp-writing.git
+/commit/fa60a4a91e2043f094a2f404f742e7d6b18e006e)
+
 #### [v1.11.5](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.11.4...v1.11.5)
 
+> 24 April 2026
+
 - Add Copilot instructions and contribution workflow [`#64`](https://github.com/hannasdev/mcp-writing.git
 /pull/64)
+- Release 1.11.5 [`9b72b8b`](https://github.com/hannasdev/mcp-writing.git
+/commit/9b72b8b827ccc7b9ab7532fbb355ab5894b56a59)
 
 #### [v1.11.4](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.11.3...v1.11.4)

package/index.js

@@ -16,7 +16,6 @@ import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDi
 import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
-import { mergeScrivenerProjectMetadata } from "./scrivener-direct.js";
 import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
@@ -894,124 +893,6 @@ function createMcpServer() {
     }
   );
 
-  // ---- merge_scrivener_project_beta --------------------------------------
-  s.tool(
-    "merge_scrivener_project_beta",
-    "[BETA] Merge metadata directly from a Scrivener .scriv project into existing scene sidecars. This path is opt-in, requires sidecars to already exist (for example, from import_scrivener_sync), and may be sensitive to Scrivener internal format changes.",
-    {
-      source_project_dir: z.string().describe("Path to a Scrivener .scriv bundle directory."),
-      project_id: z.string().optional().describe("Project ID containing existing sidecars (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb'). Defaults to a slug derived from WRITING_SYNC_DIR."),
-      scenes_dir: z.string().optional().describe("Absolute path to the scenes directory containing .meta.yaml sidecars. Overrides the path derived from project_id. Use this for non-standard sync layouts."),
-      dry_run: z.boolean().optional().describe("If true (default), reports planned merges without writing files."),
-      auto_sync: z.boolean().optional().describe("If true (default), runs sync() after a non-dry-run merge."),
-      organize_by_chapters: z.boolean().optional().describe("If true (default false), relocate scene files into chapter-based folder hierarchies (e.g., chapter-7-harbor/). Chapter metadata is always extracted to sidecars regardless of this flag."),
-    },
-    async ({ source_project_dir, project_id, scenes_dir, dry_run = true, auto_sync = true, organize_by_chapters = false }) => {
-      if (project_id !== undefined) {
-        const projectIdCheck = validateProjectId(project_id);
-        if (!projectIdCheck.ok) {
-          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
-        }
-      }
-
-      if (!dry_run && !SYNC_DIR_WRITABLE) {
-        return errorResponse(
-          "SYNC_DIR_NOT_WRITABLE",
-          "Cannot merge Scrivener metadata because WRITING_SYNC_DIR is not writable in this runtime.",
-          { sync_dir: SYNC_DIR_ABS }
-        );
-      }
-
-      const resolvedScenesDir = scenes_dir
-        ?? (project_id ? path.join(resolveProjectRoot(project_id), "scenes") : undefined);
-      const normalizedScenesDir = resolvedScenesDir ? path.resolve(resolvedScenesDir) : undefined;
-
-      if (normalizedScenesDir) {
-        if (!isPathInsideSyncDir(normalizedScenesDir)) {
-          return errorResponse(
-            "INVALID_SCENES_DIR",
-            "scenes_dir must be inside WRITING_SYNC_DIR.",
-            { scenes_dir: normalizedScenesDir, sync_dir: SYNC_DIR_ABS, sync_dir_real: SYNC_DIR_REAL }
-          );
-        }
-      }
-
-      let mergeResult;
-      try {
-        mergeResult = mergeScrivenerProjectMetadata({
-          scrivPath: source_project_dir,
-          mcpSyncDir: SYNC_DIR,
-          projectId: project_id,
-          scenesDir: normalizedScenesDir,
-          dryRun: Boolean(dry_run),
-          organizeByChapters: Boolean(organize_by_chapters),
-        });
-      } catch (error) {
-        return errorResponse(
-          "SCRIVENER_DIRECT_BETA_FAILED",
-          error instanceof Error ? error.message : "Scrivener direct beta merge failed.",
-          {
-            source_project_dir,
-            sync_dir: SYNC_DIR_ABS,
-            project_id: project_id ?? null,
-            fallback: "Use import_scrivener_sync with a Scrivener External Folder Sync export as the stable default path.",
-          }
-        );
-      }
-
-      let syncResult = null;
-      if (!dry_run && auto_sync) {
-        syncResult = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
-      }
-
-      return jsonResponse({
-        ok: true,
-        beta: true,
-        merge: {
-          source_project_dir: mergeResult.scrivPath,
-          sync_dir: mergeResult.mcpSyncDir,
-          scenes_dir: mergeResult.scenesDir,
-          project_id: mergeResult.projectId,
-          dry_run: mergeResult.dryRun,
-          sidecar_files: mergeResult.sidecarFiles,
-          updated: mergeResult.updated,
-          relocated: mergeResult.relocated,
-          unchanged: mergeResult.unchanged,
-          no_data: mergeResult.noData,
-          field_add_counts: mergeResult.fieldAddCounts,
-          preview_changes: mergeResult.previewChanges,
-          warnings: mergeResult.warnings,
-          warnings_truncated: mergeResult.warningsTruncated,
-          warning_summary: mergeResult.warningSummary,
-          stats: {
-            sync_map_entries: mergeResult.stats.syncMapEntries,
-            keyword_map_entries: mergeResult.stats.keywordMapEntries,
-            binder_items: mergeResult.stats.binderItems,
-            part_chapter_assignments: mergeResult.stats.partChapterAssignments,
-          },
-        },
-        sync: syncResult
-          ? {
-            indexed: syncResult.indexed,
-            stale_marked: syncResult.staleMarked,
-            sidecars_migrated: syncResult.sidecarsMigrated,
-            skipped: syncResult.skipped,
-            warning_summary: syncResult.warningSummary,
-          }
-          : null,
-        next_step: dry_run
-          ? "Dry run complete. Re-run with dry_run=false to write metadata merges."
-          : auto_sync
-            ? "Beta merge and sync complete."
-            : "Beta merge complete. Run sync() to refresh index.",
-        warnings: [
-          "BETA_FEATURE: Direct Scrivener project parsing may be sensitive to Scrivener internal format changes.",
-          "If this fails, use import_scrivener_sync with an External Folder Sync export as the stable fallback.",
-        ],
-      });
-    }
-  );
-
   // ---- async import/merge jobs --------------------------------------------
   s.tool(
     "import_scrivener_sync_async",
@@ -1094,8 +975,8 @@ function createMcpServer() {
   );
 
   s.tool(
-    "merge_scrivener_project_beta_async",
-    "[BETA] Start an asynchronous Scrivener metadata merge job from a `.scriv` project into existing scene sidecars. Use this only after the stable import path has created sidecars. Returns immediately with a job_id to poll via get_async_job_status.",
+    "merge_scrivener_project_beta",
+    "[BETA] Merge metadata directly from a Scrivener .scriv project into existing scene sidecars by starting a background job. This path is opt-in, requires sidecars to already exist (for example, from import_scrivener_sync), and may be sensitive to Scrivener internal format changes. Returns immediately with a job_id to poll via get_async_job_status.",
     {
       source_project_dir: z.string().describe("Path to a Scrivener .scriv bundle directory."),
       project_id: z.string().optional().describe("Project ID containing existing sidecars (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
@@ -1296,7 +1177,7 @@ function createMcpServer() {
 
   s.tool(
     "get_async_job_status",
-    "Get status and result for an asynchronous job started by async tools such as import_scrivener_sync_async, merge_scrivener_project_beta_async, or enrich_scene_characters_batch.",
+    "Get status and result for an asynchronous job started by async tools such as import_scrivener_sync_async, merge_scrivener_project_beta, or enrich_scene_characters_batch. Use this to poll job progress after receiving a job_id. Common next step: if status is still running, call this tool again; if status is completed inspect result, and if status is failed or cancelled inspect job/result diagnostics.",
     {
       job_id: z.string().describe("Job ID returned by an async start tool."),
       include_result: z.boolean().optional().describe("If true (default), includes completed result payload when available."),
@@ -1305,7 +1186,7 @@ function createMcpServer() {
       pruneAsyncJobs();
       const job = asyncJobs.get(job_id);
       if (!job) {
-        return errorResponse("NOT_FOUND", `Async job '${job_id}' was not found. It may have expired.`);
+        return errorResponse("NOT_FOUND", `Async job '${job_id}' was not found. It may have expired. Hint: call list_async_jobs to see currently tracked job IDs.`);
       }
       return jsonResponse({ ok: true, async: true, job: toPublicJob(job, include_result) });
     }
@@ -1313,7 +1194,7 @@ function createMcpServer() {
 
   s.tool(
     "list_async_jobs",
-    "List asynchronous jobs currently known to this server.",
+    "List asynchronous jobs currently known to this server. Use this when you lost a job_id or need a dashboard view of running/completed jobs. Returns an object envelope containing a jobs array of job objects sorted by newest first.",
     {
       include_results: z.boolean().optional().describe("If true, includes completed result payloads."),
     },
@@ -1328,7 +1209,7 @@ function createMcpServer() {
 
   s.tool(
     "cancel_async_job",
-    "Cancel a running asynchronous job.",
+    "Cancel a running asynchronous job. Use this when an import/merge/batch run was started with overly broad scope or is no longer needed. Returns the updated job state; cancellation is cooperative and may transition through 'cancelling' before 'cancelled'.",
     {
       job_id: z.string().describe("Job ID returned by an async start tool."),
     },
@@ -1336,7 +1217,7 @@ function createMcpServer() {
       pruneAsyncJobs();
       const job = asyncJobs.get(job_id);
       if (!job) {
-        return errorResponse("NOT_FOUND", `Async job '${job_id}' was not found. It may have expired.`);
+        return errorResponse("NOT_FOUND", `Async job '${job_id}' was not found. It may have expired. Hint: call list_async_jobs to find active IDs.`);
       }
 
       if (job.status !== "running") {
@@ -1461,7 +1342,7 @@ function createMcpServer() {
 
       const rows = db.prepare(query).all(...params);
       if (rows.length === 0) {
-        return errorResponse("NO_RESULTS", "No scenes match the given filters.");
+        return errorResponse("NO_RESULTS", "No scenes match the given filters. Hint: broaden filters or call search_metadata with a keyword first.");
       }
 
       const staleCount = rows.filter(r => r.metadata_stale).length;
@@ -1909,7 +1790,7 @@ function createMcpServer() {
   // ---- list_threads --------------------------------------------------------
   s.tool(
     "list_threads",
-    "List all subplot/storyline threads for a project. Returns a structured JSON envelope with results and total_count. Supports pagination via page/page_size.",
+    "List all subplot/storyline threads for a project. Returns a structured JSON envelope with results and total_count. Use this to discover valid thread_id values before calling get_thread_arc or upsert_thread_link. Supports pagination via page/page_size.",
     {
       project_id: z.string().describe("Project ID."),
       page: z.number().int().min(1).optional().describe("Optional page number for paginated responses (1-based)."),
@@ -1937,7 +1818,7 @@ function createMcpServer() {
   // ---- get_thread_arc ------------------------------------------------------
   s.tool(
     "get_thread_arc",
-    "Get ordered scene metadata for all scenes belonging to a thread, including the per-thread beat. Returns a structured JSON envelope with thread metadata, results, and total_count. Supports pagination via page/page_size.",
+    "Get ordered scene metadata for all scenes belonging to a thread, including the per-thread beat. Returns a structured JSON envelope with thread metadata, results, and total_count. Use list_threads first to find a valid thread_id, then call get_scene_prose for close reading of specific scenes. Supports pagination via page/page_size.",
     {
       thread_id: z.string().describe("Thread ID."),
       page: z.number().int().min(1).optional().describe("Optional page number for paginated responses (1-based)."),
@@ -1946,7 +1827,7 @@ function createMcpServer() {
     async ({ thread_id, page, page_size }) => {
       const thread = db.prepare(`SELECT * FROM threads WHERE thread_id = ?`).get(thread_id);
       if (!thread) {
-        return errorResponse("NOT_FOUND", `Thread '${thread_id}' not found.`);
+        return errorResponse("NOT_FOUND", `Thread '${thread_id}' not found. Hint: call list_threads with project_id to get valid thread IDs.`);
       }
 
       const rows = db.prepare(`
@@ -2326,7 +2207,7 @@ function createMcpServer() {
 
       const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
       if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Hint: call find_scenes to get valid scene IDs.`);
       }
 
       try {
@@ -2397,7 +2278,7 @@ function createMcpServer() {
 
       const proposal = pendingProposals.get(proposal_id);
       if (!proposal) {
-        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has expired.`);
+        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has expired. Hint: call propose_edit again to create a fresh proposal_id.`);
       }
 
       if (proposal.scene_id !== scene_id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.11.5",
+  "version": "1.11.7",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -25,6 +25,9 @@
     "start": "node --experimental-sqlite index.js",
     "new:entity": "node scripts/new-world-entity.js",
     "manual:realtest": "node scripts/manual-scrivener-realtest.mjs",
+    "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",
     "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/scripts/async-job-runner.mjs

@@ -164,15 +164,34 @@ try {
   await main();
 } catch (error) {
   const resultPath = process.argv[3];
+  const requestPath = process.argv[2];
   if (resultPath) {
-    const errorCode = error && typeof error === "object" && typeof error.code === "string"
+    const baseErrorCode = error && typeof error === "object" && typeof error.code === "string"
       ? error.code
       : "ASYNC_JOB_FAILED";
-    const errorDetails = error && typeof error === "object"
-      ? {
-        ...(error.pattern ? { pattern: error.pattern } : {}),
+    let requestKind = null;
+    if (requestPath && fs.existsSync(requestPath)) {
+      try {
+        const request = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+        requestKind = request?.kind ?? null;
+      } catch {
+        requestKind = null;
       }
-      : {};
+    }
+
+    const errorCode = requestKind === "merge_scrivener_project_beta" && baseErrorCode === "ASYNC_JOB_FAILED"
+      ? "SCRIVENER_DIRECT_BETA_FAILED"
+      : baseErrorCode;
+
+    const errorDetails = {
+      ...(error && typeof error === "object" && error.pattern ? { pattern: error.pattern } : {}),
+      ...(error && typeof error === "object" && error.details && typeof error.details === "object" ? error.details : {}),
+      ...(requestKind === "merge_scrivener_project_beta"
+        ? {
+          fallback: "Use import_scrivener_sync with an External Folder Sync export as the stable default path.",
+        }
+        : {}),
+    };
     writeResult(resultPath, {
       ok: false,
       error: {

package/scripts/manual/run_mcp_test.js

@@ -0,0 +1,135 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import path from "path";
+import process from "process";
+
+function usage() {
+  console.log("Usage: node scripts/manual/run_mcp_test.js <source_project_dir> [project_id] [sync_dir]");
+  console.log("Example: node scripts/manual/run_mcp_test.js ~/Novel.scriv demo-project ~/sync-root");
+}
+
+async function runCase(env, args) {
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: ["--experimental-sqlite", path.join(process.cwd(), "index.js")],
+    env: {
+      ...process.env,
+      MCP_TRANSPORT: "stdio",
+      ...env,
+    }
+  });
+
+  const client = new Client({
+    name: "test-client",
+    version: "1.0.0"
+  }, {
+    capabilities: {}
+  });
+
+  try {
+    await client.connect(transport);
+    
+    // Start the async merge job
+    const startResult = await client.callTool({
+      name: "merge_scrivener_project_beta",
+      arguments: args
+    });
+
+    if (startResult.isError) {
+      console.log(`error: ${startResult.content[0].text}`);
+      return;
+    }
+
+    const startData = JSON.parse(startResult.content[0].text);
+    if (!startData.ok) {
+      console.log(`error: ${startData.error?.code || 'unknown'}`);
+      return;
+    }
+
+    const jobId = startData.job.job_id;
+    console.log(`Job started: ${jobId}`);
+
+    // Poll for completion (with timeout)
+    let settled = false;
+    let attempts = 0;
+    const maxAttempts = 120; // 120 * 500ms = 60 seconds
+
+    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 }
+      });
+
+      if (statusResult.isError) {
+        console.log(`error.code/message: ${statusResult.content?.[0]?.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)}`);
+        settled = true;
+        break;
+      }
+
+      if (!statusData.ok) {
+        console.log(`error.code/message: ${statusData.error?.code || "unknown"}`);
+        settled = true;
+      }
+
+      const terminalStatuses = new Set(["completed", "failed", "cancelled"]);
+      if (!settled && terminalStatuses.has(statusData.job?.status)) {
+        settled = true;
+      }
+
+      if (statusData.job?.status === "completed") {
+        const result = statusData.job.result;
+
+        if (!result.ok) {
+          console.log(`error.code/message: ${result.error?.code}`);
+        } else {
+          const merge = result.merge || {};
+          console.log("ok");
+          if (merge.sidecar_files) console.log(`sidecar_files: ${merge.sidecar_files}`);
+          if (merge.updated) console.log(`updated: ${merge.updated}`);
+        }
+      }
+
+      if (statusData.job?.status === "failed" || statusData.job?.status === "cancelled") {
+        const details = statusData.job?.result?.error?.code || statusData.job?.status;
+        console.log(`error.code/message: ${details}`);
+      }
+      
+      attempts++;
+    }
+
+    if (!settled) {
+      console.log("error: job timeout");
+    }
+  } catch (e) {
+    console.log(`error.code/message: ${e.message}`);
+  }
+}
+
+async function main() {
+  const [sourceProjectDir, projectId = "demo-project", syncDir = process.env.WRITING_SYNC_DIR || "./sync"] = process.argv.slice(2);
+  if (!sourceProjectDir) {
+    usage();
+    process.exit(1);
+  }
+
+  await runCase({ WRITING_SYNC_DIR: syncDir }, {
+    source_project_dir: sourceProjectDir,
+    project_id: projectId,
+    dry_run: true,
+  });
+  
+  process.exit(0);
+}
+
+main();

package/scripts/manual/test-scenarios.mjs

@@ -0,0 +1,304 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+
+const BASE_URL = "http://localhost:3000";
+
+async function connect() {
+  // Wait for server to be ready
+  for (let i = 0; i < 30; i++) {
+    try {
+      const res = await fetch(`${BASE_URL}/sse`);
+      if (!res.ok && res.status !== 404) continue; // Still waiting
+      break;
+    } catch {
+      await new Promise(r => setTimeout(r, 200));
+    }
+  }
+
+  const client = new Client({ name: "test-scenarios", version: "1.0.0" });
+  const transport = new SSEClientTransport(new URL(`${BASE_URL}/sse`));
+  await client.connect(transport);
+  return client;
+}
+
+async function callTool(client, name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  return result.content?.[0]?.text ?? "";
+}
+
+const results = [];
+
+function log(scenario, status, details) {
+  results.push({ scenario, status, details });
+  console.log(`\n${scenario}: ${status}`);
+  if (details) console.log(`  ${details}`);
+}
+
+async function runScenarios() {
+  const client = await connect();
+
+  try {
+    // ========================================================================
+    // 1. Baseline list without pagination args (find_scenes)
+    // ========================================================================
+    console.log("\n=== Scenario 1: Baseline find_scenes (no pagination) ===");
+    try {
+      const text = await callTool(client, "find_scenes", { project_id: "the-lamb" });
+      const parsed = JSON.parse(text);
+      const isArray = Array.isArray(parsed);
+      const isEnvelope = !isArray && parsed.results && parsed.total_count !== undefined;
+      
+      if (isArray) {
+        log("1a", "PASS", `Got array of ${parsed.length} scenes (backward compat)`);
+      } else if (isEnvelope) {
+        log("1b", "PASS", `Got envelope with results: ${parsed.results.length}, total_count: ${parsed.total_count}`);
+      } else {
+        log("1c", "FAIL", `Unknown shape: ${JSON.stringify(parsed).slice(0, 100)}`);
+      }
+    } catch (err) {
+      log("1", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 2. Explicit pagination on find_scenes
+    // ========================================================================
+    console.log("\n=== Scenario 2: find_scenes with explicit pagination ===");
+    try {
+      const page1 = JSON.parse(await callTool(client, "find_scenes", { project_id: "the-lamb", page_size: 5, page: 1 }));
+      const page2 = JSON.parse(await callTool(client, "find_scenes", { project_id: "the-lamb", page_size: 5, page: 2 }));
+      
+      const p1Ids = page1.results.map(s => s.scene_id);
+      const p2Ids = page2.results.map(s => s.scene_id);
+      const overlap = p1Ids.filter(id => p2Ids.includes(id));
+      
+      if (page1.total_count === page2.total_count && overlap.length === 0) {
+        log("2", "PASS", `Page 1 (${p1Ids.length}), Page 2 (${p2Ids.length}), total_count: ${page1.total_count}, no overlap`);
+      } else {
+        log("2", "FAIL", `Overlap: ${overlap.length}, totals: ${page1.total_count} vs ${page2.total_count}`);
+      }
+    } catch (err) {
+      log("2", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 3. Explicit pagination on get_arc
+    // ========================================================================
+    console.log("\n=== Scenario 3: get_arc with explicit pagination ===");
+    try {
+      const arc1 = JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom", page_size: 3, page: 1 }));
+      const arc2 = JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom", page_size: 3, page: 2 }));
+      
+      const sumLen = arc1.results.length + arc2.results.length;
+      const check = arc1.total_count >= sumLen && arc1.results[0].part === 1;
+      
+      if (check) {
+        log("3", "PASS", `Page 1 (${arc1.results.length}), Page 2 (${arc2.results.length}), total: ${arc1.total_count}, ordered by part`);
+      } else {
+        log("3", "FAIL", `total_count: ${arc1.total_count}, page sum: ${sumLen}`);
+      }
+    } catch (err) {
+      log("3", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 4. Explicit pagination on search_metadata
+    // ========================================================================
+    console.log("\n=== Scenario 4: search_metadata with pagination ===");
+    try {
+      const s1 = JSON.parse(await callTool(client, "search_metadata", { query: "scene", page_size: 2, page: 1 }));
+      const s2 = JSON.parse(await callTool(client, "search_metadata", { query: "scene", page_size: 2, page: 2 }));
+      
+      if (s1.total_count > s1.results.length && s1.page === 1 && s2.page === 2) {
+        log("4", "PASS", `Page 1 (${s1.results.length}), Page 2 (${s2.results.length}), total: ${s1.total_count}`);
+      } else {
+        log("4", "FAIL", `Page meta inconsistency: ${JSON.stringify({ p1: s1.page, p2: s2.page, total: s1.total_count })}`);
+      }
+    } catch (err) {
+      log("4", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 5. list_threads empty project case
+    // ========================================================================
+    console.log("\n=== Scenario 5: list_threads on empty project ===");
+    try {
+      const text = await callTool(client, "list_threads", { project_id: "the-lamb" });
+      const parsed = JSON.parse(text);
+      
+      if (parsed.project_id === "the-lamb" && parsed.total_count === 0 && Array.isArray(parsed.results)) {
+        log("5", "PASS", `Structured JSON: project_id, results [], total_count: 0`);
+      } else {
+        log("5", "FAIL", `Missing fields or wrong structure: ${JSON.stringify(parsed).slice(0, 100)}`);
+      }
+    } catch (err) {
+      log("5", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 6. list_threads non-empty project (if any exist)
+    // ========================================================================
+    console.log("\n=== Scenario 6: list_threads non-empty (test-novel) ===");
+    try {
+      const text = await callTool(client, "list_threads", { project_id: "test-novel" });
+      const parsed = JSON.parse(text);
+      
+      const threadCount = parsed.results.length;
+      const matchesTotal = threadCount === parsed.total_count;
+      
+      if (matchesTotal && parsed.project_id === "test-novel") {
+        log("6", "PASS", `${threadCount} threads, total_count: ${parsed.total_count}`);
+      } else {
+        log("6", "FAIL", `results vs total mismatch: ${threadCount} vs ${parsed.total_count}`);
+      }
+    } catch (err) {
+      log("6", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 7. get_thread_arc happy path (we may not have threads, check structure)
+    // ========================================================================
+    console.log("\n=== Scenario 7: get_thread_arc structure check ===");
+    try {
+      // Try to get any thread first
+      const threadList = JSON.parse(await callTool(client, "list_threads", { project_id: "test-novel" }));
+      if (threadList.results.length === 0) {
+        log("7", "SKIP", "No threads in test-novel, skipping");
+      } else {
+        const threadId = threadList.results[0].thread_id;
+        const arcText = await callTool(client, "get_thread_arc", { thread_id: threadId });
+        const parsed = JSON.parse(arcText);
+        
+        if (parsed.thread && parsed.results && parsed.total_count !== undefined) {
+          log("7", "PASS", `Envelope with thread name: "${parsed.thread.name}", results: ${parsed.results.length}`);
+        } else {
+          log("7", "FAIL", `Missing envelope fields: ${JSON.stringify(Object.keys(parsed))}`);
+        }
+      }
+    } catch (err) {
+      log("7", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 8. get_thread_arc unknown thread
+    // ========================================================================
+    console.log("\n=== Scenario 8: get_thread_arc with fake thread_id ===");
+    try {
+      const text = await callTool(client, "get_thread_arc", { thread_id: "fake-thread-999" });
+      // Currently expects text error message
+      if (text.toLowerCase().includes("not found")) {
+        log("8", "PASS", `Error handling works: "${text.slice(0, 50)}..."`);
+      } else {
+        log("8", "WARN", `Unexpected response: "${text.slice(0, 80)}..."`);
+      }
+    } catch (err) {
+      log("8", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 9. Warning behavior (scenes with stale metadata)
+    // ========================================================================
+    console.log("\n=== Scenario 9: Warning on stale metadata ===");
+    try {
+      const text = await callTool(client, "get_arc", { character_id: "char-mira-nystrom" });
+      const parsed = JSON.parse(text);
+      
+      const hasStaleScenes = parsed.results.some(s => s.metadata_stale);
+      const hasWarning = parsed.warning !== undefined;
+      
+      if (hasStaleScenes && hasWarning) {
+        log("9", "PASS", `Stale scenes detected: ${hasStaleScenes}, warning included: "${parsed.warning.slice(0, 60)}..."`);
+      } else if (!hasStaleScenes) {
+        log("9", "SKIP", "No stale scenes in test data");
+      } else {
+        log("9", "FAIL", `Stale scenes found but no warning`);
+      }
+    } catch (err) {
+      log("9", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 10. Page bounds behavior (page far beyond total_pages)
+    // ========================================================================
+    console.log("\n=== Scenario 10: Page bounds (page beyond range) ===");
+    try {
+      const resp = JSON.parse(await callTool(client, "find_scenes", { project_id: "the-lamb", page_size: 5, page: 9999 }));
+      
+      if (resp.page <= resp.total_pages && !isNaN(resp.page)) {
+        log("10", "PASS", `Page normalized to ${resp.page} of ${resp.total_pages}`);
+      } else {
+        log("10", "FAIL", `Page not normalized: ${resp.page} > ${resp.total_pages}`);
+      }
+    } catch (err) {
+      log("10", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 11. Cross-tool shape consistency
+    // ========================================================================
+    console.log("\n=== Scenario 11: Cross-tool shape consistency ===");
+    try {
+      const fs = JSON.parse(await callTool(client, "find_scenes", { project_id: "the-lamb", page_size: 1 }));
+      const ga = JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom", page_size: 1 }));
+      const sm = JSON.parse(await callTool(client, "search_metadata", { query: "scene", page_size: 1 }));
+      const lt = JSON.parse(await callTool(client, "list_threads", { project_id: "the-lamb" }));
+
+      const commonFields = ["results", "total_count"];
+      const fsHas = commonFields.every(f => f in fs);
+      const gaHas = commonFields.every(f => f in ga);
+      const smHas = commonFields.every(f => f in sm);
+      const ltHas = commonFields.every(f => f in lt);
+
+      if (fsHas && gaHas && smHas && ltHas) {
+        log("11", "PASS", `All tools have results + total_count envelope`);
+      } else {
+        log("11", "FAIL", `Missing fields: fs=${fsHas}, ga=${gaHas}, sm=${smHas}, lt=${ltHas}`);
+      }
+    } catch (err) {
+      log("11", "FAIL", err.message);
+    }
+
+    // ========================================================================
+    // 12. Client-mapping smoke test
+    // ========================================================================
+    console.log("\n=== Scenario 12: Client mapping smoke test ===");
+    try {
+      const smoke = {
+        fs: JSON.parse(await callTool(client, "find_scenes", { project_id: "the-lamb" })),
+        ga: JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom" })),
+        sm: JSON.parse(await callTool(client, "search_metadata", { query: "scene" })),
+        lt: JSON.parse(await callTool(client, "list_threads", { project_id: "the-lamb" })),
+      };
+
+      const allValid = Object.values(smoke).every(obj => obj !== null && typeof obj === "object");
+      
+      if (allValid) {
+        log("12", "PASS", `All 4 tools parsed as valid JSON objects`);
+      } else {
+        log("12", "FAIL", `Some responses did not parse as JSON`);
+      }
+    } catch (err) {
+      log("12", "FAIL", err.message);
+    }
+
+  } finally {
+    await client.close();
+  }
+
+  // ============================================================================
+  // Print summary table
+  // ============================================================================
+  console.log("\n\n" + "=".repeat(80));
+  console.log("SUMMARY TABLE");
+  console.log("=".repeat(80));
+  console.log("\n");
+
+  const passCount = results.filter(r => r.status === "PASS").length;
+  const failCount = results.filter(r => r.status === "FAIL").length;
+  const skipCount = results.filter(r => r.status === "SKIP").length;
+  const warnCount = results.filter(r => r.status === "WARN").length;
+
+  console.table(results);
+  console.log(`\nPASS: ${passCount}, FAIL: ${failCount}, SKIP: ${skipCount}, WARN: ${warnCount}`);
+}
+
+runScenarios().catch(console.error);

package/scripts/manual/test.mjs

@@ -0,0 +1,175 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+
+const BASE_URL = "http://localhost:3000";
+
+const client = new Client({ name: "test-client", version: "1.0.0" });
+const transport = new SSEClientTransport(new URL(`${BASE_URL}/sse`));
+await client.connect(transport);
+
+let passed = 0;
+let failed = 0;
+
+async function test(label, toolName, args, check) {
+  try {
+    const result = await client.callTool({ name: toolName, arguments: args });
+    const text = result.content?.[0]?.text ?? "";
+    const ok = check(text);
+    if (ok) {
+      console.log(`  ✓  ${label}`);
+      passed++;
+    } else {
+      console.log(`  ✗  ${label}`);
+      console.log(`     Output: ${text.slice(0, 200)}`);
+      failed++;
+    }
+  } catch (err) {
+    console.log(`  ✗  ${label} — ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+console.log("\n── sync ──────────────────────────────────────────────────────");
+await test(
+  "sync returns indexed count",
+  "sync", {},
+  t => t.includes("3 scenes indexed")
+);
+
+console.log("\n── find_scenes ───────────────────────────────────────────────");
+await test(
+  "find all scenes returns 3",
+  "find_scenes", {},
+  t => (t.match(/"scene_id"/g) ?? []).length === 3
+);
+
+await test(
+  "filter by character elena returns 3 scenes",
+  "find_scenes", { character: "elena" },
+  t => (t.match(/"scene_id"/g) ?? []).length === 3
+);
+
+await test(
+  "filter by character marcus returns 2 scenes (sc-001, sc-002)",
+  "find_scenes", { character: "marcus" },
+  t => (t.match(/"scene_id"/g) ?? []).length === 2
+);
+
+await test(
+  "filter by beat 'Catalyst' returns sc-003",
+  "find_scenes", { beat: "Catalyst" },
+  t => t.includes("sc-003") && !(t.includes("sc-001")) && !(t.includes("sc-002"))
+);
+
+await test(
+  "filter by chapter 1 returns 2 scenes",
+  "find_scenes", { chapter: 1 },
+  t => (t.match(/"scene_id"/g) ?? []).length === 2
+);
+
+await test(
+  "filter by tag 'harbor' returns scenes 001 and 002",
+  "find_scenes", { tag: "harbor" },
+  t => t.includes("sc-001") && t.includes("sc-002") && !t.includes("sc-003")
+);
+
+console.log("\n── get_scene_prose ───────────────────────────────────────────");
+await test(
+  "returns prose for sc-001",
+  "get_scene_prose", { scene_id: "sc-001" },
+  t => t.includes("gangway") && t.includes("Marcus")
+);
+
+await test(
+  "returns prose for sc-003",
+  "get_scene_prose", { scene_id: "sc-003" },
+  t => t.includes("father") && t.includes("envelope")
+);
+
+await test(
+  "returns error for unknown scene",
+  "get_scene_prose", { scene_id: "sc-999" },
+  t => t.includes("not found")
+);
+
+console.log("\n── get_chapter_prose ─────────────────────────────────────────");
+await test(
+  "returns both scenes from part 1 chapter 1",
+  "get_chapter_prose", { project_id: "test-novel", part: 1, chapter: 1 },
+  t => t.includes("gangway") && t.includes("bait shed")
+);
+
+console.log("\n── get_arc ───────────────────────────────────────────────────");
+await test(
+  "elena arc returns 3 scenes in order",
+  "get_arc", { character_id: "elena" },
+  t => {
+    const ids = [...t.matchAll(/"scene_id": "([^"]+)"/g)].map(m => m[1]);
+    return ids.length === 3 && ids[0] === "sc-001" && ids[2] === "sc-003";
+  }
+);
+
+await test(
+  "marcus arc returns only 2 scenes",
+  "get_arc", { character_id: "marcus" },
+  t => (t.match(/"scene_id"/g) ?? []).length === 2
+);
+
+console.log("\n── list_characters ───────────────────────────────────────────");
+await test(
+  "lists elena and marcus",
+  "list_characters", {},
+  t => t.includes("elena") && t.includes("marcus")
+);
+
+console.log("\n── get_character_sheet ───────────────────────────────────────");
+await test(
+  "elena sheet includes traits and notes",
+  "get_character_sheet", { character_id: "elena" },
+  t => t.includes("driven") && t.includes("self-sabotaging") && t.includes("walls")
+);
+
+await test(
+  "marcus sheet includes arc_summary",
+  "get_character_sheet", { character_id: "marcus" },
+  t => t.includes("loyalty") && t.includes("patient")
+);
+
+console.log("\n── list_places ───────────────────────────────────────────────");
+await test(
+  "lists harbor-district",
+  "list_places", {},
+  t => t.includes("harbor-district")
+);
+
+console.log("\n── search_metadata ───────────────────────────────────────────");
+await test(
+  "search 'harbor' returns relevant scenes",
+  "search_metadata", { query: "harbor" },
+  t => t.includes("sc-001") || t.includes("sc-002")
+);
+
+await test(
+  "search 'envelope' returns sc-003 (word in logline)",
+  "search_metadata", { query: "envelope" },
+  t => t.includes("sc-003")
+);
+
+await test(
+  "search with no match returns helpful message",
+  "search_metadata", { query: "dragons" },
+  t => t.toLowerCase().includes("no scenes")
+);
+
+console.log("\n── list_threads ──────────────────────────────────────────────");
+await test(
+  "returns empty / no threads message (none created yet)",
+  "list_threads", { project_id: "projects/test-novel" },
+  t => t.toLowerCase().includes("no threads")
+);
+
+console.log("\n──────────────────────────────────────────────────────────────");
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`);
+
+await client.close();
+process.exit(failed > 0 ? 1 : 0);