loopctl-mcp-server 2.30.0 → 2.31.1

package/README.md

@@ -2,7 +2,7 @@
 
 MCP (Model Context Protocol) server for [loopctl](https://loopctl.com) -- structural trust for AI development loops.
 
-Wraps the loopctl REST API into 65 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+Wraps the loopctl REST API into 72 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
 
 ## Installation
 
@@ -66,7 +66,7 @@ Or if installed locally:
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
 
-## Tools (65)
+## Tools (72)
 
 ### Project Tools
 
@@ -117,7 +117,7 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 
 | Tool | Description |
 |---|---|
-| `bulk_mark_complete` | Bulk mark multiple stories as complete in a single API call. |
+| `bulk_mark_complete` | **Backfill-only.** Bulk-marks pre-existing, never-dispatched stories (pending, unassigned, no dispatch lineage) as complete in a single call. Dispatched stories are refused — they must go through the normal report → review → verify flow. |
 | `verify_all_in_epic` | Bulk verify all reported_done, unverified stories in an epic. |
 
 ### Token Efficiency Tools
@@ -156,6 +156,8 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `knowledge_distant_pairs` | Distant-but-bridgeable article pairs in the optimal-novelty embedding band (cosine distance, default 0.3–0.7) — the creative sweet spot. Sampled from **agent's visible published articles**; agent callers see only their own and `shared` articles. `bridge_path: true` requires a ≤2-hop link path. Returns `{a, b, distance}` pairs, paginated. Optional: `min_distance`, `max_distance`, `bridge_path`, `limit` (default 20, max 100), `offset`. |
 | `knowledge_novelty` | Score ideas by novelty: embeds each idea's text, returns `novelty_score` = cosine distance to the nearest **visible** prior proposal (0 = identical, higher = more novel, up to 2.0; `null` when the idea text is blank, no visible priors exist, or embedding fails — see `meta.prior_count`). Agent callers see only their own and `shared` articles as priors. Priors default to articles tagged `proposal`. Provide ideas as `texts` (strings) OR `ideas` (strings or objects), ≤50. Optional: `prior_tag`. |
 | `knowledge_random_walk` | Random walk through the link graph from `start_id` (no cycles, up to `length` nodes), traversing only **agent's visible published articles**, surfacing unexpected connections. Agent callers see only their own and `shared` articles. Returns `{id, title, category}` in walk order. Required: `start_id`. Optional: `length` (default 4, max 25). |
+| `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`. |
+| `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence`, `confidence`. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
@@ -173,11 +175,19 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default, reversible) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |
-| `knowledge_export` | Export all knowledge articles as an OKF v0.1 bundle (gzipped tar archive, unbounded, bounded-memory streaming, fail-closed). Returns a curl command for direct download. Pass `format=json` for buffered in-memory JSON (convenience tool for file writers; capped at `export_max_buffered_export_articles` — returns 413 if over-cap). Optional: `project_id`, `format` (tar.gz default, json, or obsidian). |
+| `knowledge_export` | Export all knowledge articles as an OKF v0.1 bundle (gzipped tar archive, unbounded, bounded-memory streaming, fail-closed). Returns a curl command for direct download — **the download requires `LOOPCTL_USER_KEY`** (an orchestrator key would 403). Pass `format=json` for buffered in-memory JSON (convenience tool for file writers; capped at `export_max_buffered_export_articles` — returns 413 if over-cap). Optional: `project_id`, `format` (`tar.gz` default or `json`). |
 | `knowledge_ingest` | Submit a URL or raw content for knowledge extraction. Enqueues an Oban job. Extracted articles are **drafts by default** (lower-trust LLM output); pass `publish: true` to publish on extraction. Required: `source_type`. One of: `url` or `content`. Optional: `project_id`, `publish`. |
 | `knowledge_ingest_batch` | Submit up to 50 ingestion items in a single request. Each item has the same shape as `knowledge_ingest` (incl. `publish`). Returns per-item results. Required: `items`. Optional: batch-level `project_id` / `publish` defaults. |
 | `knowledge_ingestion_jobs` | List recent content ingestion jobs (last 7 days, max 50). |
 
