@hanna84/mcp-writing 2.0.3 → 2.1.0

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.1.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.4...v2.1.0)
+
+- feat(tools): add scene character normalization utility [`#83`](https://github.com/hannasdev/mcp-writing.git
+/pull/83)
+
+#### [v2.0.4](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.3...v2.0.4)
+
+> 25 April 2026
+
+- docs(prd): mark review-bundles and scrivener-direct as done [`#82`](https://github.com/hannasdev/mcp-writing.git
+/pull/82)
+- Release 2.0.4 [`775bbcf`](https://github.com/hannasdev/mcp-writing.git
+/commit/775bbcfa0fb93e2b9828a94fa60ad53b29c7313c)
+
 #### [v2.0.3](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.0.2...v2.0.3)
 
+> 25 April 2026
+
 - fix(metadata-lint): warn on mixed scene character reference styles [`#81`](https://github.com/hannasdev/mcp-writing.git
 /pull/81)
+- Release 2.0.3 [`a820668`](https://github.com/hannasdev/mcp-writing.git
+/commit/a8206680db2faeeaa498edd2e112780b1d176be7)
 
 #### [v2.0.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.0.1...v2.0.2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -15,6 +15,7 @@
     "git.js",
     "world-entity-templates.js",
     "metadata-lint.js",
+    "scene-character-normalization.js",
     "review-bundles.js",
     "scripts/",
     "README.md",
@@ -31,6 +32,7 @@
     "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",
+    "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/",

package/scene-character-batch.js

@@ -1,69 +1,10 @@
 import fs from "node:fs";
 import matter from "gray-matter";
+import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
 import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
 
