@hanna84/mcp-writing 2.12.21 → 2.13.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.13.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.12.22...v2.13.0)
+
+- feat: add reference document search [`#146`](https://github.com/hannasdev/mcp-writing.git
+/pull/146)
+
+#### [v2.12.22](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.12.21...v2.12.22)
+
+> 30 April 2026
+
+- docs(prd): refine reference docs into reference graph model [`#143`](https://github.com/hannasdev/mcp-writing.git
+/pull/143)
+- Release 2.12.22 [`d363c63`](https://github.com/hannasdev/mcp-writing.git
+/commit/d363c63ddcaf6de694f24d9ed66e2f703f439bf4)
+
 #### [v2.12.21](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.20...v2.12.21)
 
+> 30 April 2026
+
 - docs: mark embeddings search as deferred backlog [`#142`](https://github.com/hannasdev/mcp-writing.git
 /pull/142)
+- Release 2.12.21 [`acafde5`](https://github.com/hannasdev/mcp-writing.git
+/commit/acafde5e2b54a1459ad5286b1001f7c068cb035c)
 
 #### [v2.12.20](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.19...v2.12.20)

package/package.json

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

@@ -106,7 +106,9 @@ export const SCHEMA = `
     doc_id      TEXT NOT NULL PRIMARY KEY,
     project_id  TEXT,
     universe_id TEXT,
+    type        TEXT,
     title       TEXT NOT NULL,
+    summary     TEXT,
     file_path   TEXT NOT NULL
   );
 
@@ -120,6 +122,10 @@ export const SCHEMA = `
     scene_id, project_id, logline, title, keywords
   );
 
+  CREATE VIRTUAL TABLE IF NOT EXISTS reference_docs_fts USING fts5(
+    doc_id, project_id, title, summary, tags
+  );
+
   CREATE TABLE IF NOT EXISTS schema_version (
     id      INTEGER PRIMARY KEY CHECK (id = 1),
     version INTEGER NOT NULL
@@ -169,6 +175,27 @@ const MIGRATIONS = [
       db.exec(`ALTER TABLE scenes_fts_migrating RENAME TO scenes_fts;`);
     }
   },
