loopctl-mcp-server 1.3.0 → 1.5.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 35 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+Wraps the loopctl REST API into 41 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 (35)
+## Tools (41)
 
 ### Project Tools
 
@@ -140,12 +141,23 @@ 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). |
 
+### Knowledge Analytics Tools (orchestrator key)
+
+| Tool | Description |
+|---|---|
+| `knowledge_analytics_top` | Top accessed knowledge articles for the tenant. Optional: `limit` (default 20, max 100), `since_days` (default 7), `access_type` (`search`, `get`, `context`, `index`). |
+| `knowledge_article_stats` | Per-article usage stats: total accesses, unique agents, by-type breakdown, recent events. Required: `article_id`. |
+| `knowledge_agent_usage` | Per-agent (api_key) knowledge usage: total reads, unique articles, top read articles. Required: `agent_id`. Optional: `limit`, `since_days`. |
+| `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
+
 ### Discovery Tools
 
 | Tool | Description |

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`
@@ -489,11 +503,80 @@ async function knowledgeIngest({ url, content, source_type, project_id }) {
   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);
 }
 
+// --- Knowledge Analytics Tools (orch key) ---
+
+async function knowledgeAnalyticsTop({ limit, since_days, access_type } = {}) {
+  const params = new URLSearchParams();
+  if (limit != null) params.set("limit", String(limit));
+  if (since_days != null) params.set("since_days", String(since_days));
+  if (access_type) params.set("access_type", access_type);
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/analytics/top-articles?${qs}`
+    : "/api/v1/knowledge/analytics/top-articles";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
+async function knowledgeArticleStats({ article_id }) {
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/articles/${article_id}/stats`,
+    null,
+    process.env.LOOPCTL_ORCH_KEY
+  );
+  return toContent(result);
+}
+
+async function knowledgeAgentUsage({ agent_id, limit, since_days } = {}) {
+  const params = new URLSearchParams();
+  if (limit != null) params.set("limit", String(limit));
+  if (since_days != null) params.set("since_days", String(since_days));
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/analytics/agents/${agent_id}?${qs}`
+    : `/api/v1/knowledge/analytics/agents/${agent_id}`;
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
+async function knowledgeUnusedArticles({ days_unused, limit } = {}) {
+  const params = new URLSearchParams();
+  if (days_unused != null) params.set("days_unused", String(days_unused));
+  if (limit != null) params.set("limit", String(limit));
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/analytics/unused-articles?${qs}`
+    : "/api/v1/knowledge/analytics/unused-articles";
+  const result = await apiCall("GET", path, 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`
@@ -1208,20 +1291,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: [],
@@ -1231,7 +1345,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: {
@@ -1244,10 +1360,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: [],
@@ -1300,6 +1424,56 @@ const TOOLS = [
       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:
@@ -1312,6 +1486,106 @@ const TOOLS = [
     },
   },
 
+  // Knowledge Analytics Tools (orchestrator key)
+  {
+    name: "knowledge_analytics_top",
+    description:
+      "Return the top accessed knowledge articles for the tenant. " +
+      "Use to identify which articles agents actually read. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          description: "Max rows to return. Default 20, max 100.",
+          minimum: 1,
+          maximum: 100,
+        },
+        since_days: {
+          type: "integer",
+          description: "Look back this many days. Default 7.",
+          minimum: 1,
+          maximum: 365,
+        },
+        access_type: {
+          type: "string",
+          enum: ["search", "get", "context", "index"],
+          description: "Optional: restrict to a single access type.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_article_stats",
+    description:
+      "Return per-article usage statistics: total accesses, unique agents, " +
+      "by-type breakdown, and the 10 most recent events. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the article to inspect.",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
+  {
+    name: "knowledge_agent_usage",
+    description:
+      "Return knowledge usage for a specific agent (api_key): total reads, " +
+      "unique articles, access type breakdown, and top read articles. " +
+      "Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: {
+          type: "string",
+          description: "API key UUID identifying the agent identity.",
+        },
+        limit: {
+          type: "integer",
+          description: "Max top articles to return. Default 20, max 100.",
+          minimum: 1,
+          maximum: 100,
+        },
+        since_days: {
+          type: "integer",
+          description: "Look back this many days. Default 7.",
+          minimum: 1,
+          maximum: 365,
+        },
+      },
+      required: ["agent_id"],
+    },
+  },
+  {
+    name: "knowledge_unused_articles",
+    description:
+      "Return published articles that have not been accessed in the configured " +
+      "time window. Use to identify dead-weight knowledge. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        days_unused: {
+          type: "integer",
+          description: "Window length in days. Default 30.",
+          minimum: 1,
+          maximum: 365,
+        },
+        limit: {
+          type: "integer",
+          description: "Max rows to return. Default 50, max 200.",
+          minimum: 1,
+          maximum: 200,
+        },
+      },
+      required: [],
+    },
+  },
+
   // Discovery Tools
   {
     name: "list_routes",
@@ -1442,6 +1716,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);
 
@@ -1455,9 +1732,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_ingest":
       return await knowledgeIngest(args);
 
+    case "knowledge_ingest_batch":
+      return await knowledgeIngestBatch(args);
+
     case "knowledge_ingestion_jobs":
       return await knowledgeIngestionJobs();
 
+    // Knowledge Analytics Tools
+    case "knowledge_analytics_top":
+      return await knowledgeAnalyticsTop(args);
+
+    case "knowledge_article_stats":
+      return await knowledgeArticleStats(args);
+
+    case "knowledge_agent_usage":
+      return await knowledgeAgentUsage(args);
+
+    case "knowledge_unused_articles":
+      return await knowledgeUnusedArticles(args);
+
     // Discovery Tools
     case "list_routes":
       return await listRoutes();

package/package.json

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