loopctl-mcp-server 2.53.1 → 2.54.0

package/README.md

@@ -297,7 +297,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | Tool | Description |
 |---|---|
 | `llm_config` | **Check your onboarding status.** Get the tenant's BYO LLM config: per-operation models and whether each key is set — `has_api_key` (Anthropic) / `has_embedding_key` (OpenAI embedding) — plus masked last-4 hints. Never returns a key. Requires **user** key. |
-| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
+| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). **Private tier (US-41.3):** also sets `chat_provider` (`anthropic` | `openai_compatible`), `chat_base_url`, `extraction_model` (required on that provider) and `chat_api_key` (optional — omit it for a keyless local server) so ingest extraction / classification / merge / memory promotion run against YOUR OWN OpenAI-compatible endpoint and document text never leaves your boundary. Every model the config resolves to is PROBED with a trivial completion before it is saved (a 422 persists nothing); the probe re-runs on any chat-surface change (provider, base_url, key rotation, model), a private-range host is refused by the SSRF guard, and moving to a NEW host needs a matching `chat_api_key` or `acknowledge_key_transmission: true`. See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). 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)

package/index.js

@@ -1852,6 +1852,10 @@ async function setLlmConfig({
   merge_model,
   embedding_api_key,
   embedding_model,
+  chat_provider,
+  chat_base_url,
+  chat_api_key,
+  acknowledge_key_transmission,
 }) {
   const body = {};
   if (api_key != null) body.api_key = api_key;
@@ -1860,6 +1864,15 @@ async function setLlmConfig({
   if (merge_model !== undefined) body.merge_model = merge_model;
   if (embedding_api_key != null) body.embedding_api_key = embedding_api_key;
   if (embedding_model !== undefined) body.embedding_model = embedding_model;
+  // US-41.3: pluggable OpenAI-compatible chat endpoint. The server PROBES the
+  // endpoint with a trivial completion before persisting, and refuses an endpoint
+  // change that carries neither a matching chat_api_key nor an explicit
+  // acknowledge_key_transmission.
+  if (chat_provider !== undefined) body.chat_provider = chat_provider;
+  if (chat_base_url !== undefined) body.chat_base_url = chat_base_url;
+  if (chat_api_key != null) body.chat_api_key = chat_api_key;
+  if (acknowledge_key_transmission === true)
+    body.acknowledge_key_transmission = true;
   // PATCH (partial-merge) + EXACT user key (review #12, #13).
   const result = await apiCall(
     "PATCH",
@@ -5114,7 +5127,11 @@ const TOOLS = [
       "(extraction_model / classification_model / merge_model / embedding_model) are " +
       "free-form (any model the key permits) and default server-side when omitted. Typical " +
       'onboarding call: set_llm_config({api_key: "sk-ant-...", embedding_api_key: "sk-..."}). ' +
-      "Verify anytime with llm_config (has_api_key / has_embedding_key). REQUIRES your " +
+      "PRIVATE TIER: set chat_provider 'openai_compatible' + chat_base_url + " +
+      "extraction_model (+ chat_api_key unless your server is keyless) to run " +
+      "extraction/classification/merge against YOUR OWN endpoint so document text " +
+      "never leaves your boundary; every model it resolves to is probed before it is saved. " +
+      "Verify anytime with llm_config (has_api_key / has_embedding_key / chat_provider). REQUIRES your " +
       "user-role key LOOPCTL_USER_KEY (minted by the human-anchored signup ceremony); if it " +
       "is unset the tool fails fast telling you to set it.",
     inputSchema: {
@@ -5128,7 +5145,14 @@ const TOOLS = [
         },
         extraction_model: {
           type: "string",
-          description: "Model id for knowledge extraction (null → server default).",
+          description:
+            "Model id for knowledge extraction (null → server default). REQUIRED with " +
+            "chat_provider 'openai_compatible': the server default is an Anthropic model " +
+            "id your endpoint cannot serve, so there is no safe fallback. It is also the " +
+            "fallback for classification_model / merge_model on that provider. " +
+            "HuggingFace repo ids are valid (e.g. 'meta-llama/Meta-Llama-3-8B-Instruct') " +
+            "— it is sent verbatim as the OpenAI `model` field, so it must match the name " +
+            "your server actually serves.",
         },
         classification_model: {
           type: "string",
@@ -5150,6 +5174,48 @@ const TOOLS = [
           description:
             "Embedding model id (null → server default text-embedding-3-small).",
         },
+        chat_provider: {
+          type: "string",
+          enum: ["anthropic", "openai_compatible"],
+          description:
+            "Which provider serves the CHAT surface (ingest extraction, classification, " +
+            "merge synthesis, memory promotion). Omit or 'anthropic' keeps the hardcoded " +
+            "Anthropic endpoint and identical behaviour. 'openai_compatible' routes that " +
+            "surface — the largest and most sensitive payload in the pipeline, your " +
+            "documents' full text — to YOUR OWN endpoint instead.",
+        },
+        chat_base_url: {
+          type: "string",
+          description:
+            "API base of your OpenAI-compatible server, e.g. " +
+            "'https://llm.example.internal/v1' (the client appends /chat/completions). " +
+            "Required with chat_provider 'openai_compatible'. PROBED with a trivial " +
+            "completion per resolved model BEFORE it is saved: an unreachable host, a " +
+            "rejected credential or a non-OpenAI-compatible response is a 422 and NOTHING " +
+            "is persisted. A host resolving into a private/loopback/link-local range is " +
+            "refused outright unless the OPERATOR allowlisted it (SSRF guard). Must be a " +
+            "BARE base: no query string, no fragment, no user:pass@ credentials (this " +
+            "column is NOT encrypted — anything in the URL is stored and echoed back). " +
+            "Plaintext http is accepted ONLY for a host the egress policy classifies " +
+            "network-local; a public http:// endpoint is refused because the request " +
+            "carries your key and your documents' full text in cleartext.",
+        },
+        chat_api_key: {
+          type: "string",
+          description:
+            "Credential for chat_base_url. Write-only; stored encrypted, never returned. " +
+            "SEPARATE from api_key — your Anthropic key is never sent to your endpoint. " +
+            "OPTIONAL: a local server that serves /chat/completions with no auth is " +
+            "configured by omitting this, and no authorization header is then sent.",
+        },
+        acknowledge_key_transmission: {
+          type: "boolean",
+          description:
+            "Required when CHANGING chat_base_url without supplying a matching " +
+            "chat_api_key: explicitly acknowledges that the already-stored key will be " +
+            "transmitted to the new host. The probe never ships an existing credential to " +
+            "a new host silently. Not persisted.",
+        },
       },
       required: [],
     },
@@ -5157,7 +5223,7 @@ const TOOLS = [
   {
     name: "knowledge_llm_usage",
     description:
-      "Per-tenant LLM token-usage summary, grouped by operation + model + source_type + " +
+      "Per-tenant LLM token-usage summary, grouped by operation + model + provider + 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 " +

package/package.json

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