loopctl-mcp-server 1.1.1 → 1.2.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 24 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+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.
 
 ## Installation
 
@@ -65,7 +65,7 @@ Or if installed locally:
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
 
-## Tools (24)
+## Tools (33)
 
 ### Project Tools
 
@@ -125,6 +125,25 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `get_cost_anomalies` | orch | Get cost anomaly alerts — stories or agents exceeding expected budgets. Optionally filter by project. |
 | `set_token_budget` | orch | Set a token budget (in millicents) for a project, epic, story, or agent scope. Requires orchestrator role. |
 
+### Knowledge Wiki Tools (agent key)
+
+| Tool | Description |
+|---|---|
+| `knowledge_index` | Load the knowledge wiki catalog at session start. Returns lightweight article metadata grouped by category. |
+| `knowledge_search` | Search the knowledge wiki by topic. Supports keyword, semantic, or combined search modes. Returns snippets. |
+| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. |
+| `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. |
+| `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. |
+
+### Knowledge Management Tools (orchestrator key)
+
+| 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_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`. |
+
 ### Discovery Tools
 
 | Tool | Description |

package/index.js

@@ -116,10 +116,12 @@ function toContent(result) {
 }
 
 /**
- * Compact variant for list endpoints — strips bulky fields (acceptance_criteria,
- * description) from each story to stay within token limits. Callers can use
- * get_story for full details on individual stories.
+ * Compact variant for list endpoints — strips acceptance_criteria and
+ * description (use get_story for full details). Keeps all other fields.
+ * Enforces a max page size to prevent MCP response token overflow.
  */
+const MAX_PAGE_SIZE = 20;
+
 function toContentCompact(result) {
   if (result && result.error === true) return toContent(result);
 
@@ -191,7 +193,7 @@ async function listStories({ project_id, agent_status, verified_status, epic_id,
   if (agent_status) params.set("agent_status", agent_status);
   if (verified_status) params.set("verified_status", verified_status);
   if (epic_id) params.set("epic_id", epic_id);
-  params.set("limit", String(limit ?? 20));
+  params.set("limit", String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE)));
   if (offset != null) params.set("offset", String(offset));
   if (include_token_totals) params.set("include_token_totals", "true");
 
@@ -201,7 +203,7 @@ async function listStories({ project_id, agent_status, verified_status, epic_id,
 
 async function listReadyStories({ project_id, limit }) {
   const params = new URLSearchParams({ project_id });
-  params.set("limit", String(limit ?? 20));
+  params.set("limit", String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE)));
 
   const result = await apiCall("GET", `/api/v1/stories/ready?${params}`);
   return toContentCompact(result);
@@ -401,6 +403,101 @@ async function setTokenBudget({ scope_type, scope_id, budget_millicents, alert_t
   return toContent(result);
 }
 
+// --- Knowledge Wiki Tools (agent key) ---
+
+async function knowledgeIndex({ project_id }) {
+  const path = project_id
+    ? `/api/v1/projects/${project_id}/knowledge/index`
+    : "/api/v1/knowledge/index";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeSearch({ q, project_id, category, tags, mode, limit }) {
+  const params = new URLSearchParams({ q });
+  if (project_id) params.set("project_id", project_id);
+  if (category) params.set("category", category);
+  if (tags) params.set("tags", tags);
+  if (mode) params.set("mode", mode);
+  if (limit != null) params.set("limit", String(limit));
+
+  const result = await apiCall("GET", `/api/v1/knowledge/search?${params}`, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeGet({ article_id }) {
+  const result = await apiCall("GET", `/api/v1/articles/${article_id}`, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeContext({ query, project_id, limit, recency_weight }) {
+  const params = new URLSearchParams({ query });
+  if (project_id) params.set("project_id", project_id);
+  if (limit != null) params.set("limit", String(limit));
+  if (recency_weight != null) params.set("recency_weight", String(recency_weight));
+
+  const result = await apiCall("GET", `/api/v1/knowledge/context?${params}`, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeCreate({ title, body, category, tags, project_id }) {
+  const payload = { title, body };
+  if (category) payload.category = category;
+  if (tags) payload.tags = tags;
+  if (project_id) payload.project_id = project_id;
+
+  const result = await apiCall("POST", "/api/v1/articles", payload, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+// --- Knowledge Management Tools (orch key) ---
+
+async function knowledgePublish({ article_id }) {
+  const result = await apiCall("POST", `/api/v1/articles/${article_id}/publish`, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
+async function knowledgeDrafts({ limit, offset }) {
+  const params = new URLSearchParams();
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  const qs = params.toString();
+  const path = qs ? `/api/v1/knowledge/drafts?${qs}` : "/api/v1/knowledge/drafts";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
+async function knowledgeLint({ project_id, stale_days, min_coverage }) {
+  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));
+  const qs = params.toString();
+  const basePath = project_id
+    ? `/api/v1/projects/${project_id}/knowledge/lint`
+    : "/api/v1/knowledge/lint";
+  const path = qs ? `${basePath}?${qs}` : basePath;
+  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`
+    : "/api/v1/knowledge/export";
+  const baseUrl = getBaseUrl();
+  const downloadCmd = `curl -H "Authorization: Bearer $LOOPCTL_ORCH_KEY" "${baseUrl}${basePath}" -o knowledge-export.zip`;
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        message: "Knowledge export produces a ZIP file. Use the curl command below to download it directly.",
+        command: downloadCmd,
+        endpoint: `${baseUrl}${basePath}`,
+      }, null, 2),
+    }],
+  };
+}
+
 // --- Discovery Tools ---
 
 async function listRoutes() {
@@ -490,7 +587,8 @@ const TOOLS = [
     description:
       "List stories for a project, optionally filtered by agent_status, verified_status, or epic_id. " +
       "Returns compact results (no acceptance_criteria/description) — use get_story for full details. " +
-      "Defaults to 20 stories per page; use limit/offset to paginate.",
+      "Max 20 per page. Use offset to paginate (response includes total_count). " +
+      "Filter by epic_id or agent_status to reduce result size.",
     inputSchema: {
       type: "object",
       properties: {
@@ -531,7 +629,8 @@ const TOOLS = [
     name: "list_ready_stories",
     description:
       "List stories that are ready to be worked on (contracted, dependencies met). " +
-      "Returns compact results — use get_story for full details. Defaults to 20 per page.",
+      "Returns compact results — use get_story for full details. " +
+      "Max 20 per page. Response includes total_count for pagination.",
     inputSchema: {
       type: "object",
       properties: {
@@ -946,6 +1045,217 @@ const TOOLS = [
     },
   },
 
+  // Knowledge Wiki Tools (agent key)
+  {
+    name: "knowledge_index",
+    description:
+      "Load the knowledge wiki catalog at session start. Returns lightweight article metadata " +
+      "(titles, categories, tags) grouped by category. Use this to discover available knowledge before searching.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description: "Optional: scope the index to a specific project UUID.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_search",
+    description:
+      "Search the knowledge wiki by topic. Supports keyword, semantic, or combined search modes. " +
+      "Returns snippets, not full bodies. Use after index to find specific articles.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: {
+          type: "string",
+          description: "Search query string.",
+        },
+        project_id: {
+          type: "string",
+          description: "Optional: scope search to a specific project UUID.",
+        },
+        category: {
+          type: "string",
+          description: "Optional: filter results by category.",
+        },
+        tags: {
+          type: "string",
+          description: "Optional: comma-separated tags to filter by.",
+        },
+        mode: {
+          type: "string",
+          enum: ["keyword", "semantic", "combined"],
+          description: "Optional: search mode (keyword, semantic, or combined).",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: maximum number of results to return.",
+        },
+      },
+      required: ["q"],
+    },
+  },
+  {
+    name: "knowledge_get",
+    description:
+      "Get full article content by ID. Use after search to read an article in detail.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the article.",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
+  {
+    name: "knowledge_context",
+    description:
+      "Get relevance-and-recency-ranked full articles for a task query. Returns the best knowledge " +
+      "for your current context with linked references. Use when starting a task that needs domain knowledge.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The task or topic query to find relevant knowledge for.",
+        },
+        project_id: {
+          type: "string",
+          description: "Optional: scope context to a specific project UUID.",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: maximum number of articles to return.",
+        },
+        recency_weight: {
+          type: "number",
+          description: "Optional: weight for recency scoring (0.0-1.0).",
+          minimum: 0,
+          maximum: 1,
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "knowledge_create",
+    description:
+      "Create a new knowledge article. Use to file findings, document patterns, or record decisions " +
+      "discovered during implementation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Article title.",
+        },
+        body: {
+          type: "string",
+          description: "Article body content (Markdown supported).",
+        },
+        category: {
+          type: "string",
+          description: "Optional: article category.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional: list of tags.",
+        },
+        project_id: {
+          type: "string",
+          description: "Optional: associate the article with a project UUID.",
+        },
+      },
+      required: ["title", "body"],
+    },
+  },
+
+  // Knowledge Management Tools (orchestrator key)
+  {
+    name: "knowledge_publish",
+    description:
+      "Publish a draft knowledge article, making it visible to all agents. Requires orchestrator role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the draft article to publish.",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
+  {
+    name: "knowledge_drafts",
+    description:
+      "List all draft (unpublished) knowledge articles. Requires orchestrator role. Use to review pending articles before publishing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          description: "Optional: maximum number of drafts to return.",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: pagination offset.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description: "Optional: scope lint to a specific project UUID.",
+        },
+        stale_days: {
+          type: "integer",
+          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,
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_export",
+    description:
+      "Export all knowledge articles as a ZIP archive. Because ZIP binary cannot be returned as MCP content, " +
+      "this tool returns a curl command you can run directly to download the archive.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description: "Optional: scope export to a specific project UUID.",
+        },
+      },
+      required: [],
+    },
+  },
+
   // Discovery Tools
   {
     name: "list_routes",
@@ -965,7 +1275,7 @@ const TOOLS = [
 const server = new Server(
   {
     name: "loopctl",
-    version: "1.1.1",
+    version: "1.1.2",
   },
   {
     capabilities: { tools: {} },
@@ -1056,6 +1366,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "set_token_budget":
       return await setTokenBudget(args);
 
+    // Knowledge Wiki Tools
+    case "knowledge_index":
+      return await knowledgeIndex(args);
+
+    case "knowledge_search":
+      return await knowledgeSearch(args);
+
+    case "knowledge_get":
+      return await knowledgeGet(args);
+
+    case "knowledge_context":
+      return await knowledgeContext(args);
+
+    case "knowledge_create":
+      return await knowledgeCreate(args);
+
+    // Knowledge Management Tools
+    case "knowledge_publish":
+      return await knowledgePublish(args);
+
+    case "knowledge_drafts":
+      return await knowledgeDrafts(args);
+
+    case "knowledge_lint":
+      return await knowledgeLint(args);
+
+    case "knowledge_export":
+      return await knowledgeExport(args);
+
     // Discovery Tools
     case "list_routes":
       return await listRoutes();

package/package.json

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