@kaddo/mcp 3.79.0 → 3.81.0

package/dist/index.js

@@ -480,8 +480,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path4 = i.path.join(".");
-      return path4 ? `  - ${path4}: ${i.message}` : `  - ${i.message}`;
+      const path5 = i.path.join(".");
+      return path5 ? `  - ${path5}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -922,11 +922,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path4 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path4)) return [];
+  const path5 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path5)) return [];
   let parsed;
   try {
-    parsed = parseYaml4(readFile(path4));
+    parsed = parseYaml4(readFile(path5));
   } catch {
     return [];
   }
@@ -2433,7 +2433,7 @@ function sectionParagraph2(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path4, md) {
+function parseCapsule(id, path5, md) {
   const { data } = matter4(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -2443,7 +2443,7 @@ function parseCapsule(id, path4, md) {
   }
   return {
     id,
-    path: path4,
+    path: path5,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -2505,9 +2505,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path4 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
-    if (path4) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path4 });
+    const path5 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
+    if (path5) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path5 });
       presentLayers.push(layer2.id);
     }
   }
@@ -4088,10 +4088,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path4 = agentInstallPath(file);
-    const installed = isFile(join(dir, path4));
+    const path5 = agentInstallPath(file);
+    const installed = isFile(join(dir, path5));
     const group = agentGroupOf(file);
-    return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path5, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -9131,7 +9131,7 @@ function buildGuardHistory(dir) {
     const d3 = hotspotDir(t.code_path);
     hotspotMap.set(d3, (hotspotMap.get(d3) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path4, warnings]) => ({ path: path4, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path5, warnings]) => ({ path: path5, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -11140,6 +11140,520 @@ ${list2(data.owners)}
   ].join("\n");
 }
 
+// ../cli/src/core/system-topology.ts
+import { parse as parseYaml11, stringify as stringifyYaml5 } from "yaml";
+import fs4 from "fs";
+import path4 from "path";
+import crypto from "crypto";
+var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
+var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
+  "system",
+  "application",
+  "service",
+  "component",
+  "api",
+  "interface",
+  "datastore",
+  "queue",
+  "job",
+  "external-system",
+  "module",
+  "unknown"
+]);
+var TECHNICAL_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set([
+  "contains",
+  "depends-on",
+  "calls",
+  "reads-from",
+  "writes-to",
+  "publishes-to",
+  "subscribes-to",
+  "integrates-with",
+  "runs-on",
+  "implemented-by"
+]);
+var PROVENANCE = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewed"]);
+function isRelative(p) {
+  return typeof p === "string" && p.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p) && !p.includes("..");
+}
+function strList(v) {
+  return Array.isArray(v) ? v.map((x2) => typeof x2 === "string" ? x2.trim() : "").filter(Boolean) : [];
+}
+function loadSystemTopology(dir) {
+  const filePath = join(dir, TOPOLOGY_FILE);
+  if (!exists(filePath)) return { entities: [], relationships: [], findings: [], declared: false };
+  const parsed = parseTopologyContent(readFile(filePath), dir);
+  return { ...parsed, declared: true };
+}
+function parseTopologyContent(raw, dir) {
+  let parsed;
+  try {
+    parsed = parseYaml11(raw) ?? {};
+  } catch {
+    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "The topology could not be parsed." }] };
+  }
+  const sourceRevision = typeof parsed.source_revision === "string" ? parsed.source_revision : void 0;
+  const findings = [];
+  const validModules = /* @__PURE__ */ new Set(["core", ...loadMappedModules(dir).map((m2) => m2.id)]);
+  const rawEntities = Array.isArray(parsed.entities) ? parsed.entities : [];
+  const entities = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const raw2 of rawEntities) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const e = raw2;
+    const id = typeof e.id === "string" ? e.id.trim() : "";
+    if (!id) {
+      findings.push({ level: "warning", message: "A topology entity is missing an id and was skipped." });
+      continue;
+    }
+    if (seenIds.has(id)) {
+      findings.push({ level: "blocking", message: `Duplicate topology entity id "${id}".` });
+      continue;
+    }
+    const kind = typeof e.kind === "string" ? e.kind.trim() : "unknown";
+    if (!SYSTEM_ENTITY_KINDS.has(kind)) {
+      findings.push({ level: "warning", message: `Entity "${id}" has an unknown kind "${kind}"; treated as unknown.` });
+    }
+    const moduleRaw = typeof e.module === "string" ? e.module.trim() : void 0;
+    if (moduleRaw && !validModules.has(moduleRaw)) findings.push({ level: "warning", message: `Entity "${id}" references unregistered module "${moduleRaw}".` });
+    const rawImpl = e.implementation ?? e.implementation_refs;
+    const implementation = strList(rawImpl).filter((p) => {
+      if (isRelative(p)) return true;
+      findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p}" is not a safe relative path and was dropped.` });
+      return false;
+    });
+    const prov = e.provenance;
+    const provOrigin = typeof prov === "string" ? prov : prov && typeof prov === "object" && typeof prov.origin === "string" ? String(prov.origin) : void 0;
+    const provenance = provOrigin && PROVENANCE.has(provOrigin) ? provOrigin : void 0;
+    const evidence = strList(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative);
+    seenIds.add(id);
+    entities.push({
+      id,
+      kind: SYSTEM_ENTITY_KINDS.has(kind) ? kind : "unknown",
+      label: typeof e.label === "string" && e.label.trim() ? e.label.trim() : id,
+      ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
+      ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
+      implementationRefs: implementation,
+      knowledgeRefs: strList(e.knowledge ?? e.knowledge_refs),
+      ...provenance ? { provenance } : {},
+      evidence
+    });
+  }
+  const entityIds = new Set(entities.map((e) => e.id));
+  const rawRels = Array.isArray(parsed.relationships) ? parsed.relationships : [];
+  const relationships = [];
+  const seenRels = /* @__PURE__ */ new Set();
+  for (const raw2 of rawRels) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const r2 = raw2;
+    const from = typeof r2.from === "string" ? r2.from.trim() : typeof r2.source === "string" ? r2.source.trim() : "";
+    const to = typeof r2.to === "string" ? r2.to.trim() : typeof r2.target === "string" ? r2.target.trim() : "";
+    const type = typeof r2.type === "string" ? r2.type.trim() : "";
+    if (!from || !to || !type) {
+      findings.push({ level: "warning", message: "A topology relationship is missing from/to/type and was skipped." });
+      continue;
+    }
+    if (!TECHNICAL_RELATIONSHIP_TYPES.has(type)) {
+      findings.push({ level: "warning", message: `Relationship type "${type}" is not recognized and was skipped.` });
+      continue;
+    }
+    if (!entityIds.has(from) || !entityIds.has(to)) {
+      findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
+      continue;
+    }
+    const key = `${from}~${type}~${to}`;
+    if (seenRels.has(key)) {
+      findings.push({ level: "warning", message: `Duplicate relationship ${from} ${type} ${to} was skipped.` });
+      continue;
+    }
+    seenRels.add(key);
+    const prov = r2.provenance;
+    relationships.push({ from, to, type, evidence: strList(r2.evidence ?? prov?.evidence_refs).filter(isRelative) });
+  }
+  return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
+}
+
+// ../cli/src/core/system-map.ts
+function dimensionOf(type) {
+  switch (type) {
+    case "module":
+    case "application":
+    case "service":
+    case "component":
+    case "api":
+    case "interface":
+    case "database":
+    case "queue":
+    case "job":
+    case "external-system":
+      return "system";
+    case "business":
+    case "product":
+    case "tech":
+    case "delivery":
+    case "capability":
+    case "decision":
+    case "project":
+    case "knowledge-capsule":
+      return "knowledge";
+    case "work-item":
+    case "initiative":
+    case "roadmap-candidate":
+    case "release":
+      return "delivery";
+    case "code-glob":
+    case "file":
+    case "directory":
+    case "migration":
+    case "configuration-artifact":
+      return "implementation";
+    default:
+      return "unknown";
+  }
+}
+var EDGE_LABELS = {
+  informs: "informs",
+  belongs_to: "belongs to",
+  materialized_as: "materialized as",
+  owns: "owns",
+  implements: "implements",
+  depends_on: "depends on",
+  governs: "governs",
+  provides_external_context: "provides external context",
+  uses_external_knowledge: "uses external knowledge"
+};
+function emptyDimensions() {
+  return { system: 0, knowledge: 0, delivery: 0, implementation: 0, unknown: 0 };
+}
+function emptyProjection(name, structure) {
+  return {
+    system: { name },
+    nodes: [],
+    relationships: [],
+    groups: [],
+    metadata: {
+      projectName: name,
+      structure,
+      nodeCount: 0,
+      relationshipCount: 0,
+      coverage: "empty",
+      available: false,
+      dimensions: emptyDimensions(),
+      topologyAvailable: false,
+      topologyStatus: "unavailable",
+      semanticEntityCount: 0,
+      technicalRelationshipCount: 0,
+      topologyFindings: []
+    }
+  };
+}
+function getSystemMapProjection(dir) {
+  const config = loadConfig(dir);
+  if (!config) return emptyProjection("unknown", "unknown");
+  const graph = buildGraph(dir, config, { scope: "all" });
+  const hints = buildGraphHints(dir, graph);
+  const knowledgeByPath = /* @__PURE__ */ new Map();
+  for (const a2 of discoverKnowledge(dir).filter((a3) => !a3.isWorkItem)) {
+    const id = a2.id || a2.relPath.replace(/[/\\]/g, "-").replace(/\.md$/, "");
+    const layer2 = a2.layer === "module" ? "tech" : a2.layer;
+    knowledgeByPath.set(a2.relPath, { id, layer: layer2 });
+  }
+  const wiModules = /* @__PURE__ */ new Map();
+  for (const wi of discoverWorkItems(dir)) wiModules.set(wi.id || wi.title, wi.affectedModules);
+  const mapped = loadMappedModules(dir);
+  const groupIds = /* @__PURE__ */ new Set(["core", ...mapped.map((m2) => m2.id)]);
+  const nodes = graph.nodes.map((n) => toNode(n, knowledgeByPath, wiModules, groupIds));
+  const relationships = graph.edges.map((e) => ({
+    id: `${e.from}~${e.type}~${e.to}`,
+    source: e.from,
+    target: e.to,
+    type: e.type,
+    label: EDGE_LABELS[e.type] ?? e.type.replace(/_/g, " ")
+  }));
+  const knowledgeById = /* @__PURE__ */ new Map();
+  for (const ref of knowledgeByPath.values()) knowledgeById.set(ref.id, ref);
+  const topology = loadSystemTopology(dir);
+  const existingIds = new Set(nodes.map((n) => n.id));
+  for (const e of topology.entities) {
+    const nodeId = `sys:${e.id}`;
+    const node = {
+      id: nodeId,
+      type: e.kind,
+      label: e.label,
+      dimension: "system",
+      implementationRefs: e.implementationRefs,
+      knowledgeRefs: e.knowledgeRefs.map((k2) => knowledgeById.get(k2)).filter(Boolean),
+      evidence: e.evidence
+    };
+    if (e.purpose) node.purpose = e.purpose;
+    if (e.moduleId) node.moduleId = e.moduleId;
+    if (e.provenance) node.provenance = e.provenance;
+    nodes.push(node);
+    existingIds.add(nodeId);
+    for (const ref of e.implementationRefs) {
+      const fileId = `file:${ref}`;
+      if (!existingIds.has(fileId)) {
+        nodes.push({ id: fileId, type: "file", label: ref.split("/").pop() || ref, dimension: "implementation", path: ref });
+        existingIds.add(fileId);
+      }
+      relationships.push({ id: `${nodeId}~implemented-by~${fileId}`, source: nodeId, target: fileId, type: "implemented-by", label: "implemented by" });
+    }
+  }
+  for (const r2 of topology.relationships) {
+    relationships.push({ id: `sys:${r2.from}~${r2.type}~sys:${r2.to}`, source: `sys:${r2.from}`, target: `sys:${r2.to}`, type: r2.type, label: r2.type.replace(/-/g, " ") });
+  }
+  const usedGroups = new Set(nodes.map((n) => n.moduleId).filter(Boolean));
+  const allGroups = [
+    { id: "core", label: "core", repositoryId: "core", available: true },
+    // A mapped module is available when its repository path resolves relative to the project.
+    ...mapped.map((m2) => ({ id: m2.id, label: m2.id, repositoryId: m2.id, available: m2.repoPath ? exists(join(dir, m2.repoPath)) : false }))
+  ];
+  const groups = allGroups.filter((g) => usedGroups.has(g.id) || g.available === false);
+  const dimensions = emptyDimensions();
+  for (const n of nodes) dimensions[n.dimension]++;
+  const semanticEntityCount = topology.entities.length;
+  const technicalRelationshipCount = relationships.filter((r2) => TECHNICAL_RELATIONSHIP_TYPES.has(r2.type)).length;
+  const topologyStatus = semanticEntityCount === 0 ? "unavailable" : topology.relationships.length > 0 ? "available" : "partial";
+  return {
+    system: { name: config.project.name },
+    nodes,
+    relationships,
+    groups,
+    metadata: {
+      projectName: config.project.name,
+      structure: config.project.structure,
+      nodeCount: nodes.length,
+      relationshipCount: relationships.length,
+      coverage: hints.quality,
+      available: nodes.length > 0,
+      dimensions,
+      topologyAvailable: dimensions.system > 0,
+      topologyStatus,
+      semanticEntityCount,
+      technicalRelationshipCount,
+      topologyFindings: topology.findings
+    }
+  };
+}
+function getSystemNodeContext(dir, nodeId) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  const node = byId.get(nodeId);
+  if (!node) return null;
+  const incoming = [];
+  const outgoing = [];
+  for (const r2 of projection.relationships) {
+    if (r2.target === nodeId) {
+      const s = byId.get(r2.source);
+      if (s) incoming.push({ relationship: r2, node: s });
+    }
+    if (r2.source === nodeId) {
+      const t = byId.get(r2.target);
+      if (t) outgoing.push({ relationship: r2, node: t });
+    }
+  }
+  return { node, incoming, outgoing };
+}
+var DEFAULT_MAX_DEPTH = 2;
+var DEFAULT_MAX_NODES = 50;
+function searchSystemNodes(dir, query) {
+  const q3 = query.trim().toLowerCase();
+  if (!q3) return [];
+  const rank = (n) => n.dimension === "system" ? 0 : n.dimension === "knowledge" ? 1 : n.dimension === "delivery" ? 2 : n.dimension === "unknown" ? 3 : 4;
+  return getSystemMapProjection(dir).nodes.filter(
+    (n) => n.label.toLowerCase().includes(q3) || n.type.toLowerCase().includes(q3) || (n.moduleId ?? "").toLowerCase().includes(q3) || (n.purpose ?? "").toLowerCase().includes(q3)
+  ).sort((a2, b2) => rank(a2) - rank(b2));
+}
+function getSystemNeighbors(dir, nodeId, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  if (!byId.has(nodeId)) return null;
+  const maxDepth = Math.max(1, opts.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const maxNodes = Math.max(1, opts.maxNodes ?? DEFAULT_MAX_NODES);
+  const relTypes = opts.relationshipTypes && opts.relationshipTypes.length ? new Set(opts.relationshipTypes) : null;
+  const modules = opts.moduleFilter && opts.moduleFilter.length ? new Set(opts.moduleFilter) : null;
+  const includeNode = (n) => !modules || n.moduleId != null && modules.has(n.moduleId) || n.id === nodeId;
+  const visited = /* @__PURE__ */ new Set([nodeId]);
+  const nodes = [];
+  const rels = [];
+  let frontier = [nodeId];
+  let truncated = false;
+  for (let depth = 0; depth < maxDepth && frontier.length > 0 && !truncated; depth++) {
+    const next = [];
+    for (const current of frontier) {
+      for (const r2 of projection.relationships) {
+        if (relTypes && !relTypes.has(r2.type)) continue;
+        const other = r2.source === current ? r2.target : r2.target === current ? r2.source : null;
+        if (!other) continue;
+        const otherNode = byId.get(other);
+        if (!otherNode || !includeNode(otherNode)) continue;
+        if (!rels.some((x2) => x2.id === r2.id)) rels.push(r2);
+        if (!visited.has(other)) {
+          if (nodes.length >= maxNodes) {
+            truncated = true;
+            break;
+          }
+          visited.add(other);
+          nodes.push(otherNode);
+          next.push(other);
+        }
+      }
+      if (truncated) break;
+    }
+    frontier = next;
+  }
+  return { seed: nodeId, nodes, relationships: rels, truncated };
+}
+function findSystemPaths(dir, source, target, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  if (!byId.has(source) || !byId.has(target)) return [];
+  const maxDepth = Math.max(1, opts.maxDepth ?? 4);
+  const out = /* @__PURE__ */ new Map();
+  for (const r2 of projection.relationships) {
+    if (!out.has(r2.source)) out.set(r2.source, []);
+    out.get(r2.source).push(r2.target);
+  }
+  const paths = [];
+  const walk = (node, path5) => {
+    if (paths.length >= 20) return;
+    if (node === target && path5.length > 1) {
+      paths.push([...path5]);
+      return;
+    }
+    if (path5.length > maxDepth) return;
+    for (const nxt of out.get(node) ?? []) {
+      if (path5.includes(nxt)) continue;
+      walk(nxt, [...path5, nxt]);
+    }
+  };
+  walk(source, [source]);
+  return paths;
+}
+function getImpactCandidates(dir, seedIds, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  const seeds = seedIds.filter((s) => byId.has(s));
+  const candidates = /* @__PURE__ */ new Map();
+  let truncated = false;
+  for (const seed of seeds) {
+    const neighborhood = getSystemNeighbors(dir, seed, opts);
+    if (!neighborhood) continue;
+    if (neighborhood.truncated) truncated = true;
+    for (const n of neighborhood.nodes) {
+      if (seeds.includes(n.id)) continue;
+      const rel = neighborhood.relationships.find((r2) => r2.source === seed && r2.target === n.id || r2.target === seed && r2.source === n.id);
+      const reason = rel ? { relationship: rel.label, from: byId.get(rel.source)?.label ?? rel.source, to: byId.get(rel.target)?.label ?? rel.target } : { relationship: "related to", from: byId.get(seed)?.label ?? seed, to: n.label };
+      const existing = candidates.get(n.id);
+      if (existing) {
+        existing.reason.push(reason);
+        continue;
+      }
+      const path5 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
+      candidates.set(n.id, {
+        nodeId: n.id,
+        label: n.label,
+        kind: n.type,
+        ...n.moduleId ? { moduleId: n.moduleId } : {},
+        reason: [reason],
+        ...path5 ? { graphPath: path5.map((id) => byId.get(id)?.label ?? id) } : {},
+        ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
+        ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
+        status: "candidate",
+        provenance: { source: "graph-assisted" }
+      });
+    }
+  }
+  return { seeds, candidates: [...candidates.values()], truncated, topologyStatus: projection.metadata.topologyStatus };
+}
+function toNode(n, knowledgeByPath, wiModules, groupIds) {
+  const node = { id: n.id, type: n.type, label: n.label, dimension: dimensionOf(n.type) };
+  if (n.status) node.status = n.status;
+  if (n.path && !/^([a-zA-Z]:[\\/]|\/)/.test(n.path)) node.path = n.path;
+  if (n.type === "work-item") {
+    const wiId = n.id.startsWith("wi:") ? n.id.slice(3) : n.id;
+    node.workItemRef = wiId;
+    const affected = (wiModules.get(wiId) ?? []).filter((m2) => groupIds.has(m2));
+    if (affected.length === 1) node.moduleId = affected[0];
+  }
+  if (n.path) {
+    const ref = knowledgeByPath.get(n.path);
+    if (ref) node.knowledgeRef = ref;
+  }
+  return node;
+}
+
+// src/system.ts
+var ok3 = (data) => ({ ok: true, data });
+var CANDIDATE_NOTE = "Graph-derived entities are IMPACT CANDIDATES, not confirmed scope. Inspect each in the repository and classify it (affected / reviewed-not-affected / unknown). A missing Graph edge does not mean no impact.";
+function systemSearchTool(root, args) {
+  const results = searchSystemNodes(root, args.query ?? "");
+  return ok3({
+    query: args.query ?? "",
+    count: results.length,
+    results: results.map((n) => ({ nodeId: n.id, label: n.label, kind: n.type, moduleId: n.moduleId ?? null, dimension: n.dimension })),
+    note: CANDIDATE_NOTE
+  });
+}
+function systemNodeTool(root, args) {
+  const ctx = getSystemNodeContext(root, args.nodeId);
+  if (!ctx) return ok3({ nodeId: args.nodeId, found: false, note: "No such system entity in the current topology." });
+  return ok3({
+    nodeId: args.nodeId,
+    found: true,
+    node: { nodeId: ctx.node.id, label: ctx.node.label, kind: ctx.node.type, moduleId: ctx.node.moduleId ?? null, dimension: ctx.node.dimension },
+    incoming: ctx.incoming.map((e) => ({ nodeId: e.node.id, label: e.node.label, kind: e.node.type, relationship: e.relationship.type })),
+    outgoing: ctx.outgoing.map((e) => ({ nodeId: e.node.id, label: e.node.label, kind: e.node.type, relationship: e.relationship.type })),
+    note: CANDIDATE_NOTE
+  });
+}
+function systemNeighborsTool(root, args) {
+  const res = getSystemNeighbors(root, args.nodeId, {
+    maxDepth: args.maxDepth,
+    maxNodes: args.maxNodes,
+    relationshipTypes: args.relationshipTypes,
+    moduleFilter: args.moduleId ? [args.moduleId] : void 0
+  });
+  if (!res) return ok3({ nodeId: args.nodeId, found: false, note: "No such system entity in the current topology." });
+  return ok3({
+    seed: res.seed,
+    truncated: res.truncated,
+    nodes: res.nodes.map((n) => ({ nodeId: n.id, label: n.label, kind: n.type, moduleId: n.moduleId ?? null })),
+    relationships: res.relationships.map((r2) => ({ from: r2.source, to: r2.target, type: r2.type })),
+    note: res.truncated ? `Neighborhood truncated by bounds \u2014 more entities may be reachable. ${CANDIDATE_NOTE}` : CANDIDATE_NOTE
+  });
+}
+function systemPathsTool(root, args) {
+  const paths = findSystemPaths(root, args.from, args.to, { maxDepth: args.maxDepth });
+  return ok3({ from: args.from, to: args.to, count: paths.length, paths, note: CANDIDATE_NOTE });
+}
+function systemImpactCandidatesTool(root, args) {
+  const res = getImpactCandidates(root, args.seeds ?? [], {
+    maxDepth: args.maxDepth,
+    maxNodes: args.maxNodes,
+    relationshipTypes: args.relationshipTypes,
+    moduleFilter: args.moduleId ? [args.moduleId] : void 0
+  });
+  return ok3({
+    seeds: res.seeds,
+    topologyStatus: res.topologyStatus,
+    truncated: res.truncated,
+    count: res.candidates.length,
+    candidates: res.candidates.map((c) => ({
+      nodeId: c.nodeId,
+      label: c.label,
+      kind: c.kind,
+      moduleId: c.moduleId ?? null,
+      status: c.status,
+      // always 'candidate'
+      reason: c.reason,
+      graphPath: c.graphPath ?? null,
+      provenance: c.provenance
+    })),
+    note: res.topologyStatus === "unavailable" ? "No semantic topology available \u2014 refine impact using the repository and Knowledge only." : `${CANDIDATE_NOTE}${res.truncated ? " Traversal was bounded; some candidates may be missing." : ""}`
+  });
+}
+
 // ../cli/src/core/context-pack.ts
 import matter12 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
@@ -12472,6 +12986,64 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => modulesDiscoverTool(root, args)))
   );
