loopctl-mcp-server 2.77.0 → 2.78.0

package/README.md

@@ -347,6 +347,40 @@ nothing changes until a scope opts in.
 | `custody_claim` | The recorded **egress custody claim** for one article or memory row: the append-only sequence of per-operation postures (create, each embed, each re-embed, each classification, each merge) with the endpoints resolved for THAT operation and their verdicts, plus the aggregate. Rides the existing hash-chained audit log + signed tree heads — each entry carries a `chain_position` and the leaf's `chain_entry_hash`, so `GET /api/v1/audit/sth/{tenant_id}/inclusion/{position}` proves inclusion of *that* leaf, and the leaf's payload names this row by a recomputable `posture_digest`. THREE states, only one an attestation: `no_claim_recorded`, `claim_pending`, `claim_recorded` (`complete` / `partial_history` / `incomplete`). Completeness is measured against a persisted per-row high-water mark, so losing the tail of a sequence is a gap, not a clean claim. `third_party_egress_on_covered_paths` is `false` only for NETWORK-local endpoints; a tenant-declared (unverified) endpoint yields `"tenant_declared_unverified"`. Attests ONLY to the endpoints loopctl called on the paths in `coverage` — never to what those endpoints did afterwards. **Agent** key. |
 | `custody_failures` | Custody posture entries whose chain append was DROPPED after exhausting retries, plus `stale_pending` entries stranded by a flush that died outside its own final-attempt branch. Surfaced rather than silently absent: each `data` entry degrades its row's claim to `incomplete`, and a stranded entry would otherwise read as an in-flight claim forever. **Agent** key. |
 
+### Corpus Tools (Epic 43) — verbatim reference documents
+
+The corpus tier indexes documents whose **files stay in your own repo**. loopctl holds
+chunk pointers (and, in mode A, the text it embeds); a search hands back
+`{source_ref, locator, snippet, score}` and **never the chunk body** — you open the file
+yourself at that pointer. That is what keeps the file the source of truth and lets the
+tier be pointed at a repo loopctl does not own.
+
+**When to reach for it.** `corpus_search` when you need the **verbatim text of an
+authoritative document** — a spec, a contract, an RFC, a manual. `knowledge_search` when
+you want **what we learned** about a topic. Searching the wiki for a distillation of a
+document whose exact wording you needed is the failure this tier exists to prevent; so is
+reading an empty wiki result as an empty corpus.
+
+Two modes, pinned at creation:
+
+- **`server_embedded`** — you send chunk TEXT; loopctl embeds it on **your** embedding key
+  (BYO), and search runs a semantic and a keyword lane. A tenant with no embedding
+  credential is refused at `corpus_create` (`422 no_embedding_key`), not at first index.
+- **`client_embedded`** — you send **vectors**; loopctl stores content it cannot read. No
+  embedding key is needed, search is **semantic-only** (there is no text to index), and
+  `allow_snippets` defaults to **false** — a snippet is text the server would then hold.
+
+`corpus_search` is deliberately **not** part of `recall_context` and is never auto-injected.
+
+| Tool | Description |
+|---|---|
+| `corpus_search` | Search a corpus for POINTERS into files loopctl does not host. Returns `{source_ref, locator, snippet, score, chunk_id, corpus_id}` — a bounded excerpt, never the chunk body — so the next step is always to open the file. `server_embedded`: send `query`. `client_embedded`: send `query_vector` (length = the corpus `dim`); a query string there is `422 query_string_not_accepted` and asking for the keyword lane is `422 keyword_lane_unavailable`. Exactly one of `query`/`query_vector` (both is `422 ambiguous_query`). Scores are rank-derived (RRF) and comparable only WITHIN one result set. Agent key. |
+| `corpus_create` | Create a corpus, pinning `mode`, `embedding_model` and `dim`. Required: `slug`, `name`, `mode`, `embedding_model`, `dim`. Optional: `description`, `allow_snippets`, `project_id`. Agent key. |
+| `corpus_index` | Index a batch of chunks. `server_embedded` chunk: `{source_ref, locator, text, ordinal?, snippet?}`. `client_embedded` chunk: `{source_ref, locator, vector, content_hash, ordinal?, snippet?}` — there is **no** `text` parameter and sending one is `422 text_not_accepted`, not ignored. Idempotent on `(corpus, source_ref, locator)`. `source_complete` is how a RE-index removes what the document no longer contains: a bare `source_ref` string means this request carries that source's complete set, `{source_ref, locators}` declares the set explicitly for a document spanning several batches. Anything under a named source that is neither carried nor declared is deleted, and `meta.pruned_by_source` reports the cost. Agent key. |
+| `corpus_list` | List this tenant's corpora, newest first. Call it before searching to learn a corpus's `mode` (which decides string vs vector) and its `dim`. Optional: `project_id`, `limit`, `offset`. Agent key. |
+| `corpus_status` | Per-`source_ref` chunk count and content hash, paginated — re-index only the documents that moved. Agent key. |
+| `corpus_delete` | **Requires `LOOPCTL_USER_KEY`.** Destroy a corpus and every chunk and vector in it. Irreversible and set-based, which is why it is the one user-role verb on this surface; the files were never uploaded, so recovery means re-creating and re-indexing. To drop chunks a document no longer contains, re-index it with `source_complete` instead. |
+
 ### Discovery Tools
 
 | Tool | Description |