+  // 3: add lightweight reference-doc metadata columns and FTS table
+  (db) => {
+    const referenceDocColumns = db.prepare(`PRAGMA table_info(reference_docs)`).all();
+    if (!referenceDocColumns.some(c => c.name === "type")) {
+      db.exec(`ALTER TABLE reference_docs ADD COLUMN type TEXT;`);
+    }
+    if (!referenceDocColumns.some(c => c.name === "summary")) {
+      db.exec(`ALTER TABLE reference_docs ADD COLUMN summary TEXT;`);
+    }
+
+    const ftsSql = db.prepare(`
+      SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'reference_docs_fts'
+    `).get()?.sql;
+    if (typeof ftsSql !== "string") {
+      db.exec(`
+        CREATE VIRTUAL TABLE reference_docs_fts USING fts5(
+          doc_id, project_id, title, summary, tags
+        );
+      `);
+    }
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —

package/src/sync/sync.js

@@ -170,6 +170,118 @@ export function isWorldFile(syncDir, filePath) {
   return rel.includes(`${path.sep}world${path.sep}`) || rel.includes("/world/");
 }
 
+export function isReferenceFile(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  return rel.startsWith("world/reference/") || rel.includes("/world/reference/") || rel.startsWith("notes/") || rel.includes("/notes/");
+}
+
+export function inferReferenceDocType(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  if (rel.startsWith("world/reference/") || rel.includes("/world/reference/")) return "world";
+  if (rel.startsWith("notes/continuity/") || rel.includes("/notes/continuity/")) return "continuity";
+  if (rel.startsWith("notes/research/") || rel.includes("/notes/research/")) return "research";
+  if (rel.startsWith("notes/style/") || rel.includes("/notes/style/")) return "style";
+  return "reference";
+}
+
+function inferReferenceScopeFromSyncDir(syncDir) {
+  const parts = path.resolve(syncDir).split(path.sep).filter(Boolean);
+  const projectSlug = parts.at(-1);
+  const parent = parts.at(-2);
+  const universeId = parts.at(-2);
+  const universeProjectSlug = parts.at(-1);
+  const universeMarker = parts.at(-3);
+
+  if (parent === "projects" && projectSlug) {
+    return { universe_id: null, project_id: projectSlug };
+  }
+
+  if (parent === "universes" && projectSlug) {
+    return { universe_id: projectSlug, project_id: null };
+  }
+
+  if (universeMarker === "universes" && universeId && universeProjectSlug) {
+    return { universe_id: universeId, project_id: `${universeId}/${universeProjectSlug}` };
+  }
+
+  return null;
+}
+
+function inferReferenceProjectAndUniverse(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  const scoped = inferReferenceScopeFromSyncDir(syncDir);
+  if (
+    scoped
+    && (rel.startsWith("world/reference/") || rel.startsWith("notes/"))
+  ) {
+    return scoped;
+  }
+
+  return inferProjectAndUniverse(syncDir, filePath);
+}
+
+function slugifyReferencePart(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/\.(md|txt)$/i, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function deriveReferenceDocId(syncDir, filePath, meta = {}) {
+  if (typeof meta.doc_id === "string" && meta.doc_id.trim()) return meta.doc_id.trim();
+
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/");
+  const slug = rel
+    .split("/")
+    .map(slugifyReferencePart)
+    .filter(Boolean)
+    .join("-");
+  return `ref-${slug}`;
+}
+
+export function deriveReferenceTitle(filePath, meta = {}, content = "") {
+  if (typeof meta.title === "string" && meta.title.trim()) return meta.title.trim();
+
+  const heading = content.match(/^\s*#\s+(.+?)\s*$/m)?.[1]?.trim();
+  if (heading) return heading;
+
+  const base = path.basename(filePath, path.extname(filePath));
+  return base
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function normalizeReferenceTags(tags) {
+  const values = Array.isArray(tags)
+    ? tags
+    : typeof tags === "string"
+      ? tags.split(",")
+      : [];
+
+  return [...new Set(
+    values
+      .map(tag => String(tag).trim())
+      .filter(Boolean)
+  )];
+}
+
+export function deriveReferenceSummary(meta = {}, content = "") {
+  if (typeof meta.summary === "string" && meta.summary.trim()) return meta.summary.trim();
+
+  const body = content
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith("#"))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!body) return null;
+  return body.length <= 240 ? body : `${body.slice(0, 237).trimEnd()}...`;
+}
+
 export function worldEntityKindForPath(syncDir, filePath) {
   const rel = path.relative(syncDir, filePath);
   if (rel.includes(`${path.sep}characters${path.sep}`) || rel.includes("/characters/")) return "character";
@@ -463,6 +575,82 @@ export function indexWorldFile(db, syncDir, file, meta) {
   }
 }
 
+export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
+  const { universe_id, project_id } = inferReferenceProjectAndUniverse(syncDir, file);
+  const docId = deriveReferenceDocId(syncDir, file, meta);
+  const type = inferReferenceDocType(syncDir, file);
+  const title = deriveReferenceTitle(file, meta, content);
+  const summary = deriveReferenceSummary(meta, content);
+  const tags = normalizeReferenceTags(meta.tags);
+
+  db.prepare(`
+    INSERT INTO reference_docs (doc_id, project_id, universe_id, type, title, summary, file_path)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (doc_id) DO UPDATE SET
+      project_id = excluded.project_id,
+      universe_id = excluded.universe_id,
+      type = excluded.type,
+      title = excluded.title,
+      summary = excluded.summary,
+      file_path = excluded.file_path
+  `).run(
+    docId,
+    project_id ?? null,
+    universe_id ?? null,
+    type,
+    title,
+    summary ?? null,
+    file
+  );
+
+  db.prepare(`DELETE FROM reference_doc_tags WHERE doc_id = ?`).run(docId);
+  for (const tag of tags) {
+    db.prepare(`INSERT OR IGNORE INTO reference_doc_tags (doc_id, tag) VALUES (?, ?)`).run(docId, tag);
+  }
+
+  db.prepare(`DELETE FROM reference_docs_fts WHERE doc_id = ?`).run(docId);
+  db.prepare(`
+    INSERT INTO reference_docs_fts (doc_id, project_id, title, summary, tags)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(
+    docId,
+    project_id ?? "",
+    title,
+    summary ?? "",
+    tags.join(" ")
+  );
+
+  return docId;
+}
+
+function pruneMissingReferenceDocs(db, seenDocIds) {
+  const rows = db.prepare(`SELECT doc_id FROM reference_docs`).all();
+  for (const row of rows) {
+    if (seenDocIds.has(row.doc_id)) continue;
+    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);
+  }
+}
+
+function canPruneReferenceDocs(syncDir) {
+  const resolvedSyncDir = path.resolve(syncDir);
+  const scopedRoot = inferReferenceScopeFromSyncDir(resolvedSyncDir);
+  if (scopedRoot) return true;
+
+  // Flat project roots and broad workspace roots can safely prune because
+  // they can observe the full set of reference docs in their scope.
+  const hasBroadRootChild = ["projects", "universes", "scenes"].some((name) => {
+    try {
+      return fs.statSync(path.join(resolvedSyncDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  return hasBroadRootChild;
+}
+
 export function indexSceneFile(db, syncDir, file, meta, prose) {
   const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
 
@@ -639,6 +827,7 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   let sidecarsMigrated = 0;
   const seenSceneIds = new Map(); // scene_id+project_id → file path, for duplicate detection
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
+  const indexedReferenceDocIds = new Set();
   const warnings = [];
 
   const scanFiles = [];
@@ -650,9 +839,20 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     scanFiles.push(file);
   }
 
-  // --- Pass 1: world files (characters/places must be indexed before scenes
-  // so that character name → ID resolution in scene_characters works) ---
+  // --- Pass 1: world files and reference docs (characters/places must be indexed
+  // before scenes so that character name -> ID resolution in scene_characters works) ---
   for (const file of scanFiles) {
+    if (isReferenceFile(syncDir, file)) {
+      try {
+        const { data, content } = parseFile(file);
+        const docId = indexReferenceFile(db, syncDir, file, data, content);
+        indexedReferenceDocIds.add(docId);
+      } catch (err) {
+        process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
+      }
+      continue;
+    }
+
     if (!isWorldFile(syncDir, file)) continue;
     try {
       const { meta } = readMeta(file, syncDir, { writable });
@@ -667,9 +867,13 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     }
   }
 
+  if (canPruneReferenceDocs(syncDir)) {
+    pruneMissingReferenceDocs(db, indexedReferenceDocIds);
+  }
+
   // --- Pass 2: scene files ---
   for (const file of scanFiles) {
-    if (isWorldFile(syncDir, file)) continue;
+    if (isWorldFile(syncDir, file) || isReferenceFile(syncDir, file)) continue;
     try {
       const { meta, sourceMeta, sidecarGenerated, derived, mismatches } = readMeta(file, syncDir, { writable });
       if (sidecarGenerated) sidecarsMigrated++;

package/src/tools/search.js

@@ -424,6 +424,67 @@ export function registerSearchTools(s, {
     }
   );
 
+  // ---- search_reference ----------------------------------------------------
+  s.tool(
+    "search_reference",
+    "Full-text search across indexed reference document titles, summaries, and tags. Use this to discover world-building notes, continuity references, research docs, and other reference material without loading full file contents.",
+    {
+      query: z.string().describe("Search terms (e.g. 'vampirism' or 'blood replacement'). FTS5 syntax supported."),
+      type: z.string().optional().describe("Optional reference type filter (for example: 'world', 'continuity', 'research', 'style')."),
+      tag: z.string().optional().describe("Optional exact tag filter."),
+    },
+    async ({ query, type, tag }) => {
+      let matchRows;
+      try {
+        matchRows = db.prepare(`
+          SELECT doc_id, rank
+          FROM reference_docs_fts
+          WHERE reference_docs_fts MATCH ?
+          ORDER BY rank
+        `).all(query);
+      } catch (err) {
+        return errorResponse("INVALID_QUERY", "Invalid reference search query syntax. Use plain keywords or quoted phrases.", { detail: err.message });
+      }
+
+      if (matchRows.length === 0) {
+        return errorResponse("NO_RESULTS", "No reference documents matched the search query.");
+      }
+
+      const rows = [];
+      const docStmt = db.prepare(`
+        SELECT doc_id, project_id, universe_id, type, title, summary, file_path
+        FROM reference_docs
+        WHERE doc_id = ?
+      `);
+      const tagsStmt = db.prepare(`
+        SELECT tag
+        FROM reference_doc_tags
+        WHERE doc_id = ?
+        ORDER BY tag
+      `);
+
+      for (const match of matchRows) {
+        const doc = docStmt.get(match.doc_id);
+        if (!doc) continue;
+
+        const tags = tagsStmt.all(match.doc_id).map(row => row.tag);
+        if (type && doc.type !== type) continue;
+        if (tag && !tags.includes(tag)) continue;
+
+        rows.push({
+          ...doc,
+          tags,
+        });
+      }
+
+      if (rows.length === 0) {
+        return errorResponse("NO_RESULTS", "No reference documents matched the provided filters.");
+      }
+
+      return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+    }
+  );
+
   // ---- list_threads --------------------------------------------------------
   s.tool(
     "list_threads",