+  const CANDIDATE_DESC = "Read-only. Results are IMPACT CANDIDATES to inspect in the repository, never confirmed scope; a missing edge does not mean no impact.";
+  server.registerTool(
+    "kaddo_system_search",
+    {
+      title: "Search system entities",
+      description: `Search the semantic system topology by label / kind / module / purpose (concepts before implementation). ${CANDIDATE_DESC}`,
+      inputSchema: { query: z3.string() }
+    },
+    async (args) => toolText(guarded(root, () => systemSearchTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_system_node",
+    {
+      title: "Get system entity context",
+      description: `Resolve one system entity plus its incoming and outgoing relationships. ${CANDIDATE_DESC}`,
+      inputSchema: { nodeId: z3.string() }
+    },
+    async (args) => toolText(guarded(root, () => systemNodeTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_system_neighbors",
+    {
+      title: "Get bounded system neighborhood",
+      description: `Bounded BFS neighborhood around a seed entity (maxDepth/maxNodes, optional relationshipTypes/moduleId). Reports truncation. ${CANDIDATE_DESC}`,
+      inputSchema: {
+        nodeId: z3.string(),
+        maxDepth: z3.number().int().positive().optional(),
+        maxNodes: z3.number().int().positive().optional(),
+        relationshipTypes: z3.array(z3.string()).optional(),
+        moduleId: z3.string().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => systemNeighborsTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_system_paths",
+    {
+      title: "Find system paths",
+      description: `Directed, acyclic, bounded paths between two system entities. ${CANDIDATE_DESC}`,
+      inputSchema: { from: z3.string(), to: z3.string(), maxDepth: z3.number().int().positive().optional() }
+    },
+    async (args) => toolText(guarded(root, () => systemPathsTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_system_impact_candidates",
+    {
+      title: "Get graph-assisted impact candidates",
+      description: `Graph-assisted IMPACT CANDIDATES reachable from one or more seed entities, with reasons and graph paths. Widens what to investigate before deciding scope; it never decides scope, mutates the Work Item, runs an LLM or touches git. ${CANDIDATE_DESC}`,
+      inputSchema: {
+        seeds: z3.array(z3.string()),
+        maxDepth: z3.number().int().positive().optional(),
+        maxNodes: z3.number().int().positive().optional(),
+        relationshipTypes: z3.array(z3.string()).optional(),
+        moduleId: z3.string().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => systemImpactCandidatesTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

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