package/index.js

@@ -24,6 +24,14 @@ import {
   llmUsagePath,
   memoryPath,
   parseJsonResponseBody,
+  corporaPath,
+  corpusPath,
+  corpusIndexPath,
+  corpusSearchPath,
+  corpusStatusPath,
+  buildCorpusCreateBody,
+  buildCorpusIndexBody,
+  buildCorpusSearchBody,
 } from "./lib/http-helpers.js";
 import {
   createWitnessClient,
@@ -3010,6 +3018,83 @@ async function getAcceptanceCriteria({ story_id }) {
   return toContent(result);
 }
 
+// ---------------------------------------------------------------------------
+// Corpus tier (Epic 43) — the index for reference documents whose files stay in
+// the caller's own repo.
+//
+// Every path AND request body below is built in lib/http-helpers.js, imported
+// above, so the corpus tests exercise the code this server ships rather than a
+// mirror re-implemented inside a test file (AC-43.4.1/AC-43.4.6).
+//
+// `corpus_delete` is the ONE verb here that takes LOOPCTL_USER_KEY: it is
+// set-based AND irreversible, the same AND that puts the KB's bulk ops behind a
+// user key. Everything else on this surface is agent-role.
+// ---------------------------------------------------------------------------
+
+async function corpusCreate(args) {
+  const result = await apiCall(
+    "POST",
+    corporaPath(),
+    buildCorpusCreateBody(args),
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function corpusList(args = {}) {
+  const result = await apiCall(
+    "GET",
+    corporaPath(args),
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function corpusIndex({ corpus_id, chunks, source_complete }) {
+  // source_complete is forwarded in both of its declared forms; without it the
+  // prune is unreachable through the only surface an agent uses (AC-43.4.1).
+  const result = await apiCall(
+    "POST",
+    corpusIndexPath(corpus_id),
+    buildCorpusIndexBody({ chunks, source_complete }),
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function corpusSearch({ corpus_id, query, query_vector, lanes, limit }) {
+  const result = await apiCall(
+    "POST",
+    corpusSearchPath(corpus_id),
+    buildCorpusSearchBody({ query, query_vector, lanes, limit }),
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  // Pointers + snippets only — the caller's next step is to open the file at
+  // source_ref/locator. Nothing here is auto-injected into a recall pack.
+  return toContent(result);
+}
+
+async function corpusStatus({ corpus_id, limit, offset }) {
+  const result = await apiCall(
+    "GET",
+    corpusStatusPath(corpus_id, { limit, offset }),
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function corpusDelete({ corpus_id }) {
+  const result = await apiCall(
+    "DELETE",
+    corpusPath(corpus_id),
+    null,
+    process.env.LOOPCTL_USER_KEY,
+  );
+  return toContent(result);
+}
+
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
@@ -7196,6 +7281,260 @@ const TOOLS = [
       required: ["story_id"],
     },
   },
+  // Corpus Tools (Epic 43) — verbatim reference documents whose FILES stay in your
+  // own repo. loopctl indexes chunks and hands back pointers; it never hosts the file.
+  {
+    name: "corpus_search",
+    description:
+      "Search an indexed reference DOCUMENT for the place that says it — use this when you " +
+      "need the VERBATIM text of an authoritative source (a spec, a contract, an RFC, a " +
+      "manual), and knowledge_search when you want what we LEARNED about a topic. " +
+      "TRADE-OFF: this returns POINTERS, not bodies. Each result is {source_ref, locator, " +
+      "snippet, score, chunk_id, corpus_id}; the snippet is a bounded excerpt and the full " +
+      "chunk text is NEVER returned, so your next step is always to open the file yourself " +
+      "at source_ref/locator. A server_embedded corpus takes `query` (a string) and fuses a " +
+      "semantic and a keyword lane. A client_embedded corpus is SEMANTIC-ONLY — loopctl " +
+      "holds no text to index — so send `query_vector` (its length must equal the corpus " +
+      "dim, from corpus_list); a query STRING there is refused (422 " +
+      "query_string_not_accepted) and so is asking for the keyword lane (422 " +
+      "keyword_lane_unavailable). Send exactly ONE of query/query_vector: both is 422 " +
+      "ambiguous_query, and a query_vector to a server_embedded corpus is 422 " +
+      "query_vector_not_accepted. Scores are rank-derived (RRF) and comparable only WITHIN " +
+      "one result set — there is no absolute floor, so judge by rank. Deliberately NOT part " +
+      "of recall_context: nothing here is auto-injected. Agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        corpus_id: {
+          type: "string",
+          description: "The corpus id or slug to search.",
+        },
+        query: {
+          type: "string",
+          description:
+            "The query text. server_embedded corpora ONLY. Send this or query_vector, never both.",
+        },
+        query_vector: {
+          type: "array",
+          items: { type: "number" },
+          description:
+            "A locally-produced query vector whose length equals the corpus dim. " +
+            "client_embedded corpora ONLY. Send this or query, never both.",
+        },
+        lanes: {
+          type: "array",
+          items: { type: "string", enum: ["semantic", "keyword"] },
+          description:
+            "Optional: the lanes to run (default: every lane the corpus offers). A " +
+            "client_embedded corpus offers only `semantic`.",
+        },
+        limit: { type: "integer", description: "Optional: max results (clamped server-side)." },
+      },
+      required: ["corpus_id"],
+    },
+  },
+  {
+    name: "corpus_create",
+    description:
+      "Create a corpus — a named index over reference documents whose FILES stay in your own " +
+      "repo (use knowledge_create instead when you are writing a curated article loopctl " +
+      "should own). TRADE-OFF: `mode` is pinned at creation and decides everything after " +
+      "it. In `server_embedded` you send chunk TEXT and loopctl embeds it on YOUR embedding " +
+      "key — so a tenant with no embedding credential is refused HERE (422 no_embedding_key) " +
+      "rather than at first index — and both search lanes work. In `client_embedded` you " +
+      "send VECTORS and loopctl stores content it cannot read: no embedding key is needed, " +
+      "search is semantic-only, and allow_snippets defaults to FALSE (a snippet IS text the " +
+      "server would then hold) — ask for it explicitly if you want excerpts back. " +
+      "`embedding_model` and `dim` are pinned too, and a dim that disagrees with a known " +
+      "model's native dimension is refused. Agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "URL-safe identifier, unique per tenant." },
+        name: { type: "string", description: "Human-readable name." },
+        mode: {
+          type: "string",
+          enum: ["server_embedded", "client_embedded"],
+          description:
+            "server_embedded: you send text, loopctl embeds it on your key, both lanes " +
+            "work. client_embedded: you send vectors, loopctl never sees the text, " +
+            "semantic lane only. Permanent for the corpus.",
+        },
+        embedding_model: {
+          type: "string",
+          description: "The embedding model this corpus is pinned to, e.g. text-embedding-3-small.",
+        },
+        dim: {
+          type: "integer",
+          description: "The embedding dimension. Every vector indexed or searched must match it.",
+        },
+        description: { type: "string", description: "Optional: what this corpus holds." },
+        allow_snippets: {
+          type: "boolean",
+          description:
+            "Optional: allow stored excerpts to come back on search results. Defaults to " +
+            "FALSE in client_embedded mode, because a snippet is text the server would hold.",
+        },
+        project_id: { type: "string", description: "Optional: scope the corpus to one project." },
+      },
+      required: ["slug", "name", "mode", "embedding_model", "dim"],
+    },
+  },
+  {
+    name: "corpus_index",
+    description:
+      "Index a batch of chunks into a corpus — this is how a document becomes searchable; " +
+      "it never uploads the file, only pointers plus whatever the corpus mode needs to rank " +
+      "them. TRADE-OFF: the chunk shape is decided by the corpus mode and a mismatch is " +
+      "REFUSED, not ignored. In a server_embedded corpus a chunk is {source_ref, locator, " +
+      "text, ordinal?, snippet?} and content_hash is computed server-side. In a " +
+      "client_embedded corpus a chunk is {source_ref, locator, vector, content_hash, " +
+      "ordinal?, snippet?} — there is NO text parameter, and a chunk carrying one is 422 " +
+      "text_not_accepted (dropping it would let you believe a keyword lane works on a corpus " +
+      "with no text). Indexing is IDEMPOTENT on (corpus, source_ref, locator): an unchanged " +
+      "batch writes nothing and spends no embedding tokens. `source_complete` is what makes " +
+      "a RE-index remove what the document no longer contains: name a source_ref as a bare " +
+      "STRING to declare that this request carries its complete chunk set, or as " +
+      "{source_ref, locators} to declare that set explicitly when the document spans several " +
+      "batches. Every stored chunk of a named source that is neither carried nor declared is " +
+      "DELETED, and meta.pruned_by_source reports what each name cost. Omit source_complete " +
+      "and stale chunks survive forever. Split large batches — an over-size body is 413 and " +
+      "vectors are bytes. Agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        corpus_id: { type: "string", description: "The corpus id or slug to index into." },
+        chunks: {
+          type: "array",
+          description:
+            "The chunks to index. server_embedded: {source_ref, locator, text, ordinal?, " +
+            "snippet?}. client_embedded: {source_ref, locator, vector, content_hash, " +
+            "ordinal?, snippet?} — no text.",
+          items: {
+            type: "object",
+            properties: {
+              source_ref: {
+                type: "string",
+                description: "The document this chunk came from, e.g. a repo-relative file path.",
+              },
+              locator: {
+                description:
+                  "Your own opaque pointer into that document (a page, a heading, a line " +
+                  "range), stored verbatim and handed back on every search hit.",
+              },
+              text: {
+                type: "string",
+                description: "The chunk text. server_embedded ONLY — refused in client_embedded.",
+              },
+              vector: {
+                type: "array",
+                items: { type: "number" },
+                description:
+                  "Your locally-produced embedding. client_embedded ONLY; length must equal " +
+                  "the corpus dim.",
+              },
+              content_hash: {
+                type: "string",
+                description:
+                  "client_embedded ONLY: your opaque idempotency token for this chunk. " +
+                  "loopctl cannot verify it against the vector or the file — rotate it to " +
+                  "publish a new vector for an otherwise unchanged chunk.",
+              },
+              ordinal: { type: "integer", description: "Optional: order within the source." },
+              snippet: {
+                type: "string",
+                description:
+                  "Optional excerpt returned on search hits. Refused (422 " +
+                  "snippets_not_allowed) unless the corpus was created with allow_snippets.",
+              },
+            },
+            required: ["source_ref"],
+          },
+        },
+        source_complete: {
+          type: "array",
+          description:
+            "The sources to RECONCILE, each declaring its complete chunk set. A bare " +
+            "source_ref string means this request carries that source's whole set; " +
+            "{source_ref, locators} declares it explicitly so a document spanning several " +
+            "batches is reconciled on the batch that completes it. Anything stored under a " +
+            "named source and neither carried nor declared is deleted.",
+          items: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                properties: {
+                  source_ref: { type: "string" },
+                  locators: {
+                    type: "array",
+                    description:
+                      "The source's COMPLETE locator set. Must include every locator this " +
+                      "request carries for it.",
+                  },
+                },
+                required: ["source_ref", "locators"],
+              },
+            ],
+          },
+        },
+      },
+      required: ["corpus_id", "chunks"],
+    },
+  },
+  {
+    name: "corpus_list",
+    description:
+      "List this tenant's corpora, newest first — call it before corpus_search to learn a " +
+      "corpus's slug, its `mode` (which decides whether you send a query string or a query " +
+      "vector) and its `dim`. Reading a mode off an ERROR is the failure this avoids. " +
+      "Agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Optional: restrict to one project scope." },
+        limit: { type: "integer", description: "Optional: page size (clamped)." },
+        offset: { type: "integer", description: "Optional: rows to skip." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "corpus_status",
+    description:
+      "List what is actually indexed in a corpus, one row per source_ref with its chunk " +
+      "count and a content hash over that source's chunks. TRADE-OFF: use it to re-index " +
+      "only the documents that MOVED instead of resubmitting the corpus — a hash that " +
+      "matches your local one means that source needs no work. Paginated: a corpus with " +
+      "thousands of sources does not come back in one body. Agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        corpus_id: { type: "string", description: "The corpus id or slug." },
+        limit: { type: "integer", description: "Optional: sources per page (clamped)." },
+        offset: { type: "integer", description: "Optional: sources to skip." },
+      },
+      required: ["corpus_id"],
+    },
+  },
+  {
+    name: "corpus_delete",
+    description:
+      "Delete a corpus and every chunk and vector in it. **Requires LOOPCTL_USER_KEY** " +
+      "(user role — an agent or orchestrator key is NOT sufficient), because this is the " +
+      "one verb on this surface that is both set-based and IRREVERSIBLE: nothing in loopctl " +
+      "restores it. The files themselves are yours and were never uploaded, so the recovery " +
+      "path is to re-create the corpus and re-index them. To drop chunks a document no longer " +
+      "contains, re-index that document with corpus_index's source_complete instead of " +
+      "deleting the corpus. Agent and orchestrator keys get 403.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        corpus_id: { type: "string", description: "The corpus id or slug to destroy." },
+      },
+      required: ["corpus_id"],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -7682,6 +8021,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "get_acceptance_criteria":
       return await getAcceptanceCriteria(args);
 
