loopctl-mcp-server 2.63.0 → 2.65.0

package/README.md

@@ -239,6 +239,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | Find by topic / relevance (ranked, published-only, lags writes) | `knowledge_search` |
 | One trustworthy answer + provenance (curated-first, retrieval fallback) | `knowledge_hybrid_search` |
 | Survey a topic cheaply (capped stubs) then open only what you need | `knowledge_progressive_index` + `knowledge_progressive_drill` |
+| A search came back empty/thin, or you don't yet know what to ask | `knowledge_heat_index` (no query at all) |
 | Enumerate / dedup / repair, or "does X exist?" (full fields, lag-free, all-status) | `knowledge_list` |
 
 | Tool | Description |
@@ -253,9 +254,10 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_search` | Search the knowledge wiki by topic (keyword, semantic, or combined). Returns snippets. **Ranked, published-only, and LAGS writes by minutes while embeddings index — do NOT use for existence/idempotency/dedup checks (a fresh write false-negatives); use `knowledge_list` for that.** `q` is optional when `tags`/`category` are supplied — that **list mode** returns the complete filtered set paginated via `offset`/`limit` over `meta.total_count`. `meta.total_count` is mode-dependent — read `meta.total_count_scope` (`keyword_matches`/`ranked_corpus`/`merged_candidates`/`filtered_set`) and don't use a relevance-mode count to size the wiki (use `knowledge_list` or `knowledge_stats`). Optional: `project_id`, `story_id` for attribution. |
 | `knowledge_hybrid_search` | Resolve a topic to a **single best answer with provenance** (US-31.4). Runs combined keyword+semantic over the full ranked pool, then decides whether a governed **curated** source actually answers. `meta.provenance` is `curated` (trust it — the canonical article is first in `data`, `meta.curated_article_id` points at it) or `retrieved` (best fuzzy match, `curated_article_id` null); `meta.confidence` is the winner's absolute score. Prefer over `knowledge_search` when you want one trustworthy answer, not a list to triage. Degrades to keyword-only like `knowledge_search` when embeddings are unavailable. Required: `query`. Optional: `project_id`, `category`, `tags`, `match`, `limit`, `offset`. |
 | `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_heat_index` | Browse the corpus with **no query at all** — capped compact stubs (`id`/`title`/`category`/`heat`/`summary`, **no bodies**) ranked by how many **distinct readers** (agents, not key rows — repeat reads by one reader count once, ties broken by the number of distinct days read, never by raw read count) opened each article inside a window. Every other retrieval tool starts from a query and so shares one failure mode: a paraphrase, or material topically central but lexically dissimilar to the question, comes back empty and reads as "the KB has nothing" rather than "I asked badly". Reach for it when a search came back empty or thin, or to survey what the fleet actually reads before you know what to ask. **Ordering is usage, not relevance.** `meta` states `heat_window` (snapped to a UTC day boundary, narrowing only, so the payload is stable between refreshes and safe in a cached prefix), `counted_access_types`, `char_budget`/`chars`, `truncated` and `unresolved`. Open a stub with `knowledge_progressive_drill` — **not** `knowledge_get`, which cannot resolve the published system canonicals this index also lists. Optional: `category`, `limit`, `since`. |
+| `knowledge_progressive_drill` | Open one stub from `knowledge_progressive_index` or `knowledge_heat_index` — returns the **full article body** for the given id, scope-enforced. Resolves both tenant-owned articles and published system canonicals (the same set those indexes surface). 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). |

package/index.js

@@ -1414,6 +1414,21 @@ async function knowledgeProgressiveIndex({ topic, category, limit }) {
   return toContent(result);
 }
 
+async function knowledgeHeatIndex({ category, limit, since }) {
+  const params = new URLSearchParams();
+  if (category) params.set("category", category);
+  if (limit != null) params.set("limit", String(limit));
+  if (since) params.set("since", since);
+
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/heat_index?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function knowledgeProgressiveDrill({ article_id }) {
   const result = await apiCall(
     "GET",
@@ -1461,10 +1476,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);
@@ -4481,10 +4497,51 @@ const TOOLS = [
       required: ["topic"],
     },
   },
+  {
+    name: "knowledge_heat_index",
+    description:
+      "Browse the corpus with NO query — a capped list of compact stubs " +
+      "(id/title/category/heat/summary, NO bodies) ranked by how many DISTINCT readers " +
+      "(agents, not key rows — repeat reads by one reader count once, ties broken by the " +
+      "number of distinct days read, never by raw read count) actually opened each article " +
+      "inside a window. " +
+      "Every other retrieval tool starts from " +
+      "a query, so they share one failure mode: a paraphrase, or material that is topically " +
+      "central but lexically dissimilar to your question, comes back empty and reads as 'the " +
+      "KB has nothing' rather than 'I asked badly'. Reach for this when a search came back " +
+      "empty or thin, or to survey what the fleet actually reads before you know what to " +
+      "ask. Ordering is usage, NOT relevance to any query. Open a stub with " +
+      "knowledge_progressive_drill (not knowledge_get — this index also lists published " +
+      "system canonicals, which knowledge_get cannot resolve).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description: "Optional: restrict to one category.",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: top-K override (clamped to the configured cap).",
+        },
+        since: {
+          type: "string",
+          description:
+            "Optional: ISO-8601 timestamp; count only reads at/after it. Defaults to the " +
+            "last 90 days, clamped to at most 365 days of lookback and to no later than " +
+            "today. Snapped to a UTC day boundary in the NARROWING direction (never wider " +
+            "than you asked for; a timestamp inside the current UTC day is used exactly as " +
+            "given), and meta.heat_window echoes what you got.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "knowledge_progressive_drill",
     description:
-      "Drill into one stub from knowledge_progressive_index — returns the FULL article " +
+      "Drill into one stub from knowledge_progressive_index or knowledge_heat_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). This is the drill " +
       "half of progressive disclosure: index cheaply, then open only the article(s) you " +
@@ -4511,7 +4568,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: {
@@ -4520,6 +4590,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",
@@ -6708,6 +6787,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_progressive_index":
       return await knowledgeProgressiveIndex(args);
 
+    case "knowledge_heat_index":
+      return await knowledgeHeatIndex(args);
+
     case "knowledge_progressive_drill":
       return await knowledgeProgressiveDrill(args);
 

package/package.json

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