@kaddo/mcp 3.21.0 → 3.22.0

package/dist/index.js

@@ -504,8 +504,12 @@ function projectStatus(root) {
       withOwnership: explain.ownership?.workItemsWithOwnership ?? 0,
       total: explain.ownership?.workItemsTotal ?? 0
     },
-    graphQuality: hints?.quality ?? "unknown (run `kaddo graph export`)",
-    graphHints: hints?.summary?.hints ?? 0,
+    graph: {
+      scope: hints?.scope ?? "unknown (run `kaddo graph export`)",
+      scope_reason: hints?.scope_reason ?? "",
+      quality: hints?.quality ?? "unknown (run `kaddo graph export`)",
+      hints: hints?.summary?.hints ?? 0
+    },
     capsules: capsules.length
   });
 }
@@ -553,7 +557,13 @@ function listGraphHints(root, filter = {}) {
   if (filter.artifact_type) hints = hints.filter((h) => h.artifact_type === filter.artifact_type);
   if (filter.severity) hints = hints.filter((h) => h.severity === filter.severity);
   if (filter.active_only) hints = hints.filter((h) => h.artifact_type === "work-item");
-  return ok({ quality: report.quality ?? "unknown", count: hints.length, hints });
+  return ok({
+    scope: report.scope ?? "active",
+    scope_reason: report.scope_reason ?? "",
+    quality: report.quality ?? "unknown",
+    count: hints.length,
+    hints
+  });
 }
 
 // ../cli/src/core/config.ts
@@ -1521,6 +1531,11 @@ function loadExternalCapsules(dir) {
 
 // ../cli/src/core/graph.ts
 var KNOWLEDGE3 = "knowledge";
+var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
+var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
+function scopeStatuses(scope) {
+  return scope === "all" ? { included: ALL_STATUSES, excluded: ["archived"] } : { included: ACTIVE_STATUSES, excluded: ["completed", "archived"] };
+}
 function toPosix3(p) {
   return p.replace(/\\/g, "/");
 }
@@ -1563,7 +1578,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   }
   const all = discoverKnowledge(dir);
   const workItems = all.filter((a) => a.isWorkItem);
-  const selectedWIs = scope === "active" ? workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)) : workItems;
+  const { included, excluded } = scopeStatuses(scope);
+  const includedSet = new Set(included);
+  const activeWICount = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)).length;
+  const selectedWIs = workItems.filter((a) => a.lifecycle && includedSet.has(a.lifecycle));
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     const wiNodeId = `wi:${id}`;
@@ -1633,6 +1651,7 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
   }
+  const scopeReason = scope === "all" ? "All supported Work Item statuses are included." : activeWICount === 0 ? "No active Work Items found. Completed Work Items are excluded from active scope." : "Active Work Items only; completed and archived are excluded.";
   return {
     generated_at: now.toISOString(),
     project: {
@@ -1640,6 +1659,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       state: config.project.state,
       structure: config.project.structure
     },
+    scope,
+    scope_reason: scopeReason,
+    included_statuses: included,
+    excluded_statuses: excluded,
     nodes: [...nodes.values()],
     edges
   };