+### Per-tenant BYO LLM config + usage (Epic 28, #179)
+
+| Tool | Description |
+|---|---|
+| `llm_config` | Get the tenant's BYO Anthropic LLM config: per-operation models, `has_api_key`, and a masked last-4 hint. Never returns the key. Requires **user** key. |
+| `set_llm_config` | Set/rotate the tenant's OWN Anthropic API key (stored encrypted, never returned) + the three per-operation models (`extraction_model`/`classification_model`/`merge_model`). Any subset; omitting `api_key` leaves it untouched. Requires **user** key. |
+| `knowledge_llm_usage` | Per-tenant LLM token-usage summary, grouped by operation + model + source_type + day over an optional `from`/`to` range (defaults to a 90-day lookback; effective window echoed in `meta.from`/`meta.to`), with `limit`/`offset` pagination. Record-only (no budget enforcement). Requires orchestrator key. |
+
 ### Knowledge Analytics Tools (orchestrator key)
 
 | Tool | Description |
@@ -186,6 +196,8 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `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_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`. |
 
 ### Discovery Tools
 

package/index.js

@@ -10,6 +10,23 @@ import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import {
+  projectsPath,
+  ingestionJobsPath,
+  llmUsagePath,
+  parseJsonResponseBody,
+} from "./lib/http-helpers.js";
+
+// Single source of truth for the server version: the package.json this file
+// ships with (npm always includes package.json in the published tarball).
+// Keeping it derived prevents the handshake version from drifting from the
+// published package version.
+const SERVER_VERSION = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8")
+).version;
 
 // ---------------------------------------------------------------------------
 // HTTP helper — witness protocol state
@@ -41,12 +58,22 @@ function resolveKey(keyOverride) {
   );
 }
 
-async function apiCall(method, path, body, keyOverride) {
+async function apiCall(method, path, body, keyOverride, { exactKey = false } = {}) {
   const url = `${getBaseUrl()}${path}`;
-  const key = resolveKey(keyOverride);
+  // Secret-managing tools pass exactKey:true so the request uses the EXACT
+  // role-pinned key (LOOPCTL_USER_KEY) and does NOT fall back to the global
+  // LOOPCTL_API_KEY override — a secret op must never silently run under a
+  // non-user global key (review #12).
+  const key = exactKey ? keyOverride : resolveKey(keyOverride);
 
   if (!key) {
-    return { error: true, status: 0, body: "No API key configured. Set LOOPCTL_API_KEY, LOOPCTL_ORCH_KEY, or LOOPCTL_AGENT_KEY." };
+    return {
+      error: true,
+      status: 0,
+      body: exactKey
+        ? "No user-role API key configured. Set LOOPCTL_USER_KEY to a user-role key to manage LLM configuration."
+        : "No API key configured. Set LOOPCTL_API_KEY, LOOPCTL_ORCH_KEY, or LOOPCTL_AGENT_KEY.",
+    };
   }
 
   const headers = {
@@ -96,7 +123,17 @@ async function apiCall(method, path, body, keyOverride) {
   let responseBody;
   const contentType = response.headers.get("content-type") || "";
   if (contentType.includes("application/json")) {
-    responseBody = await response.json();
+    // A JSON content-type is no guarantee of a well-formed body: a transient Fly
+    // edge 502/503 or a truncated/empty response can arrive with the JSON header.
+    // Read the raw text and parse defensively (shared with the test suite via
+    // lib/http-helpers.js) so a malformed body becomes a structured MCP error
+    // instead of an unhandled throw from response.json().
+    const raw = await response.text();
+    const outcome = parseJsonResponseBody(raw, response.status);
+    if (outcome.error) {
+      return outcome;
+    }
+    responseBody = outcome.parsed;
   } else {
     const text = await response.text();
     try {
@@ -178,12 +215,10 @@ async function getTenant() {
   return toContent(result);
 }
 
-async function listProjects({ page, page_size } = {}) {
-  const params = new URLSearchParams();
-  if (page != null) params.set("page", String(page));
-  if (page_size != null) params.set("page_size", String(page_size));
-  const query = params.toString() ? `?${params}` : "";
-  const result = await apiCall("GET", `/api/v1/projects${query}`);
+async function listProjects(args = {}) {
+  // Query-string building lives in lib/http-helpers.js so the test suite exercises
+  // the same page/page_size logic the server ships (#247, mcp-01).
+  const result = await apiCall("GET", projectsPath(args));
   return toContent(result);
 }
 
@@ -1120,15 +1155,56 @@ async function knowledgeIngestBatch({ items, project_id, publish }) {
   return toContent(result);
 }
 
-async function knowledgeIngestionJobs({ limit, offset, since_days } = {}) {
-  const params = new URLSearchParams();
-  if (limit != null) params.set("limit", String(limit));
-  if (offset != null) params.set("offset", String(offset));
-  if (since_days != null) params.set("since_days", String(since_days));
-  const query = params.toString() ? `?${params}` : "";
+async function knowledgeIngestionJobs(args = {}) {
+  // Query-string building lives in lib/http-helpers.js so the test suite exercises
+  // the same limit/offset/since_days logic the server ships (#248, mcp-02).
   const result = await apiCall(
     "GET",
-    `/api/v1/knowledge/ingestion-jobs${query}`,
+    ingestionJobsPath(args),
+    null,
+    process.env.LOOPCTL_ORCH_KEY,
+  );
+  return toContent(result);
+}
+
+// --- Per-tenant BYO LLM config + usage (Epic 28 residual, #179) ---
+
+async function llmConfig() {
+  // Reading/writing the tenant LLM config touches a stored secret → EXACT user
+  // key only (bypass the global LOOPCTL_API_KEY override; fail fast if unset).
+  const result = await apiCall(
+    "GET",
+    "/api/v1/tenants/me/llm-config",
+    null,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function setLlmConfig({ api_key, extraction_model, classification_model, merge_model }) {
+  const body = {};
+  if (api_key != null) body.api_key = api_key;
+  if (extraction_model !== undefined) body.extraction_model = extraction_model;
+  if (classification_model !== undefined) body.classification_model = classification_model;
+  if (merge_model !== undefined) body.merge_model = merge_model;
+  // PATCH (partial-merge) + EXACT user key (review #12, #13).
+  const result = await apiCall(
+    "PATCH",
+    "/api/v1/tenants/me/llm-config",
+    body,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function knowledgeLlmUsage(args = {}) {
+  // Query-string building lives in lib/http-helpers.js so the test suite exercises
+  // the same from/to/limit/offset logic the server ships.
+  const result = await apiCall(
+    "GET",
+    llmUsagePath(args),
     null,
     process.env.LOOPCTL_ORCH_KEY,
   );
@@ -1837,7 +1913,7 @@ const TOOLS = [
           properties: {
             input_tokens: { type: "integer", description: "Total input tokens consumed." },
             output_tokens: { type: "integer", description: "Total output tokens consumed." },
-            model_name: { type: "string", description: "Model name (e.g. claude-sonnet-4-5)." },
+            model_name: { type: "string", description: "Model name (e.g. claude-sonnet-5)." },
             cost_millicents: { type: "integer", description: "Total cost in millicents (1/1000 of a cent)." },
           },
         },
@@ -1934,8 +2010,9 @@ const TOOLS = [
   {
     name: "bulk_mark_complete",
     description:
-      "Bulk mark multiple stories as complete in a single API call. " +
-      "Each story entry needs a story_id, summary, and review_type. Uses the ORCH key.",
+      "Bulk mark multiple stories as complete (backfill-only for never-dispatched work). " +
+      "ADMIN USE ONLY: backfill pre-existing completed work into pending stories that never entered the dispatch lifecycle. " +
+      "For dispatched stories, use the normal report/review/verify flow. Each story entry needs a story_id, summary, and review_type. Uses the ORCH key.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2013,7 +2090,7 @@ const TOOLS = [
         },
         model_name: {
           type: "string",
-          description: "Name of the model used (e.g. claude-sonnet-4-5, gpt-4o).",
+          description: "Name of the model used (e.g. claude-sonnet-5, gpt-4o).",
         },
         cost_millicents: {
           type: "integer",
@@ -2410,10 +2487,14 @@ const TOOLS = [
     description:
       "Find distant-but-bridgeable article pairs in the optimal-novelty embedding band " +
       "(cosine distance min..max, default 0.3–0.7) — the creative sweet spot (neither banal " +
-      "nor nonsense). Returns { data: [{a, b, distance}], meta:{count} }. With bridge_path:true, " +
-      "only pairs also connected in the link graph (≤2 hops) are returned. Samples up to 1000 " +
-      "embedded published articles; paginate via limit/offset. For computational-creativity " +
-      "ideation (remote-associates generator).",
+      "nor nonsense). Returns { data: [{a, b, distance}], meta:{count, has_more, total_count} }. " +
+      "Paginate via meta.has_more (a limit+1 look-ahead) — NOT total_count, which is DEPRECATED " +
+      "and always null here: unlike sibling offset/limit tools, an exact total is an " +
+      "O(candidates²) cost (the pair set is a column-to-column self-join), so it was removed for " +
+      "latency (loopctl #202/#203). With bridge_path:true, only pairs also connected in the link " +
+      "graph (≤2 hops) are returned — that branch samples a smaller candidate slice, so it may " +
+      "return fewer pairs. Samples up to 1000 embedded published articles (500 for bridge_path). " +
+      "For computational-creativity ideation (remote-associates generator).",
     inputSchema: {
       type: "object",
       properties: {
@@ -3279,6 +3360,76 @@ const TOOLS = [
     },
   },
 
+  // Per-tenant BYO LLM config + usage (Epic 28 residual, #179)
+  {
+    name: "llm_config",
+    description:
+      "Get the tenant's BYO Anthropic LLM configuration: the per-operation model " +
+      "choices, whether a key is configured (has_api_key), and a masked last-4 hint. " +
+      "NEVER returns the key itself. Requires user role (LOOPCTL_USER_KEY).",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "set_llm_config",
+    description:
+      "Set/rotate the tenant's OWN Anthropic API key (stored encrypted, never returned) " +
+      "and the three per-operation models (extraction/classification/merge). loopctl " +
+      "fronts no LLM cost — the tenant's key bills the tenant. Any subset of fields may " +
+      "be sent; omitting api_key leaves the existing key untouched. Model ids are " +
+      "free-form (any model the key permits). Requires user role (LOOPCTL_USER_KEY).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        api_key: {
+          type: "string",
+          description: "Anthropic API key (write-only; stored encrypted, never returned).",
+        },
+        extraction_model: {
+          type: "string",
+          description: "Model id for knowledge extraction (null → server default).",
+        },
+        classification_model: {
+          type: "string",
+          description: "Model id for category classification (null → server default).",
+        },
+        merge_model: {
+          type: "string",
+          description: "Model id for article merge synthesis (null → server default).",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_llm_usage",
+    description:
+      "Per-tenant LLM token-usage summary, grouped by operation + model + source_type + " +
+      "day over an optional date range, newest day first, with offset/limit pagination " +
+      "over meta.total_count. When `from` is omitted it defaults to a 90-day lookback; the " +
+      "EFFECTIVE window is echoed in meta.from/meta.to so you can detect that older usage " +
+      "was excluded (pass an explicit `from` to widen it). Record-only — there is no budget " +
+      "enforcement. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: {
+          type: "string",
+          description: "Optional ISO 8601 lower bound (inclusive) on occurred_at.",
+        },
+        to: {
+          type: "string",
+          description: "Optional ISO 8601 upper bound (inclusive) on occurred_at.",
+        },
+        limit: {
+          type: "integer",
+          description: "Rows per page (default 50, clamped to 200).",
+        },
+        offset: { type: "integer", description: "Rows to skip (default 0)." },
+      },
+      required: [],
+    },
+  },
+
   // Knowledge Analytics Tools (orchestrator key)
   {
     name: "knowledge_curation_log",
@@ -3558,7 +3709,7 @@ const TOOLS = [
 const server = new Server(
   {
     name: "loopctl",
-    version: "1.2.0",
+    version: SERVER_VERSION,
   },
   {
     capabilities: { tools: {} },
@@ -3578,7 +3729,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return await getTenant();
 
     case "list_projects":
-      return await listProjects();
+      return await listProjects(args);
 
     case "create_project":
       return await createProject(args);
@@ -3752,7 +3903,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return await knowledgeIngestBatch(args);
 
     case "knowledge_ingestion_jobs":
-      return await knowledgeIngestionJobs();
+      return await knowledgeIngestionJobs(args);
+
+    // Per-tenant BYO LLM config + usage (Epic 28, #179)
+    case "llm_config":
+      return await llmConfig();
+
+    case "set_llm_config":
+      return await setLlmConfig(args);
+
+    case "knowledge_llm_usage":
+      return await knowledgeLlmUsage(args);
 
     // Knowledge Analytics Tools
     case "knowledge_curation_log":

package/lib/http-helpers.js

@@ -0,0 +1,106 @@
+// Pure, importable HTTP helpers shared by index.js and the test suite.
+//
+// index.js is a stdio entry point with top-level await (importing it would boot
+// the MCP server), so it cannot be imported directly by tests. Extracting the
+// logic that actually had bugs — query-string building for the paginated tools
+// and the defensive JSON parse in apiCall — into this side-effect-free module
+// gives BOTH index.js and the tests a single source of truth. The tests exercise
+// the SAME code the server ships, so a regression in this logic fails CI instead
+// of silently passing against a hand-copied mirror.
+
+/**
+ * Build a `?a=b&c=d` query string from an array of [key, value] pairs. Skips
+ * null/undefined values (so unset params are omitted) and stringifies the rest.
+ * Returns "" when nothing is set.
+ *
+ * @param {Array<[string, unknown]>} pairs
+ * @returns {string}
+ */
+export function buildQuery(pairs) {
+  const params = new URLSearchParams();
+  for (const [key, value] of pairs) {
+    if (value != null) params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+
+/**
+ * Path for `list_projects`, honoring page/page_size (#247, mcp-01).
+ *
+ * @param {{ page?: number, page_size?: number }} [args]
+ * @returns {string}
+ */
+export function projectsPath({ page, page_size } = {}) {
+  return `/api/v1/projects${buildQuery([
+    ["page", page],
+    ["page_size", page_size],
+  ])}`;
+}
+
+/**
+ * Path for `knowledge_ingestion_jobs`, honoring limit/offset/since_days
+ * (#248, mcp-02).
+ *
+ * @param {{ limit?: number, offset?: number, since_days?: number }} [args]
+ * @returns {string}
+ */
+export function ingestionJobsPath({ limit, offset, since_days } = {}) {
+  return `/api/v1/knowledge/ingestion-jobs${buildQuery([
+    ["limit", limit],
+    ["offset", offset],
+    ["since_days", since_days],
+  ])}`;
+}
+
+/**
+ * Path for `knowledge_llm_usage`, honoring from/to/limit/offset (Epic 28, #179).
+ *
+ * @param {{ from?: string, to?: string, limit?: number, offset?: number }} [args]
+ * @returns {string}
+ */
+export function llmUsagePath({ from, to, limit, offset } = {}) {
+  return `/api/v1/knowledge/llm-usage${buildQuery([
+    ["from", from],
+    ["to", to],
+    ["limit", limit],
+    ["offset", offset],
+  ])}`;
+}
+
+/**
+ * Defensively parse the raw text body of a JSON-content-type HTTP response
+ * (#249, mcp-03).
+ *
+ * A JSON content-type header is no guarantee of a well-formed body: a transient
+ * Fly edge 502/503 or a truncated response can arrive with the JSON header but an
+ * empty or non-JSON body, which makes a bare `response.json()` throw an unhandled
+ * exception. This turns that into a STRUCTURED error the MCP tool layer already
+ * understands (`{ error: true, status, body }`), including the HTTP status and a
+ * raw-body snippet for debugging.
+ *
+ * @param {string} rawText - the response body as text
+ * @param {number} status - the HTTP status code
+ * @returns {{ parsed: unknown } | { error: true, status: number, body: string }}
+ *   `{ parsed }` on success, or a structured error object on empty/invalid JSON.
+ */
+export function parseJsonResponseBody(rawText, status) {
+  if (rawText.trim() === "") {
+    return {
+      error: true,
+      status,
+      body: `invalid/empty JSON response from server (HTTP ${status}): empty body`,
+    };
+  }
+  try {
+    return { parsed: JSON.parse(rawText) };
+  } catch {
+    const snippet =
+      rawText.length > 200 ? `${rawText.slice(0, 200)}... (truncated)` : rawText;
+    return {
+      error: true,
+      status,
+      body: `invalid/empty JSON response from server (HTTP ${status}): ${snippet}`,
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.30.0",
+  "version": "2.31.1",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,8 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node --test"
+    "test": "node --test test/*.test.js",
+    "test:smoke": "node smoke_test.mjs"
   },
   "keywords": [
     "mcp",
@@ -33,6 +34,7 @@
   },
   "files": [
     "index.js",
+    "lib",
     "README.md",
     "LICENSE"
   ],