loopctl-mcp-server 1.2.0 → 1.4.0

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 33 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+Wraps the loopctl REST API into 37 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
 
 ## Installation
 
@@ -62,10 +62,11 @@ Or if installed locally:
 | `LOOPCTL_API_KEY` | Global API key override (if set, always used) | -- |
 | `LOOPCTL_ORCH_KEY` | Orchestrator role API key (verify, reject, review, import) | -- |
 | `LOOPCTL_AGENT_KEY` | Agent role API key (contract, claim, start, request-review) | -- |
+| `LOOPCTL_USER_KEY` | User role API key. Required ONLY for destructive admin tools like `knowledge_bulk_publish`. Leave unset if you don't use those tools. | -- |
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
 
-## Tools (33)
+## Tools (37)
 
 ### Project Tools
 
@@ -140,9 +141,13 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | Tool | Description |
 |---|---|
 | `knowledge_publish` | Publish a draft article, making it visible to all agents. Required: `article_id`. |
-| `knowledge_drafts` | List all draft (unpublished) knowledge articles. Optional: `limit`, `offset`. |
-| `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`. |
+| `knowledge_bulk_publish` | **Requires `LOOPCTL_USER_KEY`.** Atomically publish up to 100 drafts in a single call. Required: `article_ids` (array). |
+| `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 20), `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 a ZIP archive. Returns a curl command for direct download (ZIP binary cannot be returned as MCP content). Optional: `project_id`. |
+| `knowledge_ingest` | Submit a URL or raw content for knowledge extraction. Enqueues an Oban job. Required: `source_type`. One of: `url` or `content`. Optional: `project_id`. |
+| `knowledge_ingest_batch` | Submit up to 50 ingestion items in a single request. Each item has the same shape as `knowledge_ingest`. Returns per-item results. Required: `items`. Optional: batch-level `project_id` default. |
+| `knowledge_ingestion_jobs` | List recent content ingestion jobs (last 7 days, max 50). |
 
 ### Discovery Tools
 

package/index.js

@@ -457,20 +457,34 @@ async function knowledgePublish({ article_id }) {
   return toContent(result);
 }
 
-async function knowledgeDrafts({ limit, offset }) {
+async function knowledgeBulkPublish({ article_ids }) {
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/bulk-publish",
+    { article_ids },
+    process.env.LOOPCTL_USER_KEY
+  );
+  return toContent(result);
+}
+
+async function knowledgeDrafts({ limit, offset, project_id }) {
   const params = new URLSearchParams();
-  if (limit != null) params.set("limit", String(limit));
+  params.set(
+    "limit",
+    String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE))
+  );
   if (offset != null) params.set("offset", String(offset));