+    // Corpus Tools (Epic 43)
+    case "corpus_create":
+      return await corpusCreate(args);
+
+    case "corpus_index":
+      return await corpusIndex(args);
+
+    case "corpus_search":
+      return await corpusSearch(args);
+
+    case "corpus_list":
+      return await corpusList(args);
+
+    case "corpus_status":
+      return await corpusStatus(args);
+
+    case "corpus_delete":
+      return await corpusDelete(args);
+
     default:
       // Per-tenant generated Context Retriever tools (US-30.5) are not in the
       // static switch — dispatch any unknown `cr_`-prefixed name generically to

package/lib/http-helpers.js

@@ -214,3 +214,150 @@ export function parseJsonResponseBody(rawText, status) {
     };
   }
 }
+
+// ---------------------------------------------------------------------------
+// Corpus tier (Epic 43) — paths and request bodies for the `corpus_*` tools.
+//
+// EVERY corpus tool's path AND body is built here rather than inline in
+// index.js, because index.js is a stdio entry point with top-level await that
+// cannot be imported by a test (AC-43.4.1). Extracting both halves is what lets
+// the corpus tests exercise the SHIPPED code instead of a hand-copied mirror.
+//
+// The bodies are built to the shapes `LoopctlWeb.CorpusController`'s `operation/2`
+// specs declare. A nullish optional is OMITTED rather than sent as `null`: the
+// search action dispatches on the VALUE of `query_vector`, so emitting an explicit
+// `null` for an unset one sent a mode A request down the mode B path to be refused
+// with `query_vector_not_accepted`. An EMPTY ARRAY is deliberately NOT treated as
+// absent — the server refuses it by name (`invalid_query_vector`), and swallowing
+// it here would turn a malformed vector into a silently different request.
+// ---------------------------------------------------------------------------
+
+/**
+ * Path for `corpus_list` (GET /api/v1/corpora), honoring project_id/limit/offset.
+ *
+ * @param {{ project_id?: string, limit?: number, offset?: number }} [args]
+ * @returns {string}
+ */
+export function corporaPath({ project_id, limit, offset } = {}) {
+  return `/api/v1/corpora${buildQuery([
+    ["project_id", project_id],
+    ["limit", limit],
+    ["offset", offset],
+  ])}`;
+}
+
+/**
+ * Path for one corpus (GET/DELETE /api/v1/corpora/:id). The segment accepts an id
+ * OR a slug, both client-supplied, so it is encoded (the `retrieveEntityPath`
+ * precedent) rather than interpolated raw.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function corpusPath(id) {
+  return `/api/v1/corpora/${encodeURIComponent(id)}`;
+}
+
+/**
+ * Path for `corpus_index` (POST /api/v1/corpora/:id/index).
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function corpusIndexPath(id) {
+  return `${corpusPath(id)}/index`;
+}
+
+/**
+ * Path for `corpus_search` (POST /api/v1/corpora/:id/search).
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function corpusSearchPath(id) {
+  return `${corpusPath(id)}/search`;
+}
+
+/**
+ * Path for `corpus_status` (GET /api/v1/corpora/:id/status), honoring limit/offset
+ * — the per-source listing is paginated, so a corpus with thousands of sources
+ * does not come back in one body.
+ *
+ * @param {string} id
+ * @param {{ limit?: number, offset?: number }} [args]
+ * @returns {string}
+ */
+export function corpusStatusPath(id, { limit, offset } = {}) {
+  return `${corpusPath(id)}/status${buildQuery([
+    ["limit", limit],
+    ["offset", offset],
+  ])}`;
+}
+
+/**
+ * Body for `corpus_create` (POST /api/v1/corpora).
+ *
+ * `allow_snippets` is filtered on `!= null`, never on falsiness: `false` is the
+ * meaningful mode B default and a truthiness check would drop an explicit opt-out.
+ *
+ * @param {{ slug?: string, name?: string, mode?: string, embedding_model?: string,
+ *   dim?: number, description?: string, allow_snippets?: boolean, project_id?: string }} [args]
+ * @returns {object}
+ */
+export function buildCorpusCreateBody(args = {}) {
+  const body = {};
+  for (const key of [
+    "slug",
+    "name",
+    "mode",
+    "embedding_model",
+    "dim",
+    "description",
+    "allow_snippets",
+    "project_id",
+  ]) {
+    if (args[key] != null) body[key] = args[key];
+  }
+  return body;
+}
+
+/**
+ * Body for `corpus_index` (POST /api/v1/corpora/:id/index).
+ *
+ * `chunks` passes through verbatim — its shape is mode-dependent (mode A carries
+ * `text`, mode B carries `vector` + `content_hash`) and the server is the one that
+ * decides, so nothing is reshaped or filtered here.
+ *
+ * `source_complete` is forwarded in BOTH declared forms (a bare `source_ref`
+ * string, or `{source_ref, locators}`) because it is the ONLY way to reach US-43.2's
+ * prune: omit it from the tool surface and a re-indexed document's removed chunks
+ * are unreachable through the surface an agent actually uses (AC-43.4.1).
+ *
+ * @param {{ chunks?: unknown[], source_complete?: unknown[] }} [args]
+ * @returns {object}
+ */
+export function buildCorpusIndexBody({ chunks, source_complete } = {}) {
+  const body = { chunks: chunks ?? [] };
+  if (source_complete != null) body.source_complete = source_complete;
+  return body;
+}
+
+/**
+ * Body for `corpus_search` (POST /api/v1/corpora/:id/search).
+ *
+ * The parameter is named `query` (not `q`) to match every sibling on this surface
+ * except legacy `knowledge_search` — agents copy parameter spellings from
+ * neighbouring tools, and `lib/arg-aliases.js` documents the 8% of searches that
+ * cost.
+ *
+ * @param {{ query?: string, query_vector?: number[], lanes?: string[], limit?: number }} [args]
+ * @returns {object}
+ */
+export function buildCorpusSearchBody({ query, query_vector, lanes, limit } = {}) {
+  const body = {};
+  if (query != null) body.query = query;
+  if (query_vector != null) body.query_vector = query_vector;
+  if (lanes != null) body.lanes = lanes;
+  if (limit != null) body.limit = limit;
+  return body;
+}

package/package.json

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