@hanna84/mcp-writing 2.16.2 → 2.17.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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.17.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.16.2...v2.17.0)
+
+- feat(reference): persist explicit links to source metadata [`#161`](https://github.com/hannasdev/mcp-writing.git
+/pull/161)
+
 #### [v2.16.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.16.1...v2.16.2)
 
+> 1 May 2026
+
 - docs(prd): refresh reference-doc status and Phase 4C plan [`#160`](https://github.com/hannasdev/mcp-writing.git
 /pull/160)
+- Release 2.16.2 [`db02dcf`](https://github.com/hannasdev/mcp-writing.git
+/commit/db02dcfe3d854ba2c79c072ab93f73d8ab69527c)
 
 #### [v2.16.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.16.0...v2.16.1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.16.2",
+  "version": "2.17.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/sync/sync.js

@@ -281,6 +281,50 @@ export function normalizeReferenceIdList(values) {
   )];
 }
 
+function normalizeReferenceRelation(value, fallbackRelation) {
+  const normalized = String(value ?? fallbackRelation ?? "").trim().toLowerCase();
+  if (/^[a-z][a-z0-9_-]*$/.test(normalized)) return normalized;
+  return String(fallbackRelation ?? "related").trim().toLowerCase();
+}
+
+export function normalizeReferenceLinkList(values, { defaultRelation = "related" } = {}) {
+  const rawValues = Array.isArray(values)
+    ? values
+    : typeof values === "string"
+      ? values.split(",")
+      : [];
+
+  const links = [];
+  for (const value of rawValues) {
+    if (typeof value === "string") {
+      const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+      for (const targetDocId of parts) {
+        links.push({ targetDocId, relation: normalizeReferenceRelation(defaultRelation, defaultRelation) });
+      }
+      continue;
+    }
+
+    if (!value || typeof value !== "object") continue;
+    const targetDocId = String(value.target_doc_id ?? value.doc_id ?? value.id ?? "").trim();
+    if (!targetDocId) continue;
+    links.push({
+      targetDocId,
+      relation: normalizeReferenceRelation(value.relation, defaultRelation),
+    });
+  }
+
+  const deduped = [];
+  const seen = new Set();
+  for (const link of links) {
+    const key = `${link.targetDocId}::${link.relation}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(link);
+  }
+
+  return deduped;
+}
+
 export function deriveReferenceSummary(meta = {}, content = "") {
   if (typeof meta.summary === "string" && meta.summary.trim()) return meta.summary.trim();
 
@@ -340,6 +384,59 @@ function indexReferenceLinksForSource(db, {
   }
 }
 
+function indexExplicitReferenceLinksForSource(db, {
+  sourceKind,
+  sourceProjectId = "",
+  sourceId,
+  links,
+  defaultRelation,
+}) {
+  db.prepare(`
+    DELETE FROM reference_links
+    WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND origin = 'explicit'
+  `).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, origin
+    ) VALUES (?, ?, ?, ?, ?, 'explicit')
+  `);
+
+  for (const link of links) {
+    if (sourceKind === "reference" && sourceId === link.targetDocId) continue;
+    insertReferenceLink.run(
+      sourceKind,
+      sourceProjectId,
+      sourceId,
+      link.targetDocId,
+      normalizeReferenceRelation(link.relation, defaultRelation)
+    );
+  }
+}
+
+function collectExplicitReferenceLinks(meta, fields, { defaultRelation }) {
+  const hasField = fields.some((field) => Object.prototype.hasOwnProperty.call(meta, field));
+  if (!hasField) {
+    return { hasField: false, links: [] };
+  }
+
+  const rawValues = [];
+  for (const field of fields) {
+    if (!Object.prototype.hasOwnProperty.call(meta, field)) continue;
+    const value = meta[field];
+    if (Array.isArray(value)) {
+      rawValues.push(...value);
+    } else if (value !== undefined && value !== null) {
+      rawValues.push(value);
+    }
+  }
+
+  return {
+    hasField: true,
+    links: normalizeReferenceLinkList(rawValues, { defaultRelation }),
+  };
+}
+
 export function worldEntityKindForPath(syncDir, filePath) {
   const rel = path.relative(syncDir, filePath);
   if (rel.includes(`${path.sep}characters${path.sep}`) || rel.includes("/characters/")) return "character";
@@ -643,6 +740,11 @@ export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
   const relatedReferenceIds = normalizeReferenceIdList(
     meta.related_reference_ids ?? meta.related_references ?? meta.related_docs ?? meta.related
   );
+  const explicitReferenceLinks = collectExplicitReferenceLinks(
+    meta,
+    ["reference_links", "related_reference_links", "explicit_reference_links"],
+    { defaultRelation: "related" }
+  );
 
   db.prepare(`
     INSERT INTO reference_docs (doc_id, project_id, universe_id, type, title, summary, file_path)
@@ -681,6 +783,16 @@ export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
     tags.join(" ")
   );
 
+  if (explicitReferenceLinks.hasField) {
+    indexExplicitReferenceLinksForSource(db, {
+      sourceKind: "reference",
+      sourceProjectId: project_id ?? "",
+      sourceId: docId,
+      links: explicitReferenceLinks.links,
+      defaultRelation: "related",
+    });
+  }
+
   indexReferenceLinksForSource(db, {
     sourceKind: "reference",
     sourceProjectId: project_id ?? "",
@@ -798,6 +910,11 @@ function pruneMissingScenes(db, seenSceneKeys, syncDir) {
 export function indexSceneFile(db, syncDir, file, meta, prose) {
   const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
   const referenceIds = normalizeReferenceIdList(meta.reference_ids ?? meta.references);
+  const explicitSceneLinks = collectExplicitReferenceLinks(
+    meta,
+    ["reference_links", "explicit_reference_links"],
+    { defaultRelation: "informs" }
+  );
 
   if (universe_id) {
     db.prepare(`INSERT OR IGNORE INTO universes (universe_id, name) VALUES (?, ?)`).run(
@@ -922,6 +1039,16 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     keywordTokens,
   );
 
+  if (explicitSceneLinks.hasField) {
+    indexExplicitReferenceLinksForSource(db, {
+      sourceKind: "scene",
+      sourceProjectId: project_id ?? "",
+      sourceId: meta.scene_id,
+      links: explicitSceneLinks.links,
+      defaultRelation: "informs",
+    });
+  }
+
   indexReferenceLinksForSource(db, {
     sourceKind: "scene",
     sourceProjectId: project_id ?? "",

package/src/tools/metadata.js

@@ -1,9 +1,79 @@
 import { z } from "zod";
 import fs from "node:fs";
 import matter from "gray-matter";
-import { readMeta, writeMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
+import { readMeta, writeMeta, indexSceneFile, normalizeSceneMetaForPath, normalizeReferenceLinkList } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 
+function upsertSerializedReferenceLinks(existing, targetDocId, relation, { defaultRelation }) {
+  const normalized = normalizeReferenceLinkList(existing ?? [], { defaultRelation });
+  const filtered = normalized.filter((entry) => entry.targetDocId !== targetDocId);
+  filtered.push({ targetDocId, relation });
+  return filtered.map((entry) => ({
+    target_doc_id: entry.targetDocId,
+    relation: entry.relation,
+  }));
+}
+
+function persistSceneReferenceLink({ scenePath, syncDir, targetDocId, relation }) {
+  const { meta } = readMeta(scenePath, syncDir, { writable: true });
+  const existingExplicit = [
+    ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
+    ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
+  ];
+  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
+    defaultRelation: "informs",
+  });
+
+  const nextMeta = {
+    ...meta,
+    reference_links: nextReferenceLinks,
+  };
+  delete nextMeta.explicit_reference_links;
+
+  if (relation === "informs") {
+    const existingIds = Array.isArray(meta.reference_ids)
+      ? meta.reference_ids
+      : typeof meta.reference_ids === "string"
+        ? meta.reference_ids.split(",")
+        : [];
+    nextMeta.reference_ids = [...new Set([...existingIds.map((value) => String(value).trim()).filter(Boolean), targetDocId])];
+  }
+
+  writeMeta(scenePath, nextMeta);
+}
+
+function persistReferenceDocLink({ filePath, targetDocId, relation }) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = matter(raw);
+  const data = parsed.data ?? {};
+  const existingExplicit = [
+    ...(Array.isArray(data.reference_links) ? data.reference_links : data.reference_links ? [data.reference_links] : []),
+    ...(Array.isArray(data.related_reference_links) ? data.related_reference_links : data.related_reference_links ? [data.related_reference_links] : []),
+    ...(Array.isArray(data.explicit_reference_links) ? data.explicit_reference_links : data.explicit_reference_links ? [data.explicit_reference_links] : []),
+  ];
+  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
+    defaultRelation: "related",
+  });
+
+  const nextData = {
+    ...data,
+    reference_links: nextReferenceLinks,
+  };
+  delete nextData.related_reference_links;
+  delete nextData.explicit_reference_links;
+
+  if (relation === "related") {
+    const existingIds = Array.isArray(data.related_reference_ids)
+      ? data.related_reference_ids
+      : typeof data.related_reference_ids === "string"
+        ? data.related_reference_ids.split(",")
+        : [];
+    nextData.related_reference_ids = [...new Set([...existingIds.map((value) => String(value).trim()).filter(Boolean), targetDocId])];
+  }
+
+  fs.writeFileSync(filePath, matter.stringify(parsed.content, nextData), "utf8");
+}
+
 export function registerMetadataTools(s, {
   db,
   SYNC_DIR,
@@ -205,10 +275,12 @@ export function registerMetadataTools(s, {
       }
 
       let resolvedSourceProjectId;
+      let sourceScenePath = null;
+      let sourceReferencePath = null;
       if (source_kind === "scene") {
         if (source_project_id) {
           const scene = db.prepare(`
-            SELECT scene_id, project_id
+            SELECT scene_id, project_id, file_path
             FROM scenes
             WHERE scene_id = ? AND project_id = ?
             LIMIT 1
@@ -217,9 +289,10 @@ export function registerMetadataTools(s, {
             return errorResponse("NOT_FOUND", `Scene '${source_id}' not found in project '${source_project_id}'.`);
           }
           resolvedSourceProjectId = scene.project_id ?? "";
+          sourceScenePath = scene.file_path;
         } else {
           const matches = db.prepare(`
-            SELECT scene_id, project_id
+            SELECT scene_id, project_id, file_path
             FROM scenes
             WHERE scene_id = ?
             ORDER BY project_id
@@ -235,10 +308,11 @@ export function registerMetadataTools(s, {
             );
           }
           resolvedSourceProjectId = matches[0].project_id ?? "";
+          sourceScenePath = matches[0].file_path;
         }
       } else {
         const sourceDoc = db.prepare(`
-          SELECT doc_id, project_id
+          SELECT doc_id, project_id, file_path
           FROM reference_docs
           WHERE doc_id = ?
           LIMIT 1
@@ -267,6 +341,45 @@ export function registerMetadataTools(s, {
             }
           );
         }
+        sourceReferencePath = sourceDoc.file_path;
+      }
+
+      try {
+        if (source_kind === "scene") {
+          if (!sourceScenePath) {
+            return errorResponse("STALE_PATH", `Scene '${source_id}' has no indexed file path. Run sync() to refresh.`, {
+              source_id,
+              source_project_id: resolvedSourceProjectId,
+            });
+          }
+          persistSceneReferenceLink({
+            scenePath: sourceScenePath,
+            syncDir: SYNC_DIR,
+            targetDocId: target_doc_id,
+            relation: normalizedRelation,
+          });
+        } else {
+          if (!sourceReferencePath) {
+            return errorResponse("STALE_PATH", `Reference doc '${source_id}' has no indexed file path. Run sync() to refresh.`, {
+              source_id,
+            });
+          }
+          persistReferenceDocLink({
+            filePath: sourceReferencePath,
+            targetDocId: target_doc_id,
+            relation: normalizedRelation,
+          });
+        }
+      } catch (err) {
+        if (err?.code === "ENOENT") {
+          const indexedPath = source_kind === "scene" ? sourceScenePath : sourceReferencePath;
+          return errorResponse(
+            "STALE_PATH",
+            `Source file for ${source_kind} '${source_id}' not found at indexed path — run sync() to refresh.`,
+            { indexed_path: indexedPath }
+          );
+        }
+        return errorResponse("IO_ERROR", `Failed to persist link metadata: ${err.message}`);
       }
 
       try {