@hanna84/mcp-writing 2.13.0 → 2.15.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.15.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.14.0...v2.15.0)
+
+- feat(reference): add reference link query tools [`#148`](https://github.com/hannasdev/mcp-writing.git
+/pull/148)
+
+#### [v2.14.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.13.0...v2.14.0)
+
+> 30 April 2026
+
+- feat(reference): add reference link indexing for Phase 4B [`#147`](https://github.com/hannasdev/mcp-writing.git
+/pull/147)
+- Release 2.14.0 [`0b82946`](https://github.com/hannasdev/mcp-writing.git
+/commit/0b829469448cb86008113dbf1b05f92e700b61a1)
+
 #### [v2.13.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.22...v2.13.0)
 
+> 30 April 2026
+
 - feat: add reference document search [`#146`](https://github.com/hannasdev/mcp-writing.git
 /pull/146)
+- Release 2.13.0 [`0df673a`](https://github.com/hannasdev/mcp-writing.git
+/commit/0df673a183f180a16cd5a9490c2829932b4aa744)
 
 #### [v2.12.22](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.21...v2.12.22)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.13.0",
+  "version": "2.15.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

@@ -118,6 +118,18 @@ export const SCHEMA = `
     PRIMARY KEY (doc_id, tag)
   );
 
+  CREATE TABLE IF NOT EXISTS reference_links (
+    source_kind   TEXT NOT NULL,
+    source_project_id TEXT NOT NULL DEFAULT '',
+    source_id     TEXT NOT NULL,
+    target_doc_id TEXT NOT NULL,
+    relation      TEXT NOT NULL,
+    PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+    ON reference_links(target_doc_id);
+
   CREATE VIRTUAL TABLE IF NOT EXISTS scenes_fts USING fts5(
     scene_id, project_id, logline, title, keywords
   );
@@ -196,6 +208,72 @@ const MIGRATIONS = [
       `);
     }
   },