-const NON_DISTINCTIVE_TOKENS = new Set([
-  "the",
-  "and",
-  "for",
-  "with",
-  "from",
-  "into",
-  "onto",
-  "over",
-  "under",
-  "after",
-  "before",
-  "about",
-  "around",
-]);
-
-function escapeRegex(text) {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function isDistinctiveToken(token) {
-  return Boolean(token) && token.length >= 3 && !NON_DISTINCTIVE_TOKENS.has(token);
-}
-
 function normalizeCharacterRows(rows) {
-  const clean = rows
-    .filter(row => row?.character_id && row?.name)
-    .map(row => {
-      const phrase_tokens = String(row.name).toLowerCase().split(/\s+/).filter(Boolean);
-      const tokens = [...new Set(phrase_tokens)];
-      return {
-        character_id: row.character_id,
-        name: String(row.name).trim(),
-        phrase_tokens,
-        tokens,
-        informative_tokens: tokens.filter(isDistinctiveToken),
-        full_name_regex: phrase_tokens.length > 1
-          ? new RegExp(`\\b${phrase_tokens.map(escapeRegex).join("\\s+")}\\b`, "i")
-          : null,
-      };
-    })
-    .filter(row => row.name.length > 0);
-
-  const tokenMap = new Map();
-  const byId = new Map();
-  const nameMap = new Map();
-  for (const row of clean) {
-    byId.set(row.character_id, row);
-
-    const normalizedName = row.name.toLowerCase();
-    const exactNameIds = nameMap.get(normalizedName) ?? [];
-    exactNameIds.push(row.character_id);
-    nameMap.set(normalizedName, exactNameIds);
-
-    for (const token of row.informative_tokens) {
-      const ids = tokenMap.get(token) ?? [];
-      ids.push(row.character_id);
-      tokenMap.set(token, ids);
-    }
-  }
-
-  return { clean, tokenMap, byId, nameMap };
+  return buildCharacterNormalizationContext(rows);
 }
 
 function inferCharactersFromProse(prose, characterRows) {
@@ -113,32 +54,7 @@ function inferCharactersFromProse(prose, characterRows) {
 }
 
 function resolveCharacterEntry(entry, characterRows) {
-  const value = String(entry ?? "").trim();
-  if (!value) return null;
-
-  if (characterRows.byId.has(value)) {
-    return value;
-  }
-
-  const exactNameIds = characterRows.nameMap.get(value.toLowerCase());
-  if (exactNameIds?.length === 1) {
-    return exactNameIds[0];
-  }
-
-  const words = value.toLowerCase().split(/\s+/).filter(isDistinctiveToken);
-  if (words.length === 0) {
-    return value;
-  }
-
-  const matches = characterRows.clean.filter(row =>
-    words.every(word => row.informative_tokens.includes(word))
-  );
-
-  if (matches.length === 1) {
-    return matches[0].character_id;
-  }
-
-  return value;
+  return resolveCharacterReference(entry, characterRows);
 }
 
 function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {

package/scene-character-normalization.js

@@ -0,0 +1,199 @@
+export const NON_DISTINCTIVE_TOKENS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "into",
+  "onto",
+  "over",
+  "under",
+  "after",
+  "before",
+  "about",
+  "around",
+]);
+
+export function escapeRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function isDistinctiveToken(token) {
+  const normalized = String(token ?? "").trim().toLowerCase();
+  return Boolean(normalized) && normalized.length >= 3 && !NON_DISTINCTIVE_TOKENS.has(normalized);
+}
+
+function normalizeRawCharacterValues(values) {
+  const raw = Array.isArray(values) ? values : [];
+  const seen = new Set();
+  const normalized = [];
+
+  for (const value of raw) {
+    const text = String(value ?? "").trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    normalized.push(text);
+  }
+
+  return normalized;
+}
+
+function tokenizeValue(value) {
+  return [...new Set(String(value ?? "").toLowerCase().split(/\s+/).filter(isDistinctiveToken))];
+}
+
+export function buildCharacterNormalizationContext(rows) {
+  const clean = (Array.isArray(rows) ? rows : [])
+    .filter(row => row?.character_id && row?.name)
+    .map(row => {
+      const character_id = String(row.character_id).trim();
+      const name = String(row.name).trim();
+      const phrase_tokens = name.toLowerCase().split(/\s+/).filter(Boolean);
+      const tokens = [...new Set(phrase_tokens)];
+      return {
+        character_id,
+        name,
+        phrase_tokens,
+        tokens,
+        informative_tokens: tokens.filter(isDistinctiveToken),
+        full_name_regex: phrase_tokens.length > 1
+          ? new RegExp(`\\b${phrase_tokens.map(escapeRegex).join("\\s+")}\\b`, "i")
+          : null,
+      };
+    })
+    .filter(row => row.character_id.length > 0 && row.name.length > 0);
+
+  const byId = new Map();
+  const nameMap = new Map();
+  const tokenMap = new Map();
+  for (const row of clean) {
+    byId.set(row.character_id, row);
+    const normalizedName = row.name.toLowerCase();
+    const ids = nameMap.get(normalizedName) ?? [];
+    ids.push(row.character_id);
+    nameMap.set(normalizedName, ids);
+
+    for (const token of row.informative_tokens) {
+      const tokenIds = tokenMap.get(token) ?? [];
+      tokenIds.push(row.character_id);
+      tokenMap.set(token, tokenIds);
+    }
+  }
+
+  return { clean, byId, nameMap, tokenMap };
+}
+
+export function resolveCharacterReference(value, context) {
+  const text = String(value ?? "").trim();
+  if (!text) return null;
+
+  if (context.byId.has(text)) {
+    return text;
+  }
+
+  const exactNameIds = context.nameMap.get(text.toLowerCase());
+  if (exactNameIds?.length === 1) {
+    return exactNameIds[0];
+  }
+
+  const words = text.toLowerCase().split(/\s+/).filter(isDistinctiveToken);
+  if (words.length === 0) {
+    return text;
+  }
+
+  const matches = context.clean.filter(row =>
+    words.every(word => row.informative_tokens.includes(word))
+  );
+
+  if (matches.length === 1) {
+    return matches[0].character_id;
+  }
+
+  return text;
+}
+
+function isProperSubset(subsetTokens, supersetTokens) {
+  if (subsetTokens.length < 2 || subsetTokens.length >= supersetTokens.length) {
+    return false;
+  }
+  return subsetTokens.every(token => supersetTokens.includes(token));
+}
+
+function hasMoreSpecificNonCanonicalSource(candidate, sourceInfo) {
+  if (!sourceInfo || sourceInfo.hadCanonicalSource || sourceInfo.nonCanonicalTokens.length === 0) {
+    return false;
+  }
+
+  return sourceInfo.nonCanonicalTokens.some(tokens => isProperSubset(candidate.informative_tokens, tokens));
+}
+
+function pruneLessSpecificCanonicalIds(values, context, sourceMap) {
+  return values.filter((value, idx) => {
+    const row = context.byId.get(value);
+    if (!row || row.informative_tokens.length === 0) {
+      return true;
+    }
+
+    const rowSource = sourceMap.get(value);
+    if (!rowSource?.hadCanonicalSource) {
+      return true;
+    }
+
+    for (let i = 0; i < values.length; i++) {
+      if (i === idx) continue;
+
+      const otherId = values[i];
+      const other = context.byId.get(otherId);
+      if (!other || other.informative_tokens.length === 0) continue;
+
+      if (
+        isProperSubset(row.informative_tokens, other.informative_tokens)
+        && hasMoreSpecificNonCanonicalSource(row, sourceMap.get(otherId))
+      ) {
+        return false;
+      }
+    }
+
+    return true;
+  });
+}
+
+export function normalizeSceneCharacters(values, context) {
+  const before = normalizeRawCharacterValues(values);
+  const resolved = [];
+  const seen = new Set();
+  const sourceMap = new Map();
+
+  for (const value of before) {
+    const normalized = resolveCharacterReference(value, context);
+    if (!normalized) continue;
+
+    const source = sourceMap.get(normalized) ?? {
+      hadCanonicalSource: false,
+      nonCanonicalTokens: [],
+    };
+
+    if (context.byId.has(value)) {
+      source.hadCanonicalSource = true;
+    } else {
+      source.nonCanonicalTokens.push(tokenizeValue(value));
+    }
+    sourceMap.set(normalized, source);
+
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    resolved.push(normalized);
+  }
+
+  const after = pruneLessSpecificCanonicalIds(resolved, context, sourceMap);
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+
+  return {
+    before,
+    after,
+    changed: before.length !== after.length || before.some((value, idx) => after[idx] !== value),
+    added: after.filter(value => !beforeSet.has(value)),
+    removed: before.filter(value => !afterSet.has(value)),
+  };
+}

package/scripts/normalize-scene-characters.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { openDb } from "../db.js";
+import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../scene-character-normalization.js";
+import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../sync.js";
+
+function readRequiredValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`${option} requires a value.`);
+  }
+  return value;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    syncDir: process.env.WRITING_SYNC_DIR ?? "./sync",
+    projectId: null,
+    write: false,
+    json: false,
+    limit: null,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--sync-dir" || arg === "-d") {
+      opts.syncDir = readRequiredValue(argv, i, arg);
+      i++;
+    } else if (arg === "--project-id" || arg === "-p") {
+      opts.projectId = readRequiredValue(argv, i, arg);
+      i++;
+    } else if (arg === "--limit" || arg === "-n") {
+      opts.limit = Number.parseInt(readRequiredValue(argv, i, arg), 10);
+      i++;
+    } else if (arg === "--write") {
+      opts.write = true;
+    } else if (arg === "--json") {
+      opts.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      opts.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (opts.limit !== null && (!Number.isInteger(opts.limit) || opts.limit <= 0)) {
+    throw new Error("--limit must be a positive integer.");
+  }
+
+  return opts;
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  node --experimental-sqlite scripts/normalize-scene-characters.mjs [--sync-dir <dir>] [--project-id <id>] [--limit <n>] [--write] [--json]",
+    "",
+    "Options:",
+    "  --sync-dir, -d   WRITING_SYNC_DIR root (default: env WRITING_SYNC_DIR or ./sync)",
+    "  --project-id, -p Restrict to one project_id",
+    "  --limit, -n      Process at most N scenes",
+    "  --write          Apply changes (default: dry-run)",
+    "  --json           Emit machine-readable JSON summary",
+    "",
+    "Note: Uses an in-memory sqlite index for analysis; no mcp.sqlite file is created in sync_dir.",
+  ].join("\n");
+}
+
+function queryRows(db, sql, ...params) {
+  return db.prepare(sql).all(...params);
+}
+
+function resolveCharacterRows(db, projectId) {
+  return queryRows(
+    db,
+    `SELECT character_id, name
+       FROM characters
+      WHERE project_id = ?
+         OR universe_id = (SELECT universe_id FROM projects WHERE project_id = ?)
+      ORDER BY length(name) DESC`,
+    projectId,
+    projectId
+  );
+}
+
+function resolveScenes(db, projectId, limit) {
+  const limitClause = Number.isInteger(limit) ? ` LIMIT ${limit}` : "";
+  if (!projectId) {
+    return queryRows(
+      db,
+      `SELECT scene_id, project_id, file_path
+         FROM scenes
+        ORDER BY project_id, part, chapter, timeline_position, scene_id${limitClause}`
+    );
+  }
+  return queryRows(
+    db,
+    `SELECT scene_id, project_id, file_path
+       FROM scenes
+      WHERE project_id = ?
+      ORDER BY part, chapter, timeline_position, scene_id${limitClause}`,
+    projectId
+  );
+}
+
+function runNormalization({ syncDir, projectId, write, limit }) {
+  const db = openDb(":memory:");
+  try {
+    // Refresh index so character/name resolution uses current canonical sheets and sidecars.
+    syncAll(db, syncDir, { quiet: true, writable: false });
+
+    const scenes = resolveScenes(db, projectId, limit);
+    const contextCache = new Map();
+
+    const getContextForProject = (sceneProjectId) => {
+      const key = sceneProjectId ?? "__none__";
+      if (contextCache.has(key)) return contextCache.get(key);
+
+      const context = buildCharacterNormalizationContext(resolveCharacterRows(db, sceneProjectId));
+      contextCache.set(key, context);
+      return context;
+    };
+
+    const changed = [];
+    let processedScenes = 0;
+
+    for (const scene of scenes) {
+      const { meta } = readMeta(scene.file_path, syncDir, { writable: false });
+      if (!Array.isArray(meta.characters) || meta.characters.length === 0) {
+        processedScenes++;
+        continue;
+      }
+
+      const normalized = normalizeSceneCharacters(meta.characters, getContextForProject(scene.project_id));
+      processedScenes++;
+
+      if (!normalized.changed) continue;
+
+      if (write) {
+        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+          ...meta,
+          characters: normalized.after,
+        }).meta;
+        writeMeta(scene.file_path, updatedMeta);
+      }
+
+      changed.push({
+        scene_id: scene.scene_id,
+        project_id: scene.project_id,
+        file_path: scene.file_path,
+        before_characters: normalized.before,
+        after_characters: normalized.after,
+        added: normalized.added,
+        removed: normalized.removed,
+      });
+    }
+
+    return {
+      ok: true,
+      mode: write ? "write" : "dry_run",
+      sync_dir: path.resolve(syncDir),
+      project_id: projectId,
+      processed_scenes: processedScenes,
+      scenes_changed: changed.length,
+      character_reference_count: [...contextCache.values()].reduce((sum, ctx) => sum + ctx.clean.length, 0),
+      changes: changed,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function printTextSummary(result) {
+  process.stdout.write(`normalize-scene-characters (${result.mode})\n`);
+  process.stdout.write(`sync_dir: ${result.sync_dir}\n`);
+  process.stdout.write(`project_id: ${result.project_id ?? "(all projects)"}\n`);
+  process.stdout.write(`processed_scenes: ${result.processed_scenes}\n`);
+  process.stdout.write(`scenes_changed: ${result.scenes_changed}\n`);
+  process.stdout.write(`character_reference_count: ${result.character_reference_count}\n`);
+
+  const preview = result.changes.slice(0, 20);
+  for (const row of preview) {
+    process.stdout.write(`- ${row.scene_id} (${row.project_id})\n`);
+    process.stdout.write(`  added: ${row.added.join(", ") || "(none)"}\n`);
+    process.stdout.write(`  removed: ${row.removed.join(", ") || "(none)"}\n`);
+  }
+  if (result.changes.length > preview.length) {
+    process.stdout.write(`... ${result.changes.length - preview.length} more changed scene(s)\n`);
+  }
+
+  if (result.mode === "write") {
+    process.stdout.write("next_step: run sync() to refresh DB indexes from updated sidecars\n");
+  }
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      process.stdout.write(`${usage()}\n`);
+      return;
+    }
+
+    const result = runNormalization({
+      syncDir: path.resolve(opts.syncDir),
+      projectId: opts.projectId,
+      write: opts.write,
+      limit: opts.limit,
+    });
+
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return;
+    }
+    printTextSummary(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${message}\n`);
+    process.stderr.write(`${usage()}\n`);
+    process.exit(1);
+  }
+}
+
+main();