loopctl-mcp-server 1.6.1 → 2.0.1

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 41 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+Wraps the loopctl REST API into 42 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
 
 ## Installation
 
@@ -66,7 +66,7 @@ Or if installed locally:
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
 
-## Tools (41)
+## Tools (42)
 
 ### Project Tools
 
@@ -75,6 +75,7 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 | `get_tenant` | Get current tenant info. Use to verify connectivity. |
 | `list_projects` | List all projects in the current tenant. |
 | `create_project` | Create a new project in the current tenant. |
+| `delete_project` | **Requires `LOOPCTL_USER_KEY`.** Delete a project and all of its dependent resources (epics, stories, audit entries). Irreversible — orchestrator role is not sufficient. |
 | `get_progress` | Get progress summary for a project, including story counts by status. Pass `include_cost=true` for cost data. |
 | `import_stories` | Import stories into a project from a structured payload (Epic 12 import format). |
 
@@ -130,10 +131,10 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 
 | 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_index` | Load the knowledge wiki catalog at session start. Returns lightweight article metadata grouped by category. Optional: `project_id`, `story_id`. |
+| `knowledge_search` | Search the knowledge wiki by topic. Supports keyword, semantic, or combined search modes. Returns snippets. Optional: `project_id`, `story_id` for attribution. |
+| `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Optional: `project_id`, `story_id` for attribution. |
+| `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. Optional: `project_id`, `story_id` for attribution. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. |
 
 ### Knowledge Management Tools (orchestrator key)
@@ -155,7 +156,7 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 |---|---|
 | `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_agent_usage` | Per-agent knowledge usage: total reads, unique articles, top read articles. Required: exactly one of `api_key_id` (credential) or `agent_id` (logical identity). Optional: `limit`, `since_days`. See Wiki Attribution section. |
 | `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
 
 ### Discovery Tools
@@ -164,6 +165,102 @@ Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_K
 |---|---|
 | `list_routes` | List all available API routes on the loopctl server. |
 
+## Wiki Attribution
+
+### Passing context parameters on wiki reads
+
+Four wiki read tools (`knowledge_search`, `knowledge_get`, `knowledge_context`, `knowledge_index`) accept two optional attribution parameters:
+
+| Parameter | Description |
+|---|---|
+| `project_id` | UUID of the loopctl project the agent is working on |
+| `story_id` | UUID of the loopctl story the agent is currently implementing |
+
+Passing these parameters lets loopctl record which project and story triggered each wiki read. The analytics endpoints (`knowledge_analytics_top`, `knowledge_agent_usage`, etc.) can then slice usage by project, showing which knowledge articles are most valuable per project.
+
+The server silently drops attribution params that belong to a different tenant or are malformed UUIDs — you will not receive an error for invalid values.
+
+**Always pass `story_id` when you are working on a loopctl story.** This is the primary mechanism by which wiki reads are attributed to development work.
+
+#### Example: typical implementation agent workflow
+
+Step 1 — fetch the story to pick up its UUID and context:
+
+```json
+{
+  "tool": "get_story",
+  "arguments": { "story_id": "89aa0c48-5cf5-4925-b164-21684ef79c4d" }
+}
+```
+
+Step 2 — call `knowledge_search`, passing `story_id` so the read is attributed:
+
+```json
+{
+  "tool": "knowledge_search",
+  "arguments": {
+    "q": "csv import bulk validation",
+    "project_id": "b50c9e38-aebe-4bbe-b8e6-bf2cb2b8afd0",
+    "story_id": "89aa0c48-5cf5-4925-b164-21684ef79c4d"
+  }
+}
+```
+
+Step 3 — call `knowledge_get`, reusing the same `story_id`:
+
+```json
+{
+  "tool": "knowledge_get",
+  "arguments": {
+    "article_id": "c3d2e1f0-1234-5678-abcd-ef0123456789",
+    "project_id": "b50c9e38-aebe-4bbe-b8e6-bf2cb2b8afd0",
+    "story_id": "89aa0c48-5cf5-4925-b164-21684ef79c4d"
+  }
+}
+```
+
+### `knowledge_agent_usage`: api_key_id vs agent_id
+
+The `knowledge_agent_usage` tool accepts **exactly one** of two identifier parameters:
+
+| Parameter | Meaning | When to use |
+|---|---|---|
+| `api_key_id` | The `api_keys.id` credential UUID — the raw API key identity | You have the credential ID from `GET /api/v1/api_keys` or a loopctl admin page |
+| `agent_id` | The `agents.id` logical identity UUID — the agent registry entry | You have the agent registry ID from `GET /api/v1/agents` or a story's `assigned_agent_id` |
+
+The server's analytics endpoint performs dual-resolution: it tries both interpretations automatically. However, using the explicit parameter makes your intent clear and avoids ambiguity in the response's `resolved_as` field.
+
+Passing both parameters returns a validation error. Passing neither also returns a validation error.
+
+```json
+// Query by credential (api_key_id)
+{
+  "tool": "knowledge_agent_usage",
+  "arguments": {
+    "api_key_id": "b977c90c-061b-4e42-8afa-26a5efde51ad",
+    "since_days": 7
+  }
+}
+
+// Query by logical agent identity (agent_id)
+{
+  "tool": "knowledge_agent_usage",
+  "arguments": {
+    "agent_id": "09429bc4-328f-42f4-acec-db48b40849b2",
+    "since_days": 30
+  }
+}
+```
+
+#### Deprecated: old `agent_id` behavior
+
+In versions before 1.2.0, `knowledge_agent_usage` accepted a single `agent_id` parameter that actually meant the `api_keys.id` credential (not the logical agent). This was confusing and caused silent zero-result responses when callers passed a logical `agents.id` value.
+
+Starting with 1.2.0:
+- `agent_id` means the **logical** `agents.id` (the agent registry entry).
+- `api_key_id` means the **credential** `api_keys.id` (the raw API key).
+- The old behavior (passing `agent_id` meaning credential) is Deprecated and will be removed in a future release. When you call with `agent_id` alone, the response includes a `_meta.deprecation_hint` nudging you toward explicit parameters.
+
 ## Chain-of-Custody Enforcement
 
 loopctl enforces that nobody marks their own work as done. The API returns `409` if the caller's identity matches the story's assigned agent:

package/index.js

@@ -12,9 +12,15 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // ---------------------------------------------------------------------------
-// HTTP helper
+// HTTP helper — witness protocol state
 // ---------------------------------------------------------------------------
 
+// The witness protocol requires clients to echo back the last-known Signed
+// Tree Head (STH) on every authenticated request. On the very first request
+// we send X-Loopctl-STH-Bootstrap: true to receive the current STH without
+// needing one already. After that we cache and send X-Loopctl-Last-Known-STH.
+let lastKnownSTH = null;
+
 function getBaseUrl() {
   return (process.env.LOOPCTL_SERVER || "https://loopctl.com").replace(/\/$/, "");
 }
@@ -43,13 +49,22 @@ async function apiCall(method, path, body, keyOverride) {
     return { error: true, status: 0, body: "No API key configured. Set LOOPCTL_API_KEY, LOOPCTL_ORCH_KEY, or LOOPCTL_AGENT_KEY." };
   }
 
+  const headers = {
+    Authorization: `Bearer ${key}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+
+  // Witness protocol: send cached STH or request bootstrap
+  if (lastKnownSTH) {
+    headers["X-Loopctl-Last-Known-STH"] = lastKnownSTH;
+  } else {
+    headers["X-Loopctl-STH-Bootstrap"] = "true";
+  }
+
   const options = {
     method,
-    headers: {
-      Authorization: `Bearer ${key}`,
-      "Content-Type": "application/json",
-      Accept: "application/json",
-    },
+    headers,
     signal: AbortSignal.timeout(30_000),
   };
 
@@ -68,6 +83,12 @@ async function apiCall(method, path, body, keyOverride) {
     return { error: true, status: 0, body: `Network error: ${err.message}${cause}` };
   }
 
+  // Witness protocol: cache the STH from response for subsequent requests
+  const sthHeader = response.headers.get("x-loopctl-current-sth");
+  if (sthHeader) {
+    lastKnownSTH = sthHeader;
+  }
+
   if (response.status === 204) {
     return { ok: true };
   }
@@ -416,17 +437,22 @@ async function setTokenBudget({ scope_type, scope_id, budget_millicents, alert_t
 
 // --- Knowledge Wiki Tools (agent key) ---
 
-async function knowledgeIndex({ project_id }) {
-  const path = project_id
+async function knowledgeIndex({ project_id, story_id }) {
+  const basePath = project_id
     ? `/api/v1/projects/${project_id}/knowledge/index`
     : "/api/v1/knowledge/index";
+  const params = new URLSearchParams();
+  if (story_id) params.set("story_id", story_id);
+  const qs = params.toString();
+  const path = qs ? `${basePath}?${qs}` : basePath;
   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 }) {
+async function knowledgeSearch({ q, project_id, story_id, category, tags, mode, limit }) {
   const params = new URLSearchParams({ q });
   if (project_id) params.set("project_id", project_id);
+  if (story_id) params.set("story_id", story_id);
   if (category) params.set("category", category);
   if (tags) params.set("tags", tags);
   if (mode) params.set("mode", mode);
@@ -436,14 +462,20 @@ async function knowledgeSearch({ q, project_id, category, tags, mode, limit }) {
   return toContent(result);
 }
 
-async function knowledgeGet({ article_id }) {
-  const result = await apiCall("GET", `/api/v1/articles/${article_id}`, null, process.env.LOOPCTL_AGENT_KEY);
+async function knowledgeGet({ article_id, project_id, story_id }) {
+  const params = new URLSearchParams();
+  if (project_id) params.set("project_id", project_id);
+  if (story_id) params.set("story_id", story_id);
+  const qs = params.toString();
+  const path = qs ? `/api/v1/articles/${article_id}?${qs}` : `/api/v1/articles/${article_id}`;
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
 
-async function knowledgeContext({ query, project_id, limit, recency_weight }) {
+async function knowledgeContext({ query, project_id, story_id, limit, recency_weight }) {
   const params = new URLSearchParams({ query });
   if (project_id) params.set("project_id", project_id);
+  if (story_id) params.set("story_id", story_id);
   if (limit != null) params.set("limit", String(limit));
   if (recency_weight != null) params.set("recency_weight", String(recency_weight));
 
@@ -564,15 +596,70 @@ async function knowledgeArticleStats({ article_id }) {
   return toContent(result);
 }
 
-async function knowledgeAgentUsage({ agent_id, limit, since_days } = {}) {
+// Canonical 8-4-4-4-12 UUID shape. Used to reject path-injection attempts
+// in tools that interpolate user-supplied IDs into URL path segments.
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+async function knowledgeAgentUsage({ api_key_id, agent_id, limit, since_days } = {}) {
+  // Normalize: treat empty strings / whitespace-only strings as missing so the
+  // validation below catches them. Otherwise an empty string would slip past
+  // the `!= null` checks and produce a malformed URL like /agents/.
+  const normalizedApiKeyId =
+    typeof api_key_id === "string" && api_key_id.trim() === "" ? null : api_key_id;
+  const normalizedAgentId =
+    typeof agent_id === "string" && agent_id.trim() === "" ? null : agent_id;
+
+  // Validate: exactly one of api_key_id or agent_id must be provided.
+  if (normalizedApiKeyId != null && normalizedAgentId != null) {
+    return {
+      content: [{ type: "text", text: "Error: pass exactly one of api_key_id or agent_id, not both. Use api_key_id for the api_keys.id credential; use agent_id for the agents.id logical identity." }],
+      isError: true,
+    };
+  }
+  if (normalizedApiKeyId == null && normalizedAgentId == null) {
+    return {
+      content: [{ type: "text", text: "Error: pass exactly one of api_key_id or agent_id. Use api_key_id for the api_keys.id credential; use agent_id for the agents.id logical identity." }],
+      isError: true,
+    };
+  }
+
+  const resolvedId = normalizedApiKeyId ?? normalizedAgentId;
+
+  // Defense-in-depth: the MCP SDK declares `format: "uuid"` on these schemas
+  // but does not enforce it for tool arguments. Because `resolvedId` is
+  // interpolated directly into a URL path segment, a value containing `/`
+  // or `..` would let `fetch()` normalize the request to a different
+  // endpoint. Reject anything that isn't a canonical UUID before we touch
+  // the network.
+  if (typeof resolvedId !== "string" || !UUID_RE.test(resolvedId)) {
+    const which = normalizedApiKeyId != null ? "api_key_id" : "agent_id";
+    return {
+      content: [{ type: "text", text: `Error: ${which} must be a canonical UUID (8-4-4-4-12 hex).` }],
+      isError: true,
+    };
+  }
   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}`;
+    ? `/api/v1/knowledge/analytics/agents/${resolvedId}?${qs}`
+    : `/api/v1/knowledge/analytics/agents/${resolvedId}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+
+  // When agent_id alone is passed (new semantic: logical agents.id), emit a
+  // one-release-cycle nudge so callers can be explicit about their intent.
+  if (normalizedAgentId != null && normalizedApiKeyId == null) {
+    const base = toContent(result);
+    return {
+      ...base,
+      _meta: {
+        deprecation_hint:
+          "knowledge_agent_usage: if you meant the api_keys.id credential, pass it as api_key_id explicitly. The agent_id parameter now refers to the logical agents.id only.",
+      },
+    };
+  }
+
   return toContent(result);
 }
 
@@ -613,6 +700,51 @@ async function listRoutes() {
   return toContent(result);
 }
 
+// US-26.2.3: Dispatch lineage tool
+async function createDispatch({
+  parent_dispatch_id,
+  role,
+  story_id,
+  agent_id,
+  expires_in_seconds = 3600,
+}) {
+  const body = { role, agent_id, expires_in_seconds };
+  if (parent_dispatch_id) body.parent_dispatch_id = parent_dispatch_id;
+  if (story_id) body.story_id = story_id;
+
+  const result = await apiCall("POST", "/api/v1/dispatches", body);
+  return toContent(result);
+}
+
+// US-26: Signed Tree Head retrieval
+async function getSth({ tenant_id }) {
+  const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
+  return toContent(result);
+}
+
+// US-26: System article retrieval
+async function getSystemArticles({ slug, category } = {}) {
+  const params = new URLSearchParams();
+  if (slug) params.set("slug", slug);
+  if (category) params.set("category", category);
+  const qs = params.toString();
+  const result = await apiCall("GET", `/api/v1/articles/system${qs ? "?" + qs : ""}`);
+  return toContent(result);
+}
+
+// US-26: Cap recovery after session crash
+async function recoverCap({ story_id, cap_type, lineage }) {
+  const body = { cap_type: cap_type || "start_cap", lineage: lineage || [] };
+  const result = await apiCall("POST", `/api/v1/stories/${story_id}/recover-cap`, body);
+  return toContent(result);
+}
+
+// US-26: Acceptance criteria for a story
+async function getAcceptanceCriteria({ story_id }) {
+  const result = await apiCall("GET", `/api/v1/stories/${story_id}/acceptance_criteria`);
+  return toContent(result);
+}
+
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
@@ -1177,15 +1309,21 @@ const TOOLS = [
   {
     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.",
+      "Load the knowledge wiki catalog at session start. Returns article metadata grouped by category. " +
+      "Pass story_id when working on a loopctl story so reads attribute correctly.",
     inputSchema: {
       type: "object",
       properties: {
         project_id: {
           type: "string",
+          format: "uuid",
           description: "Optional: scope the index to a specific project UUID.",
         },
+        story_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: loopctl story UUID for attribution tracking.",
+        },
       },
       required: [],
     },
@@ -1193,8 +1331,8 @@ const TOOLS = [
   {
     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.",
+      "Search the knowledge wiki by topic. Returns snippets. " +
+      "Pass story_id when working on a loopctl story so reads attribute correctly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1204,8 +1342,14 @@ const TOOLS = [
         },
         project_id: {
           type: "string",
+          format: "uuid",
           description: "Optional: scope search to a specific project UUID.",
         },
+        story_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: loopctl story UUID for attribution tracking.",
+        },
         category: {
           type: "string",
           description: "Optional: filter results by category.",
@@ -1230,14 +1374,26 @@ const TOOLS = [
   {
     name: "knowledge_get",
     description:
-      "Get full article content by ID. Use after search to read an article in detail.",
+      "Get full article content by ID. Use after search to read an article in detail. " +
+      "Pass story_id when working on a loopctl story so reads attribute correctly.",
     inputSchema: {
       type: "object",
       properties: {
         article_id: {
           type: "string",
+          format: "uuid",
           description: "The UUID of the article.",
         },
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: project UUID for attribution tracking.",
+        },
+        story_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: loopctl story UUID for attribution tracking.",
+        },
       },
       required: ["article_id"],
     },
@@ -1245,8 +1401,8 @@ const TOOLS = [
   {
     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.",
+      "Get ranked full articles for a task query. Returns best knowledge with linked references. " +
+      "Pass story_id when working on a loopctl story so reads attribute correctly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1256,8 +1412,14 @@ const TOOLS = [
         },
         project_id: {
           type: "string",
+          format: "uuid",
           description: "Optional: scope context to a specific project UUID.",
         },
+        story_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: loopctl story UUID for attribution tracking.",
+        },
         limit: {
           type: "integer",
           description: "Optional: maximum number of articles to return.",
@@ -1566,15 +1728,21 @@ const TOOLS = [
   {
     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. " +
+      "Return knowledge usage for an agent: total reads, unique articles, top read articles. " +
+      "Pass api_key_id (api_keys.id credential) OR agent_id (agents.id logical identity) — not both. " +
       "Requires orchestrator role.",
     inputSchema: {
       type: "object",
       properties: {
+        api_key_id: {
+          type: "string",
+          format: "uuid",
+          description: "The api_keys.id credential UUID. Use this when you have the raw API key ID.",
+        },
         agent_id: {
           type: "string",
-          description: "API key UUID identifying the agent identity.",
+          format: "uuid",
+          description: "The agents.id logical identity UUID. Use this when you have the agent registry ID.",
         },
         limit: {
           type: "integer",
@@ -1589,7 +1757,7 @@ const TOOLS = [
           maximum: 365,
         },
       },
-      required: ["agent_id"],
+      required: [],
     },
   },
   {
@@ -1627,6 +1795,91 @@ const TOOLS = [
       required: [],
     },
   },
+
+  // Dispatch Tool (US-26.2.3)
+  {
+    name: "dispatch",
+    description:
+      "Mint an ephemeral api_key for a sub-agent dispatch. " +
+      "The raw_key is returned ONCE — pass it to the sub-agent via its launch arguments, " +
+      "never store it in env vars. The key expires after expires_in_seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        parent_dispatch_id: {
+          type: "string",
+          description: "UUID of the parent dispatch (omit for root dispatch).",
+        },
+        role: {
+          type: "string",
+          enum: ["agent", "orchestrator"],
+          description: "Role for the sub-agent.",
+        },
+        story_id: {
+          type: "string",
+          description: "Optional: UUID of the story this dispatch is for.",
+        },
+        agent_id: {
+          type: "string",
+          description: "UUID of the agent being dispatched.",
+        },
+        expires_in_seconds: {
+          type: "integer",
+          description: "Key lifetime in seconds (default 3600, max 14400).",
+          default: 3600,
+        },
+      },
+      required: ["role", "agent_id"],
+    },
+  },
+
+  // Chain of Custody v2 tools
+  {
+    name: "get_sth",
+    description: "Get the latest Signed Tree Head for a tenant's audit chain. Public — no auth required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+      },
+      required: ["tenant_id"],
+    },
+  },
+  {
+    name: "get_system_articles",
+    description: "List or retrieve system-scoped wiki articles. Public — no auth required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "Optional: fetch a single article by slug." },
+        category: { type: "string", description: "Optional: filter by category (pattern, convention, decision, finding, reference)." },
+      },
+    },
+  },
+  {
+    name: "recover_cap",
+    description: "Re-mint a capability token for a story you're assigned to. Use after a session crash when you've lost your cap.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "Story UUID." },
+        cap_type: { type: "string", enum: ["start_cap", "report_cap"], description: "Which cap to recover (default: start_cap)." },
+        lineage: { type: "array", items: { type: "string" }, description: "Your dispatch lineage path." },
+      },
+      required: ["story_id"],
+    },
+  },
+  {
+    name: "get_acceptance_criteria",
+    description: "List acceptance criteria for a story with their verification status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "Story UUID." },
+      },
+      required: ["story_id"],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1636,7 +1889,7 @@ const TOOLS = [
 const server = new Server(
   {
     name: "loopctl",
-    version: "1.1.2",
+    version: "1.2.0",
   },
   {
     capabilities: { tools: {} },
@@ -1789,6 +2042,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "list_routes":
       return await listRoutes();
 
+    case "dispatch":
+      return await createDispatch(args);
+
+    case "get_sth":
+      return await getSth(args);
+
+    case "get_system_articles":
+      return await getSystemArticles(args);
+
+    case "recover_cap":
+      return await recoverCap(args);
+
+    case "get_acceptance_criteria":
+      return await getAcceptanceCriteria(args);
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "1.6.1",
+  "version": "2.0.1",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,8 @@
     "loopctl-mcp-server": "index.js"
   },
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "test": "node --test"
   },
   "keywords": [
     "mcp",