+  // 4: add explicit reference links table
+  (db) => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS reference_links (
+        source_kind   TEXT NOT NULL,
+        source_project_id TEXT NOT NULL DEFAULT '',
+        source_id     TEXT NOT NULL,
+        target_doc_id TEXT NOT NULL,
+        relation      TEXT NOT NULL,
+        PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+      );
+    `);
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+        ON reference_links(target_doc_id);
+    `);
+  },
+  // 5: ensure reference_links has project-scoped source key and target_doc_id index
+  (db) => {
+    const tables = db.prepare(`
+      SELECT name
+      FROM sqlite_master
+      WHERE type = 'table' AND name = 'reference_links'
+    `).all();
+
+    if (tables.length === 0) {
+      db.exec(`
+        CREATE TABLE reference_links (
+          source_kind   TEXT NOT NULL,
+          source_project_id TEXT NOT NULL DEFAULT '',
+          source_id     TEXT NOT NULL,
+          target_doc_id TEXT NOT NULL,
+          relation      TEXT NOT NULL,
+          PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+        );
+      `);
+    } else {
+      const columns = db.prepare(`PRAGMA table_info(reference_links)`).all();
+      if (!columns.some(c => c.name === "source_project_id")) {
+        db.exec(`
+          CREATE TABLE reference_links_migrating (
+            source_kind   TEXT NOT NULL,
+            source_project_id TEXT NOT NULL DEFAULT '',
+            source_id     TEXT NOT NULL,
+            target_doc_id TEXT NOT NULL,
+            relation      TEXT NOT NULL,
+            PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+          );
+        `);
+        db.exec(`
+          INSERT OR IGNORE INTO reference_links_migrating
+            (source_kind, source_project_id, source_id, target_doc_id, relation)
+          SELECT source_kind, '', source_id, target_doc_id, relation
+          FROM reference_links;
+        `);
+        db.exec(`DROP TABLE reference_links;`);
+        db.exec(`ALTER TABLE reference_links_migrating RENAME TO reference_links;`);
+      }
+    }
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+        ON reference_links(target_doc_id);
+    `);
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —

package/src/sync/sync.js

@@ -267,6 +267,20 @@ export function normalizeReferenceTags(tags) {
   )];
 }
 
+export function normalizeReferenceIdList(values) {
+  const rawValues = Array.isArray(values)
+    ? values
+    : typeof values === "string"
+      ? values.split(",")
+      : [];
+
+  return [...new Set(
+    rawValues
+      .map(value => String(value).trim())
+      .filter(Boolean)
+  )];
+}
+
 export function deriveReferenceSummary(meta = {}, content = "") {
   if (typeof meta.summary === "string" && meta.summary.trim()) return meta.summary.trim();
 
@@ -282,6 +296,30 @@ export function deriveReferenceSummary(meta = {}, content = "") {
   return body.length <= 240 ? body : `${body.slice(0, 237).trimEnd()}...`;
 }
 
+function indexReferenceLinksForSource(db, {
+  sourceKind,
+  sourceProjectId = "",
+  sourceId,
+  targetDocIds,
+  relation,
+}) {
+  db.prepare(`
+    DELETE FROM reference_links
+    WHERE source_kind = ? AND source_project_id = ? AND source_id = ?
+  `).run(sourceKind, sourceProjectId, sourceId);
+
+  const insertReferenceLink = db.prepare(`
+    INSERT OR IGNORE INTO reference_links
+      (source_kind, source_project_id, source_id, target_doc_id, relation)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+
+  for (const targetDocId of targetDocIds) {
+    if (sourceKind === "reference" && sourceId === targetDocId) continue;
+    insertReferenceLink.run(sourceKind, sourceProjectId, sourceId, targetDocId, relation);
+  }
+}
+
 export function worldEntityKindForPath(syncDir, filePath) {
   const rel = path.relative(syncDir, filePath);
   if (rel.includes(`${path.sep}characters${path.sep}`) || rel.includes("/characters/")) return "character";
@@ -582,6 +620,9 @@ export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
   const title = deriveReferenceTitle(file, meta, content);
   const summary = deriveReferenceSummary(meta, content);
   const tags = normalizeReferenceTags(meta.tags);
+  const relatedReferenceIds = normalizeReferenceIdList(
+    meta.related_reference_ids ?? meta.related_references ?? meta.related_docs ?? meta.related
+  );
 
   db.prepare(`
     INSERT INTO reference_docs (doc_id, project_id, universe_id, type, title, summary, file_path)
@@ -620,13 +661,26 @@ export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
     tags.join(" ")
   );
 
+  indexReferenceLinksForSource(db, {
+    sourceKind: "reference",
+    sourceProjectId: project_id ?? "",
+    sourceId: docId,
+    targetDocIds: relatedReferenceIds,
+    relation: "related",
+  });
+
   return docId;
 }
 
 function pruneMissingReferenceDocs(db, seenDocIds) {
-  const rows = db.prepare(`SELECT doc_id FROM reference_docs`).all();
+  const rows = db.prepare(`SELECT doc_id, project_id FROM reference_docs`).all();
   for (const row of rows) {
     if (seenDocIds.has(row.doc_id)) continue;
+    db.prepare(`
+      DELETE FROM reference_links
+      WHERE source_kind = 'reference' AND source_project_id = ? AND source_id = ?
+    `).run(row.project_id ?? "", row.doc_id);
+    db.prepare(`DELETE FROM reference_links WHERE target_doc_id = ?`).run(row.doc_id);
     db.prepare(`DELETE FROM reference_doc_tags WHERE doc_id = ?`).run(row.doc_id);
     db.prepare(`DELETE FROM reference_docs_fts WHERE doc_id = ?`).run(row.doc_id);
     db.prepare(`DELETE FROM reference_docs WHERE doc_id = ?`).run(row.doc_id);
@@ -651,8 +705,79 @@ function canPruneReferenceDocs(syncDir) {
   return hasBroadRootChild;
 }
 
+function inferSceneProjectScopeFromSyncDir(syncDir) {
+  const parts = path.resolve(syncDir).split(path.sep).filter(Boolean);
+  if (parts.length < 2) return null;
+
+  const tail = parts.at(-1);
+  const parent = parts.at(-2);
+
+  if (parent === "projects" && tail) {
+    return tail;
+  }
+
+  if (tail === "scenes" && parts.length >= 3 && parts.at(-3) === "projects") {
+    return parts.at(-2);
+  }
+
+  if (parts.length >= 3 && parts.at(-3) === "universes") {
+    return `${parts.at(-2)}/${parts.at(-1)}`;
+  }
+
+  if (tail === "scenes" && parts.length >= 4 && parts.at(-4) === "universes") {
+    return `${parts.at(-3)}/${parts.at(-2)}`;
+  }
+
+  return null;
+}
+
+function canPruneScenes(syncDir) {
+  const resolvedSyncDir = path.resolve(syncDir);
+
+  if (inferSceneProjectScopeFromSyncDir(resolvedSyncDir)) {
+    return true;
+  }
+
+  const hasBroadRootChild = ["projects", "universes", "scenes"].some((name) => {
+    try {
+      return fs.statSync(path.join(resolvedSyncDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  return hasBroadRootChild;
+}
+
+function pruneMissingScenes(db, seenSceneKeys, syncDir) {
+  const projectScope = inferSceneProjectScopeFromSyncDir(syncDir);
+  const rows = projectScope
+    ? db.prepare(`SELECT scene_id, project_id FROM scenes WHERE project_id = ?`).all(projectScope)
+    : db.prepare(`SELECT scene_id, project_id FROM scenes`).all();
+
+  for (const row of rows) {
+    const key = `${row.scene_id}::${row.project_id}`;
+    if (seenSceneKeys.has(key)) continue;
+
+    db.prepare(`DELETE FROM scenes_fts WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    db.prepare(`
+      DELETE FROM reference_links
+      WHERE source_kind = 'scene' AND source_project_id = ? AND source_id = ?
+    `).run(row.project_id ?? "", row.scene_id);
+    db.prepare(`DELETE FROM scenes WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+
+    const remainingScene = db.prepare(`SELECT 1 FROM scenes WHERE scene_id = ? LIMIT 1`).get(row.scene_id);
+    if (!remainingScene) {
+      db.prepare(`DELETE FROM scene_characters WHERE scene_id = ?`).run(row.scene_id);
+      db.prepare(`DELETE FROM scene_places WHERE scene_id = ?`).run(row.scene_id);
+      db.prepare(`DELETE FROM scene_tags WHERE scene_id = ?`).run(row.scene_id);
+    }
+  }
+}
+
 export function indexSceneFile(db, syncDir, file, meta, prose) {
   const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
+  const referenceIds = normalizeReferenceIdList(meta.reference_ids ?? meta.references);
 
   if (universe_id) {
     db.prepare(`INSERT OR IGNORE INTO universes (universe_id, name) VALUES (?, ?)`).run(
@@ -777,6 +902,14 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     keywordTokens,
   );
 
+  indexReferenceLinksForSource(db, {
+    sourceKind: "scene",
+    sourceProjectId: project_id ?? "",
+    sourceId: meta.scene_id,
+    targetDocIds: referenceIds,
+    relation: "informs",
+  });
+
   return { isStale };
 }
 
@@ -826,8 +959,10 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   let skipped = 0;
   let sidecarsMigrated = 0;
   const seenSceneIds = new Map(); // scene_id+project_id → file path, for duplicate detection
+  const seenSceneKeys = new Set();
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
   const indexedReferenceDocIds = new Set();
+  let sceneIndexFailures = 0;
   const warnings = [];
 
   const scanFiles = [];
@@ -896,6 +1031,7 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       } else {
         seenSceneIds.set(key, file);
       }
+      seenSceneKeys.add(key);
 
       if (mismatches.part || mismatches.chapter) {
         const details = [];
@@ -912,10 +1048,15 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       if (isStale) staleMarked++;
       indexed++;
     } catch (err) {
+      sceneIndexFailures++;
       process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
     }
   }
 
+  if (canPruneScenes(syncDir) && sceneIndexFailures === 0) {
+    pruneMissingScenes(db, seenSceneKeys, syncDir);
+  }
+
   // --- Orphaned sidecar detection ---
   const sidecars = walkSidecars(syncDir).filter(sidecar => !isNestedMirrorPath(syncDir, sidecar));
   for (const sidecar of sidecars) {

package/src/tools/search.js

@@ -485,6 +485,160 @@ export function registerSearchTools(s, {
     }
   );
 
+  // ---- list_scene_references -----------------------------------------------
+  s.tool(
+    "list_scene_references",
+    "List direct reference documents linked from a scene via metadata (for example, reference_ids). Returns only one-hop scene -> reference links and does not recursively traverse related references. If scene IDs are reused across projects, omitting project_id returns CONFLICT with candidate project_ids.",
+    {
+      scene_id: z.string().describe("Scene ID to inspect."),
+      project_id: z.string().optional().describe("Optional project ID to disambiguate duplicate scene IDs across projects."),
+    },
+    async ({ scene_id, project_id }) => {
+      let scene;
+      if (project_id) {
+        scene = db.prepare(`
+          SELECT scene_id, project_id
+          FROM scenes
+          WHERE scene_id = ? AND project_id = ?
+          LIMIT 1
+        `).get(scene_id, project_id);
+        if (!scene) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+        }
+      } else {
+        const matches = db.prepare(`
+          SELECT scene_id, project_id
+          FROM scenes
+          WHERE scene_id = ?
+          ORDER BY project_id
+        `).all(scene_id);
+        if (matches.length === 0) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+        }
+        if (matches.length > 1) {
+          return errorResponse(
+            "CONFLICT",
+            `Scene ID '${scene_id}' exists in multiple projects. Provide project_id to disambiguate.`,
+            { scene_id, project_ids: matches.map(row => row.project_id) }
+          );
+        }
+        scene = matches[0];
+      }
+
+      const links = db.prepare(`
+        SELECT
+          rl.target_doc_id,
+          rl.relation,
+          rd.project_id AS target_project_id,
+          rd.universe_id AS target_universe_id,
+          rd.type,
+          rd.title,
+          rd.summary,
+          rd.file_path
+        FROM reference_links rl
+        LEFT JOIN reference_docs rd ON rd.doc_id = rl.target_doc_id
+        WHERE rl.source_kind = 'scene' AND rl.source_project_id = ? AND rl.source_id = ?
+        ORDER BY rl.target_doc_id
+      `).all(scene.project_id ?? "", scene.scene_id);
+
+      if (links.length === 0) {
+        return errorResponse("NO_RESULTS", `No reference links found for scene '${scene.scene_id}' in project '${scene.project_id}'.`);
+      }
+
+      const tagsStmt = db.prepare(`
+        SELECT tag
+        FROM reference_doc_tags
+        WHERE doc_id = ?
+        ORDER BY tag
+      `);
+      const references = links.map((row) => ({
+        doc_id: row.target_doc_id,
+        relation: row.relation,
+        project_id: row.target_project_id,
+        universe_id: row.target_universe_id,
+        type: row.type,
+        title: row.title,
+        summary: row.summary,
+        file_path: row.file_path,
+        tags: tagsStmt.all(row.target_doc_id).map(tagRow => tagRow.tag),
+      }));
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            scene_id: scene.scene_id,
+            project_id: scene.project_id,
+            references,
+          }, null, 2),
+        }],
+      };
+    }
+  );
+
+  // ---- get_reference_doc ----------------------------------------------------
+  s.tool(
+    "get_reference_doc",
+    "Get metadata for a reference document by doc_id. Optionally includes exactly one hop of related reference docs.",
+    {
+      doc_id: z.string().describe("Reference document ID."),
+      include_related: z.boolean().optional().describe("If true, include one-hop related reference docs."),
+    },
+    async ({ doc_id, include_related = false }) => {
+      const doc = db.prepare(`
+        SELECT doc_id, project_id, universe_id, type, title, summary, file_path
+        FROM reference_docs
+        WHERE doc_id = ?
+      `).get(doc_id);
+      if (!doc) {
+        return errorResponse("NOT_FOUND", `Reference document '${doc_id}' not found.`);
+      }
+
+      const tagsStmt = db.prepare(`
+        SELECT tag
+        FROM reference_doc_tags
+        WHERE doc_id = ?
+        ORDER BY tag
+      `);
+      const payload = {
+        ...doc,
+        tags: tagsStmt.all(doc.doc_id).map(row => row.tag),
+      };
+
+      if (include_related) {
+        const relatedRows = db.prepare(`
+          SELECT
+            rl.target_doc_id,
+            rl.relation,
+            rd.project_id,
+            rd.universe_id,
+            rd.type,
+            rd.title,
+            rd.summary,
+            rd.file_path
+          FROM reference_links rl
+          LEFT JOIN reference_docs rd ON rd.doc_id = rl.target_doc_id
+          WHERE rl.source_kind = 'reference' AND rl.source_project_id = ? AND rl.source_id = ?
+          ORDER BY rl.target_doc_id
+        `).all(doc.project_id ?? "", doc.doc_id);
+
+        payload.related = relatedRows.map((row) => ({
+          doc_id: row.target_doc_id,
+          relation: row.relation,
+          project_id: row.project_id,
+          universe_id: row.universe_id,
+          type: row.type,
+          title: row.title,
+          summary: row.summary,
+          file_path: row.file_path,
+          tags: tagsStmt.all(row.target_doc_id).map(tagRow => tagRow.tag),
+        }));
+      }
+
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    }
+  );
+
   // ---- list_threads --------------------------------------------------------
   s.tool(
     "list_threads",