-  const qs = params.toString();
-  const path = qs ? `/api/v1/knowledge/drafts?${qs}` : "/api/v1/knowledge/drafts";
+  if (project_id) params.set("project_id", project_id);
+  const path = `/api/v1/knowledge/drafts?${params.toString()}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
   return toContent(result);
 }
 
-async function knowledgeLint({ project_id, stale_days, min_coverage }) {
+async function knowledgeLint({ project_id, stale_days, min_coverage, max_per_category }) {
   const params = new URLSearchParams();
   if (stale_days != null) params.set("stale_days", String(stale_days));
   if (min_coverage != null) params.set("min_coverage", String(min_coverage));
+  if (max_per_category != null) params.set("max_per_category", String(max_per_category));
   const qs = params.toString();
   const basePath = project_id
     ? `/api/v1/projects/${project_id}/knowledge/lint`
@@ -480,6 +494,40 @@ async function knowledgeLint({ project_id, stale_days, min_coverage }) {
   return toContent(result);
 }
 
+async function knowledgeIngest({ url, content, source_type, project_id }) {
+  const body = { source_type };
+  if (url) body.url = url;
+  if (content) body.content = content;
+  if (project_id) body.project_id = project_id;
+  const result = await apiCall("POST", "/api/v1/knowledge/ingest", body, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
+async function knowledgeIngestBatch({ items, project_id }) {
+  // If a batch-level project_id is supplied, apply it as a default to every
+  // item that doesn't already set its own.
+  const resolvedItems = Array.isArray(items)
+    ? items.map((item) =>
+        project_id && item && item.project_id == null
+          ? { ...item, project_id }
+          : item
+      )
+    : items;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/ingest/batch",
+    { items: resolvedItems },
+    process.env.LOOPCTL_ORCH_KEY
+  );
+  return toContent(result);
+}
+
+async function knowledgeIngestionJobs() {
+  const result = await apiCall("GET", "/api/v1/knowledge/ingestion-jobs", null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
 async function knowledgeExport({ project_id }) {
   const basePath = project_id
     ? `/api/v1/projects/${project_id}/knowledge/export`
@@ -1194,20 +1242,51 @@ const TOOLS = [
       required: ["article_id"],
     },
   },
+  {
+    name: "knowledge_bulk_publish",
+    description:
+      "Atomically publish up to 100 draft articles in a single call. " +
+      "REQUIRES LOOPCTL_USER_KEY to be set in the MCP server env (user role — " +
+      "orchestrator role is NOT sufficient for this destructive operation). " +
+      "All articles must be drafts belonging to the tenant; if any fail validation, " +
+      "the entire operation rolls back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of draft article UUIDs to publish (max 100).",
+          maxItems: 100,
+        },
+      },
+      required: ["article_ids"],
+    },
+  },
   {
     name: "knowledge_drafts",
     description:
-      "List all draft (unpublished) knowledge articles. Requires orchestrator role. Use to review pending articles before publishing.",
+      "List draft (unpublished) knowledge articles. Requires orchestrator role. " +
+      "Returns paginated drafts with total_count in meta. Max 20 per page.",
     inputSchema: {
       type: "object",
       properties: {
         limit: {
           type: "integer",
-          description: "Optional: maximum number of drafts to return.",
+          description: "Max drafts per page. Default 20, hard max 20.",
+          default: 20,
+          minimum: 1,
+          maximum: 20,
         },
         offset: {
           type: "integer",
-          description: "Optional: pagination offset.",
+          description: "Pagination offset. Default 0.",
+          default: 0,
+          minimum: 0,
+        },
+        project_id: {
+          type: "string",
+          description: "Optional: filter drafts to a specific project UUID.",
         },
       },
       required: [],
@@ -1217,7 +1296,9 @@ const TOOLS = [
     name: "knowledge_lint",
     description:
       "Run a lint check on the knowledge wiki to identify stale, low-coverage, or broken articles. " +
-      "Requires orchestrator role. Optionally scoped to a project.",
+      "Requires orchestrator role. Optionally scoped to a project. " +
+      "Each issue category is capped at max_per_category (default 50) with true totals " +
+      "exposed in summary.total_per_category and per-category truncated flags.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1230,10 +1311,18 @@ const TOOLS = [
           description: "Optional: flag articles not updated in this many days as stale.",
         },
         min_coverage: {
-          type: "number",
-          description: "Optional: minimum required coverage score (0.0-1.0) to flag under-covered articles.",
-          minimum: 0,
-          maximum: 1,
+          type: "integer",
+          description:
+            "Optional: minimum published articles per category below which a coverage gap is reported (default 3).",
+          minimum: 1,
+        },
+        max_per_category: {
+          type: "integer",
+          description:
+            "Max items per category to return. Default 50, max 500. True totals are still reported in summary.total_per_category.",
+          default: 50,
+          minimum: 1,
+          maximum: 500,
         },
       },
       required: [],
@@ -1256,6 +1345,98 @@ const TOOLS = [
     },
   },
 
+  // Knowledge Ingestion Tools
+  {
+    name: "knowledge_ingest",
+    description:
+      "Submit a URL or raw content for knowledge extraction. " +
+      "Enqueues an Oban job that fetches the content (if URL), extracts knowledge articles via LLM, " +
+      "and inserts them as draft articles. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to fetch content from (exactly one of url or content required).",
+        },
+        content: {
+          type: "string",
+          description: "Raw content to extract knowledge from (exactly one of url or content required).",
+        },
+        source_type: {
+          type: "string",
+          description: "Source type (e.g., newsletter, skill, web_article, ingestion). Required.",
+        },
+        project_id: {
+          type: "string",
+          description: "Optional: scope extracted articles to a specific project UUID.",
+        },
+      },
+      required: ["source_type"],
+    },
+  },
+  {
+    name: "knowledge_ingest_batch",
+    description:
+      "Submit up to 50 ingestion items in a single request. Each item follows the same " +
+      "shape as knowledge_ingest (url OR content, source_type required). Returns a " +
+      "per-item result array — individual failures do not abort the batch. " +
+      "Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        items: {
+          type: "array",
+          description: "Array of ingestion items (1-50). Each item must include source_type and exactly one of url or content.",
+          minItems: 1,
+          maxItems: 50,
+          items: {
+            type: "object",
+            properties: {
+              url: {
+                type: "string",
+                description: "URL to fetch content from (exactly one of url or content required).",
+              },
+              content: {
+                type: "string",
+                description: "Raw content to extract from (exactly one of url or content required).",
+              },
+              source_type: {
+                type: "string",
+                description: "Source type (e.g., newsletter, skill, web_article, ingestion). Required.",
+              },
+              project_id: {
+                type: "string",
+                description: "Optional: scope the item to a specific project UUID.",
+              },
+              metadata: {
+                type: "object",
+                description: "Optional metadata map.",
+              },
+            },
+            required: ["source_type"],
+          },
+        },
+        project_id: {
+          type: "string",
+          description: "Optional batch-level default project UUID applied to items that don't specify their own.",
+        },
+      },
+      required: ["items"],
+    },
+  },
+  {
+    name: "knowledge_ingestion_jobs",
+    description:
+      "List recent content ingestion jobs for the current tenant. " +
+      "Returns jobs from the last 7 days, max 50 results. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+
   // Discovery Tools
   {
     name: "list_routes",
@@ -1386,6 +1567,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_publish":
       return await knowledgePublish(args);
 
+    case "knowledge_bulk_publish":
+      return await knowledgeBulkPublish(args);
+
     case "knowledge_drafts":
       return await knowledgeDrafts(args);
 
@@ -1395,6 +1579,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_export":
       return await knowledgeExport(args);
 
+    // Knowledge Ingestion Tools
+    case "knowledge_ingest":
+      return await knowledgeIngest(args);
+
+    case "knowledge_ingest_batch":
+      return await knowledgeIngestBatch(args);
+
+    case "knowledge_ingestion_jobs":
+      return await knowledgeIngestionJobs();
+
     // Discovery Tools
     case "list_routes":
       return await listRoutes();

package/package.json

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