loopctl-mcp-server 2.62.0 → 2.64.0

package/README.md

@@ -255,7 +255,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_progressive_index` | Progressive disclosure — a **cheap, capped index** of what's relevant to a topic (compact stubs: `id`/`title`/`category`/`summary`, **no bodies**), curated-preferred and hub-enriched, capped at top-K (`meta.truncated` when the pool exceeded it). Survey a topic without flooding context, then open only what you need via `knowledge_progressive_drill`. Required: `topic`. Optional: `category`, `limit`. |
 | `knowledge_progressive_drill` | Open one stub from `knowledge_progressive_index` — returns the **full article body** for the given id, scope-enforced. Resolves both tenant-owned articles and published system canonicals (the same set the index surfaces). Required: `article_id`. |
 | `knowledge_list` | List articles (`id`, `title`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, timestamps), filtered + paginated. **Body-less summary by default** (safe to page up to `limit=1000`); pass `include_body: true` to also return `body`, in which case the page is bounded by a ~5 MB byte budget — continue via `meta.next_offset` while `meta.has_more`. **Lag-free, all-status** read of the DB of record — unlike `knowledge_search` (ranked, published-only, lags writes) and `knowledge_index` (id/title/category only). The right tool to enumerate/dedup/repair and for idempotency/existence checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read `meta.total_count` (exact). Single full body → `knowledge_get`; relevant bodies → `knowledge_context`; bulk dump → `knowledge_export`. Optional: `project_id`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, `offset`, `limit`, `include_body`. |
-| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Optional: `project_id`, `story_id` for attribution. |
+| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Each link carries only its FAR side (`article: {id, title}`, plus `similarity` when scored); both arrays are ranked (open conflicts first, then descending similarity, then oldest-first for the unscored) and capped at 25 per direction, with `links_total` / `links_truncated` reporting the truth (`count` returns both, so one cheap call tells you whether the full fetch is capped). Pass `links: "count"` or `"none"` when you only want the text — on a well-linked hub the link block is several times the body. `potential_conflicts` is returned in all three modes, itself capped at 25 with `conflicts_total` / `conflicts_truncated`. Optional: `links`, `project_id`, `story_id` for attribution. |
 | `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. **Agent-memory scoping**: `memory_types` (comma-separated, OR — observation/finding/summary/decision/question/task), `agents` (comma-separated agent_ids, OR), `conversation_id` (exact) filter on article `metadata` (JSONB `@>`). Optional: `project_id`, `story_id` for attribution, `limit`, `recency_weight`. |
 | `knowledge_graph` | Multi-hop traversal of the published article-link graph from `article_id` (depth 1–3, default 1), **bounded to agent's visible articles**. Agent callers see only their own and `shared` articles. Bidirectional, cycle-safe, bounded to 100 nodes / 500 edges (`truncated` flags a cap). Returns `nodes` (`id`/`title`/`category`/`depth`) + `edges` (`source_article_id`/`target_article_id`/`relationship_type`). Explore typed connections beyond `knowledge_context`'s 1-hop links. Required: `article_id`. Optional: `depth`, `project_id`. |
 | `knowledge_suggest_links` | Ranked typed-link **candidates** for an article by embedding similarity among **visible articles** — **read-only** (creates nothing). Excludes the article itself + any already-linked article (either direction, any type); only embedded published articles visible to the caller. Agent callers see only their own and `shared` articles. Returns `{id, title, category, similarity_score}` highest-first, to create as a **typed** link (relates_to/derived_from/contradicts/supersedes). Required: `article_id`. Optional: `threshold` (cosine floor 0–1, default 0.5), `limit` (default 5). |
@@ -323,7 +323,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_article_stats` | Per-article usage stats: total accesses, unique agents, by-type breakdown, recent events. Required: `article_id`. |
 | `knowledge_agent_usage` | Per-agent knowledge usage: total reads, unique articles, top read articles. Required: exactly one of `api_key_id` (credential) or `agent_id` (logical identity). Optional: `limit`, `since_days`. See Wiki Attribution section. |
 | `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
-| `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
+| `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`/`gate_skip`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
 | `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of search results the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
 
 ### Egress / Privacy Tools (US-41.4)

package/index.js

