loopctl-mcp-server 2.112.0 → 2.113.0

package/index.js

@@ -15,6 +15,7 @@ import os from "node:os";
 import crypto from "node:crypto";
 import path from "node:path";
 import { applyArgAliases } from "./lib/arg-aliases.js";
+import { articleId } from "./lib/article-id.js";
 import { clientContextHeader } from "./lib/client-context.js";
 import { resolveClaimSessionId } from "./lib/claim-session.js";
 import { degradedSearchNotice } from "./lib/search-notices.js";
@@ -1668,8 +1669,10 @@ async function knowledgeStats({ project_id }) {
 }
 
 async function knowledgeGraph({ article_id, depth, project_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
-  params.set("article_id", article_id);
+  params.set("article_id", art.id);
   if (depth != null) params.set("depth", String(depth));
   if (project_id) params.set("project_id", project_id);
   const result = await apiCall(
@@ -1682,11 +1685,13 @@ async function knowledgeGraph({ article_id, depth, project_id }) {
 }
 
 async function knowledgeSuggestLinks({ article_id, limit, threshold }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   if (limit != null) params.set("limit", String(limit));
   if (threshold != null) params.set("threshold", String(threshold));
   const qs = params.toString();
-  const base = `/api/v1/knowledge/articles/${article_id}/suggested_links`;
+  const base = `/api/v1/knowledge/articles/${art.id}/suggested_links`;
   const result = await apiCall(
     "GET",
     qs ? `${base}?${qs}` : base,
@@ -1871,6 +1876,8 @@ async function knowledgeHeatIndex({ category, limit, since }) {
 }
 
 async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offset }) {
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   // 0 is meaningful on both (whole body / start at the beginning), so test for
   // null/undefined rather than truthiness.
@@ -1879,7 +1886,7 @@ async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offs
   if (body_offset !== undefined && body_offset !== null)
     params.set("body_offset", String(body_offset));
   const qs = params.toString();
-  const base = `/api/v1/knowledge/progressive/${article_id}`;
+  const base = `/api/v1/knowledge/progressive/${art.id}`;
   const result = await apiCall(
     "GET",
     qs ? `${base}?${qs}` : base,
@@ -1942,6 +1949,11 @@ async function knowledgeGet({
   body_max_bytes,
   body_offset,
 }) {
+  // A missing id went out as /undefined and a malformed one as whatever it spelled
+  // ('', '#', '..', 'x?y' each reach a different route); the server's answer read as
+  // "this article does not exist". Refused here with status 0, before any request.
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
@@ -1953,7 +1965,7 @@ async function knowledgeGet({
   if (body_offset !== undefined && body_offset !== null)
     params.set("body_offset", String(body_offset));
   const qs = params.toString();
-  const path = qs ? `/api/v1/articles/${article_id}?${qs}` : `/api/v1/articles/${article_id}`;
+  const path = qs ? `/api/v1/articles/${art.id}?${qs}` : `/api/v1/articles/${art.id}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
@@ -2031,6 +2043,8 @@ async function knowledgeCreate({
 // provided fields change. Agent role — KB-content curation, visibility-scoped
 // server-side (another agent's private/owner memory 404s).
 async function knowledgeUpdate({ article_id, title, body, category, tags, metadata }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const payload = {};
   if (title != null) payload.title = title;
   if (body != null) payload.body = body;
@@ -2040,7 +2054,7 @@ async function knowledgeUpdate({ article_id, title, body, category, tags, metada
 
   const result = await apiCall(
     "PATCH",
-    `/api/v1/articles/${article_id}`,
+    `/api/v1/articles/${art.id}`,
     payload,
     process.env.LOOPCTL_AGENT_KEY,
   );
@@ -2231,7 +2245,9 @@ async function memoryGraduate({ memory_id, re_scope }) {
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
-  const result = await apiCall("POST", `/api/v1/articles/${article_id}/publish`, null, process.env.LOOPCTL_ORCH_KEY);
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
+  const result = await apiCall("POST", `/api/v1/articles/${art.id}/publish`, null, process.env.LOOPCTL_ORCH_KEY);
   return toContent(result);
 }
 
@@ -2286,9 +2302,11 @@ async function knowledgeBulkUnpublish({ article_ids }) {
 }
 
 async function knowledgeUnpublish({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/unpublish`,
+    `/api/v1/articles/${art.id}/unpublish`,
     null,
     process.env.LOOPCTL_USER_KEY
   );
@@ -2299,9 +2317,11 @@ async function knowledgeUnpublish({ article_id }) {
 // audited, visibility-scoped server-side). NOT reversible in code — #606/#605: `:archived`
 // is a terminal status. The row survives; nothing automated brings it back.
 async function knowledgeArchive({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/archive`,
+    `/api/v1/articles/${art.id}/archive`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2312,9 +2332,11 @@ async function knowledgeArchive({ article_id }) {
 // one member of that family that undoes: nothing is destroyed and nothing is rebuilt, so
 // knowledge_unsuppress restores the article to every read path immediately.
 async function knowledgeSuppress({ article_id, reason }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/suppress`,
+    `/api/v1/articles/${art.id}/suppress`,
     { reason },
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2322,9 +2344,11 @@ async function knowledgeSuppress({ article_id, reason }) {
 }
 
 async function knowledgeUnsuppress({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/unsuppress`,
+    `/api/v1/articles/${art.id}/unsuppress`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2333,9 +2357,11 @@ async function knowledgeUnsuppress({ article_id }) {
 
 // #331: soft-delete (archive) is agent-role KB curation, same as knowledge_archive.
 async function knowledgeDelete({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "DELETE",
-    `/api/v1/articles/${article_id}`,
+    `/api/v1/articles/${art.id}`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2812,9 +2838,11 @@ async function knowledgeCurationLog({ kind, since, limit, offset } = {}) {
 }
 
 async function knowledgeArticleStats({ article_id }) {
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "GET",
-    `/api/v1/knowledge/articles/${article_id}/stats`,
+    `/api/v1/knowledge/articles/${art.id}/stats`,
     null,
     process.env.LOOPCTL_ORCH_KEY
   );
@@ -5542,7 +5570,8 @@ const TOOLS = [
         article_id: {
           type: "string",
           format: "uuid",
-          description: "Starting article UUID (required).",
+          description:
+            "Starting article UUID (required). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         depth: {
           type: "integer",
@@ -5575,7 +5604,8 @@ const TOOLS = [
         article_id: {
           type: "string",
           format: "uuid",
-          description: "The article to suggest links for (required).",
+          description:
+            "The article to suggest links for (required). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         limit: { type: "integer", description: "Max candidates (default 5)." },
         threshold: {
@@ -5925,8 +5955,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          format: "uuid",
-          description: "The UUID of the article to open (from a progressive index stub).",
+          description:
+            "The UUID of the article to open (from a progressive index stub). Or a prefix of at least 8 hex digits (the server matches its first 8). A missing, blank, shorter or non-hex value is refused locally with status 0 and no request is sent.",
         },
         body_max_bytes: {
           type: "integer",
@@ -5985,7 +6015,10 @@ const TOOLS = [
           description:
             "The UUID of the article. A unique ID PREFIX (>= 8 hex characters) also " +
             "resolves, so copy what you have rather than reconstructing 36 characters " +
-            "from memory; an ambiguous prefix is a 404, never a guess.",
+            "from memory; an ambiguous prefix is a 404, never a guess. The server matches a " +
+            "prefix on its first 8 hex digits only. Surrounding whitespace is trimmed. A " +
+            "missing or blank id, fewer than 8 hex digits, or any character other than hex " +
+            "digits and dashes is refused locally with status 0 and no request is sent.",
         },
         links: {
           type: "string",
@@ -6232,7 +6265,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to edit (preserved across the update).",
+          description:
+            "The UUID of the article to edit (preserved across the update). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         title: {
           type: "string",
@@ -6610,7 +6644,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the draft article to publish.",
+          description:
+            "The UUID of the draft article to publish. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6678,7 +6713,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the published article to unpublish.",
+          description:
+            "The UUID of the published article to unpublish. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6701,7 +6737,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to archive.",
+          description:
+            "The UUID of the article to archive. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6736,7 +6773,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to take out of retrieval.",
+          description:
+            "The UUID of the article to take out of retrieval. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         reason: {
           type: "string",
@@ -6764,7 +6802,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to restore to retrieval.",
+          description:
+            "The UUID of the article to restore to retrieval. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6786,7 +6825,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to delete.",
+          description:
+            "The UUID of the article to delete. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -8092,7 +8132,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to inspect.",
+          description:
+            "The UUID of the article to inspect. Or a prefix of at least 8 hex digits (the server matches its first 8). A missing, blank, shorter or non-hex value is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -9904,6 +9945,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       );
     },
     declaredToolArgs(name),
+    name,
   );
 
   switch (name) {

package/lib/arg-aliases.js

@@ -66,8 +66,26 @@ const ARG_ALIASES = {
   limit: ["max_results"],
 };
 
+// TOOL-SCOPED aliases, keyed by tool name, applied only when the called tool declares the
+// canonical and not the alias. `id` cannot go in the global table above: memory_forget and
+// others declare `id` as their own parameter, and the drift guard refuses it there.
+//
+// `article_id <- id` on knowledge_get is measured: 17 of 96 knowledge_get calls in mac-mini's
+// session transcripts (2026-10-01) passed `{"id": ...}`, the key every search result carries
+// its id under, and the request went out as `/api/v1/articles/undefined`. All 30
+// knowledge_get 404s in production for 2026-09-25..30 were that request.
+// knowledge_progressive_drill is the same mechanism: its documented input is a progressive
+// index stub, which carries the id under the same `id` key. A write verb never joins: there
+// the alias would turn a harmless miss into a write against an id copied from the wrong row.
+const TOOL_SCOPED_ALIASES = {
+  knowledge_get: { article_id: ["id"] },
+  knowledge_progressive_drill: { article_id: ["id"] },
+};
+
+// Whitespace-only is blank, matching articleId(), which trims: otherwise a "  " article_id
+// blocks the rescue here and is then refused as missing there, discarding a good `id`.
 function isBlank(v) {
-  return v === undefined || v === null || v === "";
+  return v === undefined || v === null || (typeof v === "string" && v.trim() === "");
 }
 
 /**
@@ -78,8 +96,11 @@ function isBlank(v) {
  * supplied, only a fill of a declared key is reported as a rescue — the rest are inert
  * conveniences. Omit it and every fill is reported (the conservative default for a tool
  * whose schema is not known, e.g. the per-tenant `cr_*` tools).
+ *
+ * `toolName` selects that tool's TOOL_SCOPED_ALIASES, which apply only when BOTH `declared`
+ * and `toolName` are given.
  */
-function applyArgAliases(args, onAliasUsed, declared) {
+function applyArgAliases(args, onAliasUsed, declared, toolName) {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
 
   const out = { ...args };
@@ -109,6 +130,24 @@ function applyArgAliases(args, onAliasUsed, declared) {
     }
   }
 
+  const scoped =
+    declaredSet !== null && toolName && Object.hasOwn(TOOL_SCOPED_ALIASES, toolName)
+      ? TOOL_SCOPED_ALIASES[toolName]
+      : {};
+  for (const [canonical, aliases] of Object.entries(scoped)) {
+    if (!declaredSet.has(canonical) || !isBlank(out[canonical])) continue;
+    const alias = aliases.find((a) => !declaredSet.has(a) && !isBlank(out[a]));
+    if (alias === undefined) continue;
+    out[canonical] = out[alias];
+    if (typeof onAliasUsed === "function") {
+      try {
+        onAliasUsed({ canonical, alias });
+      } catch {
+        // Telemetry must never break a tool call.
+      }
+    }
+  }
+
   // Some callers send a numeric arg as a string ("6"). Coerce so downstream validation and
   // the outbound query string both see a number rather than rejecting or double-encoding.
   if (typeof out.limit === "string" && /^\d+$/.test(out.limit.trim())) {
@@ -118,4 +157,4 @@ function applyArgAliases(args, onAliasUsed, declared) {
   return out;
 }
 
-export { ARG_ALIASES, applyArgAliases };
+export { ARG_ALIASES, TOOL_SCOPED_ALIASES, applyArgAliases };

package/lib/article-id.js

@@ -0,0 +1,17 @@
+/**
+ * An `article_id` bound for a URL path or query: trimmed (an id pasted with a trailing newline
+ * is the id), then held to the shared `uuid()` check in lib/delivery-loop.js. Returns `{ id }`
+ * to send, or `{ refusal }` (status 0, value never echoed).
+ *
+ * The reads whose server path resolves an id prefix (#652: knowledge_get,
+ * knowledge_progressive_drill, knowledge_article_stats) pass `{ prefix: true }`; every other
+ * article verb takes a full UUID. A missing id used to go out as `/undefined` and come back as
+ * a 404 that agents read as "the article does not exist".
+ */
+import { uuid } from "./delivery-loop.js";
+
+export function articleId(value, { prefix = false } = {}) {
+  const trimmed = typeof value === "string" ? value.trim() : value;
+  const refusal = uuid(trimmed, "article_id", { prefix });
+  return refusal ? { refusal } : { id: trimmed };
+}

package/lib/delivery-loop.js

@@ -48,7 +48,9 @@ function refuse(body) {
 }
 
 /**
- * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`.
+ * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`
+ * here, and `article_id` on the knowledge verbs through `lib/article-id.js` (which adds the
+ * `prefix` grammar its reads accept).
  *
  * EXPORTED, because it is one check and not a pattern to copy. `update_story`
  * (`lib/story-update.js`) interpolates a `story_id` into a path exactly as the verbs below do
@@ -111,15 +113,30 @@ function refuse(body) {
  * into the transcript.
  */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function uuid(value, field) {
-  if (typeof value !== "string" || value.trim() === "") {
+const PREFIX_RE = /^[0-9a-f-]+$/i;
+
+// `prefix: true` also accepts what the server's id-prefix fallback resolves (#652,
+// `Knowledge.id_prefix_range/1`, reached by knowledge_get, knowledge_progressive_drill and
+// knowledge_article_stats): hex digits and dashes with at least 8 hex digits, dashless or
+// partial. The server compares only the FIRST 8 hex digits and resolves when exactly one
+// article has them: the rest of a longer value is not checked, so a full-length id with a
+// wrong tail resolves to the article owning its first 8 (#652's design, for confabulated tails).
+// Only hex and dashes are accepted, so nothing in a prefix can change the route ('#', '?', '/').
+export function uuid(value, field, { prefix = false } = {}) {
+  if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
     return refuse(`\`${field}\` is required.`);
   }
 
+  if (typeof value !== "string") {
+    return refuse(`\`${field}\` must be a string; got a ${Array.isArray(value) ? "array" : typeof value}.`);
+  }
+
+  if (prefix && PREFIX_RE.test(value) && value.replace(/-/g, "").length >= 8) return null;
+
   if (!UUID_RE.test(value)) {
     return refuse(
-      `\`${field}\` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper). ` +
+      `\`${field}\` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper)` +
+        (prefix ? " or a prefix of at least 8 hex digits. " : ". ") +
         `Got a ${value.length}-character string that is not one. The value is not repeated ` +
         `here: a malformed id is often something pasted into the wrong argument, and a tool ` +
         `result lands in the transcript.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.112.0",
+  "version": "2.113.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",