@hanna84/mcp-writing 2.15.0 → 2.16.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.16.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.15.0...v2.16.0)
+
+- feat: add upsert_reference_link write tool [`#150`](https://github.com/hannasdev/mcp-writing.git
+/pull/150)
+
 #### [v2.15.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.14.0...v2.15.0)
 
+> 30 April 2026
+
 - feat(reference): add reference link query tools [`#148`](https://github.com/hannasdev/mcp-writing.git
 /pull/148)
+- Release 2.15.0 [`1b9ac11`](https://github.com/hannasdev/mcp-writing.git
+/commit/1b9ac11157f8385e85a0c6c86e30109e9b9b2220)
 
 #### [v2.14.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.13.0...v2.14.0)

package/package.json

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

@@ -124,6 +124,7 @@ export const SCHEMA = `
     source_id     TEXT NOT NULL,
     target_doc_id TEXT NOT NULL,
     relation      TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'inferred',
     PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
   );
 
@@ -274,6 +275,13 @@ const MIGRATIONS = [
         ON reference_links(target_doc_id);
     `);
   },
+  // 6: add origin marker to reference_links so sync can preserve explicit tool-authored links
+  (db) => {
+    const columns = db.prepare(`PRAGMA table_info(reference_links)`).all();
+    if (!columns.some(c => c.name === "origin")) {
+      db.exec(`ALTER TABLE reference_links ADD COLUMN origin TEXT NOT NULL DEFAULT 'inferred';`);
+    }
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —

package/src/sync/sync.js

@@ -305,18 +305,38 @@ function indexReferenceLinksForSource(db, {
 }) {
   db.prepare(`
     DELETE FROM reference_links
-    WHERE source_kind = ? AND source_project_id = ? AND source_id = ?
+    WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND origin = 'inferred'
   `).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 (?, ?, ?, ?, ?)
+    INSERT OR IGNORE INTO reference_links (
+      source_kind, source_project_id, source_id, target_doc_id, relation, origin
+    )
+    SELECT ?, ?, ?, ?, ?, 'inferred'
+    WHERE NOT EXISTS (
+      SELECT 1
+      FROM reference_links existing
+      WHERE existing.source_kind = ?
+        AND existing.source_project_id = ?
+        AND existing.source_id = ?
+        AND existing.target_doc_id = ?
+        AND existing.origin = 'explicit'
+    )
   `);
 
   for (const targetDocId of targetDocIds) {
     if (sourceKind === "reference" && sourceId === targetDocId) continue;
-    insertReferenceLink.run(sourceKind, sourceProjectId, sourceId, targetDocId, relation);
+    insertReferenceLink.run(
+      sourceKind,
+      sourceProjectId,
+      sourceId,
+      targetDocId,
+      relation,
+      sourceKind,
+      sourceProjectId,
+      sourceId,
+      targetDocId
+    );
   }
 }
 

package/src/tools/metadata.js

@@ -170,6 +170,141 @@ export function registerMetadataTools(s, {
     }
   );
 
+  // ---- upsert_reference_link -----------------------------------------------
+  s.tool(
+    "upsert_reference_link",
+    "Create or update an explicit reference link from a scene or reference doc to a target reference doc. If a link already exists between the same source and target, this updates the relation. Only available when the sync dir is writable.",
+    {
+      source_kind: z.enum(["scene", "reference"]).describe("Link source kind."),
+      source_id: z.string().describe("Source scene_id or reference doc_id."),
+      source_project_id: z.string().optional().describe("Optional project scope for the source. For scene sources, use this to disambiguate an ambiguous scene_id across projects. For reference sources, when provided, it is treated as an ownership check and must match the source reference doc's project."),
+      target_doc_id: z.string().describe("Target reference doc_id."),
+      relation: z.string().describe("Relationship label (for example: 'informs', 'related', 'history_of'). The value is trimmed and lowercased before validation."),
+    },
+    async ({ source_kind, source_id, source_project_id, target_doc_id, relation }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot write reference links: sync dir is read-only.");
+      }
+
+      const normalizedRelation = relation.trim().toLowerCase();
+      if (!/^[a-z][a-z0-9_-]*$/.test(normalizedRelation)) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          "Relation is normalized to lowercase and must match [a-z][a-z0-9_-]* after normalization (for example: 'informs' or 'history_of').",
+          { relation }
+        );
+      }
+
+      const targetDoc = db.prepare(`
+        SELECT doc_id
+        FROM reference_docs
+        WHERE doc_id = ?
+      `).get(target_doc_id);
+      if (!targetDoc) {
+        return errorResponse("NOT_FOUND", `Target reference doc '${target_doc_id}' not found.`);
+      }
+
+      let resolvedSourceProjectId;
+      if (source_kind === "scene") {
+        if (source_project_id) {
+          const scene = db.prepare(`
+            SELECT scene_id, project_id
+            FROM scenes
+            WHERE scene_id = ? AND project_id = ?
+            LIMIT 1
+          `).get(source_id, source_project_id);
+          if (!scene) {
+            return errorResponse("NOT_FOUND", `Scene '${source_id}' not found in project '${source_project_id}'.`);
+          }
+          resolvedSourceProjectId = scene.project_id ?? "";
+        } else {
+          const matches = db.prepare(`
+            SELECT scene_id, project_id
+            FROM scenes
+            WHERE scene_id = ?
+            ORDER BY project_id
+          `).all(source_id);
+          if (matches.length === 0) {
+            return errorResponse("NOT_FOUND", `Scene '${source_id}' not found.`);
+          }
+          if (matches.length > 1) {
+            return errorResponse(
+              "CONFLICT",
+              `Scene ID '${source_id}' exists in multiple projects. Provide source_project_id to disambiguate.`,
+              { source_id, project_ids: matches.map(row => row.project_id) }
+            );
+          }
+          resolvedSourceProjectId = matches[0].project_id ?? "";
+        }
+      } else {
+        const sourceDoc = db.prepare(`
+          SELECT doc_id, project_id
+          FROM reference_docs
+          WHERE doc_id = ?
+          LIMIT 1
+        `).get(source_id);
+        if (!sourceDoc) {
+          return errorResponse("NOT_FOUND", `Source reference doc '${source_id}' not found.`);
+        }
+        if (source_id === target_doc_id) {
+          return errorResponse("VALIDATION_ERROR", "Self-links are not allowed for reference sources.");
+        }
+        resolvedSourceProjectId = sourceDoc.project_id ?? "";
+        if ((source_project_id ?? "") !== "" && source_project_id !== resolvedSourceProjectId) {
+          const resolvedSourceProjectLabel = resolvedSourceProjectId === ""
+            ? "unscoped/no project"
+            : `project '${resolvedSourceProjectId}'`;
+          const requestedSourceProjectLabel = source_project_id === ""
+            ? "unscoped/no project"
+            : `project '${source_project_id}'`;
+          return errorResponse(
+            "CONFLICT",
+            `Source reference doc '${source_id}' belongs to ${resolvedSourceProjectLabel}, not ${requestedSourceProjectLabel}.`,
+            {
+              source_id,
+              source_project_id,
+              resolved_source_project_id: resolvedSourceProjectId,
+            }
+          );
+        }
+      }
+
+      try {
+        db.exec("BEGIN");
+        db.prepare(`
+          DELETE FROM reference_links
+          WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND target_doc_id = ?
+        `).run(source_kind, resolvedSourceProjectId, source_id, target_doc_id);
+
+        db.prepare(`
+          INSERT INTO reference_links (
+            source_kind, source_project_id, source_id, target_doc_id, relation, origin
+          ) VALUES (?, ?, ?, ?, ?, 'explicit')
+        `).run(source_kind, resolvedSourceProjectId, source_id, target_doc_id, normalizedRelation);
+        db.exec("COMMIT");
+      } catch (err) {
+        try {
+          db.exec("ROLLBACK");
+        } catch (rollbackErr) {
+          void rollbackErr;
+        }
+        throw err;
+      }
+
+      const link = db.prepare(`
+        SELECT source_kind, source_project_id, source_id, target_doc_id, relation, origin
+        FROM reference_links
+        WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND target_doc_id = ? AND relation = ?
+      `).get(source_kind, resolvedSourceProjectId, source_id, target_doc_id, normalizedRelation);
+
+      return jsonResponse({
+        ok: true,
+        action: "upserted",
+        link,
+      });
+    }
+  );
+
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",