loopctl-mcp-server 1.1.2 → 1.3.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 35 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 (35)
 
 ### Project Tools
 
@@ -125,6 +125,27 @@ 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`. |
+| `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_ingestion_jobs` | List recent content ingestion jobs (last 7 days, max 50). |
+
 ### Discovery Tools
 
 | Tool | Description |

package/index.js

@@ -403,6 +403,115 @@ 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 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 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`
+    : "/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() {
@@ -950,6 +1059,259 @@ 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: [],
+    },
+  },
+
+  // 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_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",
@@ -1060,6 +1422,42 @@ 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);
+
+    // Knowledge Ingestion Tools
+    case "knowledge_ingest":
+      return await knowledgeIngest(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.1.2",
+  "version": "1.3.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",