@@ -1687,8 +1710,13 @@ function loadGraphSummary(dir) {
     const connected = new Set(
       edges.filter((e) => e.type === "owns" && activeWiIds.has(e.from)).map((e) => e.from)
     );
+    const scope = graph.scope === "all" ? "all" : "active";
     return {
       generatedAt: String(graph.generated_at ?? ""),
+      scope,
+      scopeReason: String(graph.scope_reason ?? ""),
+      includedStatuses: Array.isArray(graph.included_statuses) ? graph.included_statuses : [],
+      excludedStatuses: Array.isArray(graph.excluded_statuses) ? graph.excluded_statuses : [],
       nodes: nodes.length,
       edges: edges.length,
       activeWorkItemsConnectedToCode: connected.size
@@ -1840,6 +1868,8 @@ function buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
   const quality = assessQuality(nodes, relationshipEdges, hints.length);
   return {
     generated_at: now.toISOString(),
+    scope: graph.scope,
+    scope_reason: graph.scope_reason,
     quality,
     summary: { nodes, edges: graph.edges.length, hints: hints.length },
     metrics,
@@ -1875,13 +1905,23 @@ function renderGraphHintsMarkdown(report) {
   lines.push("");
   lines.push("## Summary");
   lines.push("");
+  lines.push(`- Scope: ${report.scope} \u2014 ${report.scope_reason}`);
   lines.push(`- Relationship quality: ${report.quality} \u2014 ${QUALITY_NOTE[report.quality]}`);
   lines.push(`- Nodes: ${report.summary.nodes}`);
   lines.push(`- Edges: ${report.summary.edges}`);
   lines.push(`- Hints: ${report.summary.hints}`);
   lines.push("");
   if (report.hints.length === 0) {
-    lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    if (report.quality === "empty") {
+      lines.push("No active relationship hints were generated.");
+      lines.push("");
+      lines.push(`The graph is ${report.quality} for the **${report.scope}** scope \u2014 ${report.scope_reason}`);
+      if (report.scope !== "all") {
+        lines.push("Run `kaddo graph export --scope all` to inspect completed Work Items and historical relationships.");
+      }
+    } else {
+      lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    }
     lines.push("");
     return lines.join("\n");
   }
@@ -1917,6 +1957,8 @@ function loadGraphHints(dir) {
     const report = JSON.parse(readFile(p));
     const hints = Array.isArray(report.hints) ? report.hints : [];
     return {
+      scope: String(report.scope ?? "active"),
+      scopeReason: String(report.scope_reason ?? ""),
       quality: report.quality ?? "empty",
       totalHints: hints.length,
       activeWorkItemHints: hints.filter((h) => h.artifact_type === "work-item").length,
@@ -2316,9 +2358,12 @@ function renderContextPack(pack) {
     parts.push(
       [
         "- Available: yes",
+        `- Scope: ${pack.graph.scope}`,
         `- Nodes: ${pack.graph.nodes}`,
         `- Edges: ${pack.graph.edges}`,
-        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`
+        ...pack.graphHints ? [`- Quality: ${pack.graphHints.quality}`] : [],
+        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`,
+        ...pack.graph.scopeReason ? [`- Reason: ${pack.graph.scopeReason}`] : []
       ].join("\n") + "\n"
     );
     parts.push("Full graph: `.kaddo/graph.json` / `.kaddo/graph.mmd` (run `kaddo graph export` to refresh).\n");
@@ -2709,13 +2754,18 @@ function renderExplanationHuman(exp) {
   }
   if (exp.graph) {
     lines.push("## Knowledge Graph");
+    lines.push(`- Scope: ${exp.graph.scope}`);
     lines.push(`- Nodes: ${exp.graph.nodes}`);
     lines.push(`- Edges: ${exp.graph.edges}`);
     if (exp.graphHints) {
       lines.push(`- Quality: ${exp.graphHints.quality}`);
       lines.push(`- Hints: ${exp.graphHints.totalHints}`);
     }
+    if (exp.graph.scopeReason) lines.push(`- Reason: ${exp.graph.scopeReason}`);
     if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
+    if (exp.graph.scope === "active" && exp.graphHints?.quality === "empty") {
+      lines.push("- Tip: Run `kaddo graph export --scope all` to include completed Work Items");
+    }
     lines.push("");
   }
   if (exp.skills.total > 0) {
@@ -2973,10 +3023,10 @@ function generateUnderstand(root) {
     next_suggested_resources: ["kaddo://understand"]
   };
 }
-function generateGraph(root) {
+function generateGraph(root, scope = "active") {
   const config = requireConfig(root);
   requireKnowledge(root);
-  const graph = buildGraph(root, config, { scope: "active" });
+  const graph = buildGraph(root, config, { scope });
   const hints = buildGraphHints(root, graph);
   writeDerived(root, ".kaddo/graph.json", serializeGraphJson(graph));
   writeDerived(root, ".kaddo/graph.mmd", renderGraphMermaid(graph));
@@ -2991,7 +3041,7 @@ function generateGraph(root) {
       ".kaddo/graph-hints.md",
       ".kaddo/graph-hints.json"
     ],
-    summary: "Knowledge graph and hints generated successfully.",
+    summary: `Knowledge graph and hints generated successfully (${scope} scope).`,
     warnings,
     next_suggested_resources: ["kaddo://graph", "kaddo://graph-hints"]
   };
@@ -3172,8 +3222,12 @@ function createServer(root) {
   );
   server.registerTool(
     "kaddo_generate_graph",
-    { title: "Generate knowledge graph", description: `Regenerate .kaddo/graph.json/.mmd + graph-hints.md/.json. ${DERIVED_NOTE}`, inputSchema: {} },
-    async () => generated(root, "generate knowledge graph", () => generateGraph(root))
+    {
+      title: "Generate knowledge graph",
+      description: `Regenerate .kaddo/graph.json/.mmd + graph-hints.md/.json. scope: active (default) or all. ${DERIVED_NOTE}`,
+      inputSchema: { scope: z2.enum(["active", "all"]).optional() }
+    },
+    async (args) => generated(root, "generate knowledge graph", () => generateGraph(root, args.scope ?? "active"))
   );
   server.registerTool(
     "kaddo_generate_capsule_draft",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {