loopctl-mcp-server 2.30.1 → 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 69 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 (69)
+## Tools (72)
 
 ### Project Tools
 
@@ -180,6 +180,14 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `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 |

package/index.js

@@ -13,6 +13,12 @@ import {
 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).
@@ -52,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 = {
@@ -109,26 +125,15 @@ async function apiCall(method, path, body, keyOverride) {
   if (contentType.includes("application/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 so a malformed body becomes a
-    // structured MCP error instead of an unhandled throw from response.json().
+    // 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();
-    if (raw.trim() === "") {
-      return {
-        error: true,
-        status: response.status,
-        body: `invalid/empty JSON response from server (HTTP ${response.status}): empty body`,
-      };
-    }
-    try {
-      responseBody = JSON.parse(raw);
-    } catch {
-      const snippet = raw.length > 200 ? `${raw.slice(0, 200)}... (truncated)` : raw;
-      return {
-        error: true,
-        status: response.status,
-        body: `invalid/empty JSON response from server (HTTP ${response.status}): ${snippet}`,
-      };
+    const outcome = parseJsonResponseBody(raw, response.status);
+    if (outcome.error) {
+      return outcome;
     }
+    responseBody = outcome.parsed;
   } else {
     const text = await response.text();
     try {
@@ -210,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);
 }
 
@@ -1152,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,
   );
@@ -2443,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: {
@@ -3312,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",
@@ -3787,6 +3905,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_ingestion_jobs":
       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":
       return await knowledgeCurationLog(args);

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.1",
+  "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"
   ],