@@ -1461,10 +1461,11 @@ async function knowledgeList({
   return toContent(result);
 }
 
-async function knowledgeGet({ article_id, project_id, story_id }) {
+async function knowledgeGet({ article_id, project_id, story_id, links }) {
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
+  if (links) params.set("links", links);
   const qs = params.toString();
   const path = qs ? `/api/v1/articles/${article_id}?${qs}` : `/api/v1/articles/${article_id}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
@@ -1504,6 +1505,7 @@ async function knowledgeCreate({
   project_id,
   draft,
   force,
+  skip_low_novelty,
   source_type,
   source_id,
   idempotency_key,
@@ -1525,8 +1527,10 @@ async function knowledgeCreate({
   if (draft) payload.draft = true;
 
   // The server-side novelty gate dedups the proposal against the corpus (verdict in
-  // the response `gate`). force:true bypasses it.
+  // the response `gate`). force:true bypasses it; skip_low_novelty:true drops a
+  // high-overlap proposal instead of banking it as a draft. Mutually exclusive (422).
   if (force) payload.force = true;
+  if (skip_low_novelty) payload.skip_low_novelty = true;
 
   const result = await apiCall(
     "POST",
@@ -4508,7 +4512,20 @@ const TOOLS = [
       "material to your current task, act on it: read the peer, judge redundant/complementary/" +
       "contradictory against the live system, and knowledge_resolve_conflict (dismiss a false " +
       "positive, supersede when one clearly wins, merge when both should combine). If you can't " +
-      "tell which is right, leave it. See the 'Resolving knowledge conflicts' wiki playbook.",
+      "tell which is right, leave it. See the 'Resolving knowledge conflicts' wiki playbook.\n\n" +
+      "LINKS: each link carries only its FAR side as `article: {id, title}` (plus " +
+      "`similarity` when the auto-linker scored it) — direction is already given by which " +
+      "array it is in. Both arrays are ranked (open conflicts first, then descending " +
+      "similarity, then oldest-first for the unscored) and capped at 25 per direction; " +
+      "read `links_total` for the true count and `links_truncated` to know the cap bit — " +
+      "both are returned by links: 'count' too, so one cheap call tells you whether the " +
+      "full fetch is even complete. When you only want the article's TEXT, " +
+      "pass links: 'count' (or 'none') — on a well-linked hub the link block is several " +
+      "times the size of the body, and you are paying for it on every read. " +
+      "`potential_conflicts` is returned in all three modes, so opting out of the link " +
+      "list never hides a conflict from you; it is capped at 25 (strongest first) with " +
+      "`conflicts_total` / `conflicts_truncated`. To actually traverse the graph, use " +
+      "knowledge_graph rather than raising this cap.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4517,6 +4534,15 @@ const TOOLS = [
           format: "uuid",
           description: "The UUID of the article.",
         },
+        links: {
+          type: "string",
+          enum: ["full", "count", "none"],
+          description:
+            "Optional: how much of the link graph to return. 'full' (default) = ranked, " +
+            "capped arrays; 'count' = just links_total + links_truncated; 'none' = omit " +
+            "link fields. potential_conflicts (capped, with conflicts_total) is always " +
+            "returned.",
+        },
         project_id: {
           type: "string",
           format: "uuid",
@@ -4601,7 +4627,9 @@ const TOOLS = [
       "so NOTHING was created (HTTP 200, `deduplicated: true`); read/update the article at `data.id` " +
       "instead (its `gate.similarity` ~1.0). `gated_to_draft` means high overlap, so the article was " +
       "created as a DRAFT (not published) with the near-neighbors in metadata.proposal_novelty for you " +
-      "to merge or publish. `created` means it was novel and went through normally. Pass force: true to " +
+      "to merge or publish — unless you passed skip_low_novelty: true, in which case the verdict is " +
+      "`skipped_low_novelty` and NOTHING was created (HTTP 200, `skipped: true`, `data: null`). " +
+      "`created` means it was novel and went through normally. Pass force: true to " +
       "bypass the gate when you intentionally want an article near an existing one. " +
       "Concurrency-safe: if a create races/retries against an " +
       "existing article with the same title AND an identical body (ignoring surrounding whitespace), the " +
@@ -4645,6 +4673,15 @@ const TOOLS = [
             "semantic dedup and creates on the requested path even if a near-duplicate exists. " +
             "Use only when you've already checked and intend an article close to an existing one.",
         },
+        skip_low_novelty: {
+          type: "boolean",
+          description:
+            "Optional: on high overlap, create NOTHING instead of staging a draft (default " +
+            "false → gated_to_draft). For an UNATTENDED writer with no reviewer behind it, " +
+            "whose gated drafts would pile up unresolved; you get verdict skipped_low_novelty " +
+            "with data:null. Mutually exclusive with force (422). An idempotency_key match or " +
+            "an exact title collision is still answered as a dedup/409, never dropped.",
+        },
         idempotency_key: {
           type: "string",
           description:
@@ -5905,7 +5942,7 @@ const TOOLS = [
     name: "knowledge_curation_log",
     description:
       "The concise, human-readable log of KB CURATION adjustments — novelty-gate decisions " +
-      "(gate_duplicate/gate_draft) and conflict resolutions (supersede/merge/dismiss) — for " +
+      "(gate_duplicate/gate_draft/gate_skip) and conflict resolutions (supersede/merge/dismiss) — for " +
       "analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry is a " +
       "one-liner: {at, kind, summary, refs, actor, confidence}. RECORDED ONLY while the tenant " +
       "has the toggle on: settings.kb_curation_log (flip via the admin tenant API, " +
@@ -5917,7 +5954,8 @@ const TOOLS = [
         kind: {
           type: "string",
           description:
-            "Optional: filter by kind (gate_duplicate | gate_draft | supersede | merge | dismiss).",
+            "Optional: filter by kind (gate_duplicate | gate_draft | gate_skip | supersede | merge | dismiss). " +
+            "gate_skip = a high-overlap proposal DISCARDED under skip_low_novelty (dropped, not stored).",
         },
         since: {
           type: "string",

package/package.json

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