@hanna84/mcp-writing 2.0.1 → 2.0.3

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.0.3](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.2...v2.0.3)
+
+- fix(metadata-lint): warn on mixed scene character reference styles [`#81`](https://github.com/hannasdev/mcp-writing.git
+/pull/81)
+
+#### [v2.0.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.1...v2.0.2)
+
+> 25 April 2026
+
+- fix(scene-character-batch): tighten precision-first character linking [`#80`](https://github.com/hannasdev/mcp-writing.git
+/pull/80)
+- Release 2.0.2 [`0ca5898`](https://github.com/hannasdev/mcp-writing.git
+/commit/0ca58982799b64f115681948b19b4dc795095951)
+
 #### [v2.0.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.0.0...v2.0.1)
 
+> 25 April 2026
+
 - fix(package): include scene-character-batch in published files [`#79`](https://github.com/hannasdev/mcp-writing.git
 /pull/79)
+- Release 2.0.1 [`ec34e21`](https://github.com/hannasdev/mcp-writing.git
+/commit/ec34e21c6c4d9472c937d5e549f55ddea4b57186)
 
 ### [v2.0.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.17.0...v2.0.0)

package/metadata-lint.js

@@ -119,6 +119,23 @@ function validateUniqueArrays(meta, kind, issues) {
   }
 }
 
+function validateSceneCharacterReferenceStyle(meta, issues) {
+  if (!Array.isArray(meta.characters) || meta.characters.length === 0) return;
+
+  if (!meta.characters.every(value => typeof value === "string")) return;
+
+  const hasCanonicalIds = meta.characters.some(value => /^char-/.test(String(value).trim()));
+  const hasNonCanonicalEntries = meta.characters.some(value => !/^char-/.test(String(value).trim()));
+
+  if (!hasCanonicalIds || !hasNonCanonicalEntries) return;
+
+  issues.push({
+    level: "warning",
+    code: "MIXED_CHARACTER_REFERENCE_STYLE",
+    message: "Scene characters contain mixed canonical and non-canonical references. Prefer canonical character_id values only.",
+  });
+}
+
 export function validateMetadataObject(meta, { sourcePath, kindHint } = {}) {
   const issues = [];
   const kind = metadataKindSchema.parse(kindHint ?? detectMetadataKind(meta));
@@ -168,6 +185,10 @@ export function validateMetadataObject(meta, { sourcePath, kindHint } = {}) {
 
   validateUniqueArrays(meta, kind, issues);
 
+  if (kind === "scene") {
+    validateSceneCharacterReferenceStyle(meta, issues);
+  }
+
   if (kind === "scene" && sourcePath) {
     const sidecar = sourcePath.endsWith(".meta.yaml");
     if (sidecar && !meta.scene_id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/scene-character-batch.js

@@ -2,50 +2,89 @@ import fs from "node:fs";
 import matter from "gray-matter";
 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 => ({
-      character_id: row.character_id,
-      name: String(row.name).trim(),
-      tokens: [...new Set(String(row.name).toLowerCase().split(/\s+/).filter(Boolean))],
-    }))
+    .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) {
-    for (const token of row.tokens) {
-      if (!token || token.length < 3) continue;
+    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 };
+  return { clean, tokenMap, byId, nameMap };
 }
 
 function inferCharactersFromProse(prose, characterRows) {
   const { clean, tokenMap } = characterRows;
   const inferred = new Set();
+  const full_name_matches = new Set();
   const ambiguous_tokens = [];
 
   for (const row of clean) {
-    if (row.tokens.length > 1) {
-      const pattern = row.tokens.map(escapeRegex).join("\\s+");
-      const regex = new RegExp(`\\b${pattern}\\b`, "i");
-      if (regex.test(prose)) {
-        inferred.add(row.character_id);
-        continue;
-      }
+    if (row.full_name_regex?.test(prose)) {
+      inferred.add(row.character_id);
+      full_name_matches.add(row.character_id);
+      continue;
+    }
+
+    // Precision-first v1 policy: multi-token names require a full phrase match.
+    if (row.phrase_tokens.length !== 1) {
+      continue;
     }
 
-    for (const token of row.tokens) {
-      if (!token || token.length < 3) continue;
+    for (const token of row.informative_tokens) {
       const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
       if (!tokenRegex.test(prose)) continue;
 
@@ -58,12 +97,73 @@ function inferCharactersFromProse(prose, characterRows) {
     }
   }
 
+  for (const [token, tokenIds] of tokenMap.entries()) {
+    if (tokenIds.length < 2) continue;
+    const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
+    if (tokenRegex.test(prose) && !ambiguous_tokens.includes(token)) {
+      ambiguous_tokens.push(token);
+    }
+  }
+
   return {
     inferred_characters: [...inferred],
+    full_name_matches: [...full_name_matches],
     ambiguous_tokens,
   };
 }
 
+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;
+}
+
+function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {
+  const kept = new Set(characterIds);
+
+  for (const candidateId of [...kept]) {
+    const candidate = characterRows.byId.get(candidateId);
+    if (!candidate || candidate.informative_tokens.length < 2) continue;
+
+    for (const dominantId of fullNameMatches) {
+      if (candidateId === dominantId) continue;
+      const dominant = characterRows.byId.get(dominantId);
+      if (!dominant) continue;
+      if (candidate.informative_tokens.length >= dominant.informative_tokens.length) continue;
+
+      if (candidate.informative_tokens.every(token => dominant.informative_tokens.includes(token))) {
+        kept.delete(candidateId);
+        break;
+      }
+    }
+  }
+
+  return [...kept];
+}
+
 function nextTurn() {
   return new Promise(resolve => setImmediate(resolve));
 }
@@ -125,10 +225,15 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
       const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
 
       const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
+      const normalized_before_characters = [...new Set(
+        before_characters
+          .map(character => resolveCharacterEntry(character, normalizedCharacterRows))
+          .filter(Boolean)
+      )];
       const inference = inferCharactersFromProse(prose, normalizedCharacterRows);
       const inferred_characters = inference.inferred_characters;
 
-      const afterSet = new Set(before_characters);
+      const afterSet = new Set(normalized_before_characters);
       if (replace_mode === "replace") {
         afterSet.clear();
       }
@@ -136,7 +241,11 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
         afterSet.add(characterId);
       }
 
-      const after_characters = [...afterSet];
+      const after_characters = pruneLessSpecificCharacters(
+        [...afterSet],
+        inference.full_name_matches,
+        normalizedCharacterRows
+      );
       const beforeSet = new Set(before_characters);
       const added = after_characters.filter(id => !beforeSet.has(id));
       const afterSetLookup = new Set(after_characters);