@esankhan3/code-search-mcp 0.2.0 → 0.4.0

package/README.md

@@ -118,15 +118,21 @@ retrieval pipeline that powers the Anvil dashboard.
 | `search_code` | Hybrid retrieval — vector + BM25 + graph + rerank |
 | `search_semantic` | Vector-only (paraphrases, intent) |
 | `search_exact` | BM25-only (identifiers, error codes) |
+| `get_code_snippet` | Fetch the source for one entity by qualified name (cheaper than reading the file) |
 
 ### Graph
 | Tool | What it does |
 |---|---|
 | `get_repo_graph` | Single-repo AST graph |
 | `get_cross_repo_edges` | Inter-repo edges (Kafka, HTTP, gRPC, shared types, …) |
-| `find_callers` | Who calls this function |
+| `find_callers` | Who calls this function (exact by default; `fuzzy:true` for substring) |
 | `find_dependencies` | What this function calls |
 | `impact_analysis` | What breaks if this changes |
+| `trace_path` | Multi-hop call chain — shortest path between two functions, or the reachable call tree |
+| `search_graph` | Structural query — filter entities by name/type/file, ranked by connectivity |
+| `find_dead_code` | Entities with no callers (heuristic) |
+| `detect_changes` | Map a git diff to affected entities + their dependents |
+| `get_architecture` | Project overview — repo roles, key flows, connections |
 
 ### Profiles
 | Tool | What it does |

package/dist/__tests__/graph-tools.test.js

@@ -0,0 +1,208 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+import { handleGraphTool } from "../tools/graph.js";
+import { handleSearchTool } from "../tools/search.js";
+const PROJECT = "demo";
+let tmp = "";
+let stashDataDir;
+function ctx() {
+  return {
+    projectName: PROJECT,
+    directoryPath: null,
+    indexReady: true,
+    startedAt: 0,
+    indexing: {
+      status: "idle",
+      phase: null,
+      message: null,
+      percent: 0,
+      startedAt: null,
+      error: null,
+      lastSuccess: null,
+      lastDurationMs: 0,
+      history: []
+    }
+  };
+}
+const text = (r) => r?.content?.[0]?.text ?? "";
+const SYSTEM_GRAPH = {
+  nodes: [
+    { key: "app::a.ts::handleRequest", attributes: { label: "handleRequest", type: "function", repo: "app", file: "a.ts" } },
+    { key: "app::a.ts::validateToken", attributes: { label: "validateToken", type: "function", repo: "app", file: "a.ts" } },
+    { key: "app::b.ts::dbQuery", attributes: { label: "dbQuery", type: "function", repo: "app", file: "b.ts" } },
+    { key: "app::a.ts::get", attributes: { label: "get", type: "function", repo: "app", file: "a.ts" } },
+    { key: "app::a.ts::getUser", attributes: { label: "getUser", type: "function", repo: "app", file: "a.ts" } },
+    { key: "app::a.ts::caller1", attributes: { label: "caller1", type: "function", repo: "app", file: "a.ts" } },
+    { key: "app::a.ts::caller2", attributes: { label: "caller2", type: "function", repo: "app", file: "a.ts" } }
+  ],
+  edges: [
+    { source: "app::a.ts::handleRequest", target: "app::a.ts::validateToken", attributes: { type: "calls", confidence: 0.9 } },
+    { source: "app::a.ts::validateToken", target: "app::b.ts::dbQuery", attributes: { type: "calls", confidence: 0.9 } },
+    { source: "app::a.ts::caller1", target: "app::a.ts::get", attributes: { type: "calls", confidence: 0.9 } },
+    { source: "app::a.ts::caller2", target: "app::a.ts::getUser", attributes: { type: "calls", confidence: 0.9 } }
+  ]
+};
+const REPO_GRAPH = {
+  nodes: [
+    { id: "app::a.ts::usedFn", label: "usedFn", type: "function", file: "a.ts" },
+    { id: "app::a.ts::deadFn", label: "deadFn", type: "function", file: "a.ts" }
+  ],
+  links: [
+    { source: "app::a.ts::caller", target: "app::a.ts::usedFn", type: "calls", confidence: 0.9 },
+    { source: "app::a.ts::Container", target: "app::a.ts::deadFn", type: "contains", confidence: 1 }
+  ]
+};
+const CHUNKS = [
+  { id: "c1", repoName: "app", filePath: "a.ts", entityName: "handleRequest", startLine: 1, endLine: 3, content: "function handleRequest() { return 1; }", language: "typescript" }
+];
+const PROJECT_GRAPH = {
+  architectureSummary: "Two services talk over HTTP.",
+  repoRoles: { app: { role: "service", criticality: "high", responsibilities: ["serves the API"] } },
+  relationships: [{ from: "app", to: "db", type: "sync-http", description: "queries the database" }],
+  keyFlows: [{ name: "login", trigger: "POST /login", steps: [{ repo: "app", component: "handler", action: "validate", protocol: "http" }] }]
+};
+beforeEach(() => {
+  stashDataDir = process.env.CODE_SEARCH_DATA_DIR;
+  tmp = mkdtempSync(join(tmpdir(), "cs-graph-"));
+  process.env.CODE_SEARCH_DATA_DIR = tmp;
+  const kb = join(tmp, PROJECT);
+  mkdirSync(join(kb, "app"), { recursive: true });
+  writeFileSync(join(kb, "system_graph_v2.json"), JSON.stringify(SYSTEM_GRAPH));
+  writeFileSync(join(kb, "app", "graph.json"), JSON.stringify(REPO_GRAPH));
+  writeFileSync(join(kb, "chunks.json"), JSON.stringify(CHUNKS));
+  writeFileSync(join(kb, "PROJECT_GRAPH.json"), JSON.stringify(PROJECT_GRAPH));
+});
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  if (stashDataDir === void 0) delete process.env.CODE_SEARCH_DATA_DIR;
+  else process.env.CODE_SEARCH_DATA_DIR = stashDataDir;
+});
+describe("trace_path", () => {
+  it("finds a 2-hop call chain", async () => {
+    const r = await handleGraphTool("trace_path", { from: "handleRequest", to: "dbQuery" }, ctx());
+    const t = text(r);
+    assert.match(t, /2 hops/);
+    assert.match(t, /handleRequest.*validateToken.*dbQuery/s);
+  });
+  it("respects maxDepth", async () => {
+    const r = await handleGraphTool("trace_path", { from: "handleRequest", to: "dbQuery", maxDepth: 1 }, ctx());
+    assert.match(text(r), /No path/);
+  });
+  it("lists reachable callees without a target", async () => {
+    const r = await handleGraphTool("trace_path", { from: "handleRequest" }, ctx());
+    const t = text(r);
+    assert.match(t, /validateToken/);
+    assert.match(t, /dbQuery/);
+  });
+});
+describe("find_callers precision", () => {
+  it('exact match does not treat "get" as a substring of "getUser"', async () => {
+    const r = await handleGraphTool("find_callers", { function: "get" }, ctx());
+    const t = text(r);
+    assert.match(t, /caller1/);
+    assert.doesNotMatch(t, /caller2/);
+    assert.doesNotMatch(t, /getUser/);
+  });
+  it("fuzzy:true re-enables substring matching", async () => {
+    const r = await handleGraphTool("find_callers", { function: "get", fuzzy: true }, ctx());
+    const t = text(r);
+    assert.match(t, /caller1/);
+    assert.match(t, /caller2/);
+  });
+});
+describe("find_dead_code", () => {
+  it("flags zero-caller entities and ignores contains-only edges", async () => {
+    const r = await handleGraphTool("find_dead_code", { repo: "app" }, ctx());
+    const t = text(r);
+    assert.match(t, /deadFn/);
+    assert.doesNotMatch(t, /\busedFn\b/);
+  });
+});
+describe("get_architecture", () => {
+  it("renders the project graph when present", async () => {
+    const r = await handleGraphTool("get_architecture", {}, ctx());
+    const t = text(r);
+    assert.match(t, /Two services talk over HTTP/);
+    assert.match(t, /login/);
+  });
+  it("degrades cleanly when no architecture data exists", async () => {
+    const c = ctx();
+    c.projectName = "empty-project";
+    const r = await handleGraphTool("get_architecture", {}, c);
+    assert.match(text(r), /No architecture data/);
+  });
+});
+describe("get_code_snippet", () => {
+  it("returns source for a qualified id", async () => {
+    const r = await handleSearchTool("get_code_snippet", { id: "app::a.ts::handleRequest" }, ctx());
+    assert.match(text(r), /function handleRequest/);
+  });
+  it("reports when nothing matches", async () => {
+    const r = await handleSearchTool("get_code_snippet", { id: "app::a.ts::nope" }, ctx());
+    assert.match(text(r), /No snippet found/);
+  });
+  it("reads the NDJSON chunks format (org-scale)", async () => {
+    const ndjson = CHUNKS.map((c) => JSON.stringify(c)).join("\n") + "\n";
+    writeFileSync(join(tmp, PROJECT, "chunks.json"), ndjson);
+    const r = await handleSearchTool("get_code_snippet", { id: "app::a.ts::handleRequest" }, ctx());
+    assert.match(text(r), /function handleRequest/);
+  });
+});
+describe("search_graph", () => {
+  it("filters by type and minDegree, ranked by connectivity", async () => {
+    const r = await handleGraphTool("search_graph", { type: "function", minDegree: 2 }, ctx());
+    const t = text(r);
+    assert.match(t, /validateToken/);
+    assert.doesNotMatch(t, /handleRequest/);
+  });
+  it("matches names by regex/substring", async () => {
+    const r = await handleGraphTool("search_graph", { name: "caller" }, ctx());
+    const t = text(r);
+    assert.match(t, /caller1/);
+    assert.match(t, /caller2/);
+  });
+  it("reports when no entity matches", async () => {
+    const r = await handleGraphTool("search_graph", { type: "class" }, ctx());
+    assert.match(text(r), /No entities match/);
+  });
+});
+describe("detect_changes", () => {
+  it("requires a local repo path", async () => {
+    const r = await handleGraphTool("detect_changes", { repo: "app" }, ctx());
+    assert.match(text(r), /needs a local repo path/);
+  });
+  it("maps a git working-tree change to affected entities + dependents", async () => {
+    const ws = mkdtempSync(join(tmpdir(), "cs-ws-"));
+    const repoDir = join(ws, "app");
+    mkdirSync(repoDir, { recursive: true });
+    let baseSha = "";
+    try {
+      const git = (cmd) => execSync(`git ${cmd}`, { cwd: repoDir, stdio: ["pipe", "pipe", "pipe"] });
+      git("init -q");
+      git("config user.email t@t.dev");
+      git("config user.name test");
+      git("config commit.gpgsign false");
+      writeFileSync(join(repoDir, "a.ts"), "export function handleRequest() {}\n");
+      writeFileSync(join(repoDir, "b.ts"), "export function dbQuery() {}\n");
+      git("add -A");
+      git("commit -q -m init");
+      baseSha = execSync("git rev-parse HEAD", { cwd: repoDir }).toString().trim();
+      appendFileSync(join(repoDir, "b.ts"), "// touched\n");
+    } catch {
+      rmSync(ws, { recursive: true, force: true });
+      return;
+    }
+    const c = ctx();
+    c.directoryPath = ws;
+    const r = await handleGraphTool("detect_changes", { repo: "app", baseSha }, c);
+    const t = text(r);
+    rmSync(ws, { recursive: true, force: true });
+    assert.match(t, /b\.ts/);
+    assert.match(t, /dbQuery/);
+    assert.match(t, /validateToken.*dbQuery/s);
+  });
+});

package/dist/server.js

@@ -20,7 +20,7 @@ import { toKnowledgeConfig } from "./core/config.js";
 import { startHttpTransport } from "./transports/http-transport.js";
 function createMcpServerInstance(ctx) {
   const server = new Server(
-    { name: "code-search-mcp", version: "0.1.0" },
+    { name: "code-search-mcp", version: "0.4.0" },
     { capabilities: { tools: {}, resources: {} } }
   );
   const allTools = [

package/dist/tools/graph.js

@@ -1,6 +1,98 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getKnowledgeBasePath } from "@esankhan3/anvil-knowledge-core";
+import {
+  getKnowledgeBasePath,
+  loadAllProfiles,
+  loadProfile,
+  getAllChanges,
+  getChangedFilesList
+} from "@esankhan3/anvil-knowledge-core";
+const GRAPH_TOOL_NAMES = [
+  "get_repo_graph",
+  "get_cross_repo_edges",
+  "find_callers",
+  "find_dependencies",
+  "impact_analysis",
+  "trace_path",
+  "find_dead_code",
+  "get_architecture",
+  "search_graph",
+  "detect_changes"
+];
+function loadSystemGraph(kbPath) {
+  const p = join(kbPath, "system_graph_v2.json");
+  if (!existsSync(p)) return null;
+  try {
+    const g = JSON.parse(readFileSync(p, "utf-8"));
+    return { nodes: g.nodes ?? [], edges: g.edges ?? [] };
+  } catch {
+    return null;
+  }
+}
+function nodeLabel(node) {
+  return node.attributes?.label ?? node.key.split("::").slice(2).join("::") ?? node.key;
+}
+const edgeType = (e) => e.attributes?.type ?? e.attributes?.relation;
+function resolveEntityNodes(nodes, name, repo, fuzzy = false) {
+  const inRepo = (key) => !repo || key.startsWith(repo + "::");
+  if (fuzzy) {
+    return nodes.filter((n) => inRepo(n.key) && ((n.attributes?.label ?? "").includes(name) || n.key.includes(name))).map((n) => n.key);
+  }
+  return nodes.filter((n) => inRepo(n.key) && (n.attributes?.label === name || n.key.endsWith("::" + name))).map((n) => n.key);
+}
+function buildAdjacency(edges, direction) {
+  const adj = /* @__PURE__ */ new Map();
+  const add = (a, b) => {
+    if (!adj.has(a)) adj.set(a, /* @__PURE__ */ new Set());
+    adj.get(a).add(b);
+  };
+  for (const e of edges) {
+    if (!e.source || !e.target) continue;
+    if (edgeType(e) === "contains") continue;
+    if ((e.attributes?.confidence ?? 0.8) < 0.7) continue;
+    if (direction === "callees" || direction === "both") add(e.source, e.target);
+    if (direction === "callers" || direction === "both") add(e.target, e.source);
+  }
+  return adj;
+}
+function shortestPath(adj, fromKeys, toKeys, maxDepth) {
+  const seed = fromKeys.find((k) => toKeys.has(k));
+  if (seed) return [seed];
+  const visited = new Set(fromKeys);
+  let frontier = fromKeys.map((k) => [k]);
+  for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const path of frontier) {
+      for (const nb of adj.get(path[path.length - 1]) ?? []) {
+        if (visited.has(nb)) continue;
+        if (toKeys.has(nb)) return [...path, nb];
+        visited.add(nb);
+        next.push([...path, nb]);
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}
+function reachable(adj, fromKeys, maxDepth, cap = 50) {
+  const visited = new Set(fromKeys);
+  const out = [];
+  let frontier = [...fromKeys];
+  for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const k of frontier) {
+      for (const nb of adj.get(k) ?? []) {
+        if (visited.has(nb)) continue;
+        visited.add(nb);
+        out.push({ key: nb, depth });
+        next.push(nb);
+        if (out.length >= cap) return out;
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
 function registerGraphTools() {
   return [
     {
@@ -8,9 +100,7 @@ function registerGraphTools() {
       description: "Get the AST knowledge graph for a repo \u2014 entities (functions, classes, types) and their relationships (calls, imports, inheritance).",
       inputSchema: {
         type: "object",
-        properties: {
-          repo: { type: "string", description: "Repository name" }
-        },
+        properties: { repo: { type: "string", description: "Repository name" } },
         required: ["repo"]
       }
     },
@@ -19,31 +109,31 @@ function registerGraphTools() {
       description: "Get connections between repos \u2014 shared deps, Kafka topics, HTTP routes, database tables, gRPC services, etc.",
       inputSchema: {
         type: "object",
-        properties: {
-          repo: { type: "string", description: "Filter to edges involving this repo (optional)" }
-        }
+        properties: { repo: { type: "string", description: "Filter to edges involving this repo (optional)" } }
       }
     },
     {
       name: "find_callers",
-      description: "Find all functions/methods that call a given function. Uses the AST graph.",
+      description: "Find all functions/methods that call a given function (exact name match by default). Uses the AST graph.",
       inputSchema: {
         type: "object",
         properties: {
           function: { type: "string", description: "Function name to find callers of" },
-          repo: { type: "string", description: "Limit search to this repo (optional)" }
+          repo: { type: "string", description: "Limit search to this repo (optional)" },
+          fuzzy: { type: "boolean", description: "Substring-match the name instead of exact (default false)" }
         },
         required: ["function"]
       }
     },
     {
       name: "find_dependencies",
-      description: "Find what a function depends on \u2014 calls, imports, type references.",
+      description: "Find what a function depends on \u2014 calls, imports, type references (exact name match by default).",
       inputSchema: {
         type: "object",
         properties: {
           function: { type: "string", description: "Function name" },
-          repo: { type: "string", description: "Limit to this repo (optional)" }
+          repo: { type: "string", description: "Limit to this repo (optional)" },
+          fuzzy: { type: "boolean", description: "Substring-match the name instead of exact (default false)" }
         },
         required: ["function"]
       }
@@ -60,11 +150,75 @@ function registerGraphTools() {
         },
         required: ["file", "repo"]
       }
+    },
+    {
+      name: "trace_path",
+      description: 'Trace the call chain from a function across multiple hops. With "to", returns the shortest path between two functions; otherwise returns the reachable call tree. Follows confidence-weighted call/import/use edges.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          from: { type: "string", description: "Starting function name or qualified id (repo::file::entity)" },
+          to: { type: "string", description: "Target function name or qualified id (optional \u2014 shortest path)" },
+          repo: { type: "string", description: "Limit resolution to this repo (optional)" },
+          direction: { type: "string", enum: ["callees", "callers", "both"], description: "Traverse callees (what it calls), callers (who calls it), or both. Default callees." },
+          maxDepth: { type: "number", description: "Max hops to traverse (default 4)" },
+          fuzzy: { type: "boolean", description: "Substring-match names instead of exact (default false)" }
+        },
+        required: ["from"]
+      }
+    },
+    {
+      name: "find_dead_code",
+      description: "List entities (functions, methods, classes) with no callers/importers in a repo \u2014 likely dead code. Heuristic: exported APIs, reflection, and dynamic dispatch produce false positives.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repo: { type: "string", description: "Repository name" },
+          limit: { type: "number", description: "Max results (default 50)" }
+        },
+        required: ["repo"]
+      }
+    },
+    {
+      name: "get_architecture",
+      description: "High-level architecture overview of the project \u2014 repo roles, key flows, and how services connect. Built from the LLM-generated project graph and repo profiles.",
+      inputSchema: {
+        type: "object",
+        properties: { repo: { type: "string", description: "Drill into one repo profile (optional)" } }
+      }
+    },
+    {
+      name: "search_graph",
+      description: `Structural search over the knowledge graph: filter entities by name (regex/substring), type, file, and repo; rank by connectivity (degree). Answers "which functions matter most in this module" \u2014 a structural question search/grep can't.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Name regex or substring to match (optional)" },
+          type: { type: "string", description: "Entity type filter: function | class | interface | method | type | \u2026 (optional)" },
+          file: { type: "string", description: "File-path substring filter (optional)" },
+          repo: { type: "string", description: "Limit to this repo (optional)" },
+          minDegree: { type: "number", description: "Only entities with at least this many connections (default 0)" },
+          limit: { type: "number", description: "Max results (default 50)" }
+        }
+      }
+    },
+    {
+      name: "detect_changes",
+      description: "Map a git diff to affected symbols and their dependents. Compares the working tree against a base commit (or the last-indexed SHA) and reports which entities changed and what depends on them \u2014 a blast-radius / code-review tool. Requires a local repo (local/serve mode).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          repo: { type: "string", description: "Repository name" },
+          baseSha: { type: "string", description: "Git base commit to diff against (default: last-indexed SHA)" },
+          limit: { type: "number", description: "Max dependent edges to list (default 50)" }
+        },
+        required: ["repo"]
+      }
     }
   ];
 }
 async function handleGraphTool(name, args, ctx) {
-  if (!["get_repo_graph", "get_cross_repo_edges", "find_callers", "find_dependencies", "impact_analysis"].includes(name)) return null;
+  if (!GRAPH_TOOL_NAMES.includes(name)) return null;
   try {
     const kbPath = getKnowledgeBasePath(ctx.projectName);
     if (name === "get_repo_graph") {
@@ -86,26 +240,21 @@ ${graph.nodes?.length > 50 ? `... and ${graph.nodes.length - 50} more` : ""}`;
       return { content: [{ type: "text", text: summary }] };
     }
     if (name === "get_cross_repo_edges") {
-      const sysGraphPath = join(kbPath, "system_graph_v2.json");
-      if (!existsSync(sysGraphPath)) {
-        return { content: [{ type: "text", text: "No system graph found. Build KB first." }] };
-      }
-      const sysGraph = JSON.parse(readFileSync(sysGraphPath, "utf-8"));
-      const edges = sysGraph.edges ?? [];
+      const sys = loadSystemGraph(kbPath);
+      if (!sys) return { content: [{ type: "text", text: "No system graph found. Build KB first." }] };
       const repo = args.repo;
-      const relevant = repo ? edges.filter((e) => (e.source ?? "").startsWith(repo + "::") || (e.target ?? "").startsWith(repo + "::")) : edges;
+      const relevant = repo ? sys.edges.filter((e) => e.source.startsWith(repo + "::") || e.target.startsWith(repo + "::")) : sys.edges;
       const crossRepo = relevant.filter((e) => {
-        const src = (e.source ?? "").split("::")[0];
-        const tgt = (e.target ?? "").split("::")[0];
+        const src = e.source.split("::")[0];
+        const tgt = e.target.split("::")[0];
         return src && tgt && src !== tgt;
       });
       if (crossRepo.length === 0) {
         return { content: [{ type: "text", text: repo ? `No cross-repo edges found for "${repo}"` : "No cross-repo edges found" }] };
       }
-      const text = crossRepo.slice(0, 50).map((e) => {
-        const attrs = e.attributes ?? {};
-        return `- ${(e.source ?? "").split("::")[0]} \u2192 ${(e.target ?? "").split("::")[0]} (${attrs.relation ?? attrs.type ?? "edge"})`;
-      }).join("\n");
+      const text = crossRepo.slice(0, 50).map(
+        (e) => `- ${e.source.split("::")[0]} \u2192 ${e.target.split("::")[0]} (${edgeType(e) ?? "edge"})`
+      ).join("\n");
       return { content: [{ type: "text", text: `# Cross-Repo Edges${repo ? ` for ${repo}` : ""}
 
 ${crossRepo.length} edges found:
@@ -117,30 +266,21 @@ ${text}${crossRepo.length > 50 ? `
     if (name === "find_callers" || name === "find_dependencies") {
       const funcName = args.function;
       const repoFilter = args.repo;
-      const sysGraphPath = join(kbPath, "system_graph_v2.json");
-      if (!existsSync(sysGraphPath)) {
-        return { content: [{ type: "text", text: "No system graph found." }] };
-      }
-      const sysGraph = JSON.parse(readFileSync(sysGraphPath, "utf-8"));
-      const edges = sysGraph.edges ?? [];
-      const matchingNodes = (sysGraph.nodes ?? []).filter((n) => {
-        const label = n.attributes?.label ?? n.key ?? "";
-        const matchesName = label.includes(funcName) || (n.key ?? "").includes(funcName);
-        const matchesRepo = !repoFilter || (n.key ?? "").startsWith(repoFilter + "::");
-        return matchesName && matchesRepo;
-      });
-      if (matchingNodes.length === 0) {
-        return { content: [{ type: "text", text: `No entity found matching "${funcName}"${repoFilter ? ` in ${repoFilter}` : ""}` }] };
-      }
-      const nodeKeys = new Set(matchingNodes.map((n) => n.key));
-      let results;
-      if (name === "find_callers") {
-        results = edges.filter((e) => nodeKeys.has(e.target)).map((e) => e.source);
-      } else {
-        results = edges.filter((e) => nodeKeys.has(e.source)).map((e) => e.target);
+      const fuzzy = args.fuzzy === true;
+      const sys = loadSystemGraph(kbPath);
+      if (!sys) return { content: [{ type: "text", text: "No system graph found." }] };
+      const matchKeys = new Set(resolveEntityNodes(sys.nodes, funcName, repoFilter, fuzzy));
+      if (matchKeys.size === 0) {
+        return { content: [{ type: "text", text: `No entity found matching "${funcName}"${repoFilter ? ` in ${repoFilter}` : ""}. Try fuzzy:true for substring matching.` }] };
       }
+      const results = name === "find_callers" ? sys.edges.filter((e) => matchKeys.has(e.target) && edgeType(e) !== "contains").map((e) => e.source) : sys.edges.filter((e) => matchKeys.has(e.source) && edgeType(e) !== "contains").map((e) => e.target);
       const unique = [...new Set(results)].slice(0, 30);
       const direction = name === "find_callers" ? "Callers of" : "Dependencies of";
+      if (unique.length === 0) {
+        return { content: [{ type: "text", text: `# ${direction} "${funcName}"
+
+Matched ${matchKeys.size} entit${matchKeys.size === 1 ? "y" : "ies"}, but no ${name === "find_callers" ? "callers" : "dependencies"} found.` }] };
+      }
       return { content: [{ type: "text", text: `# ${direction} "${funcName}"
 
 ${unique.length} found:
@@ -150,22 +290,16 @@ ${unique.map((r) => `- \`${r}\``).join("\n")}` }] };
       const file = args.file;
       const repo = args.repo;
       const entity = args.entity;
-      const sysGraphPath = join(kbPath, "system_graph_v2.json");
-      if (!existsSync(sysGraphPath)) {
-        return { content: [{ type: "text", text: "No system graph found." }] };
-      }
-      const sysGraph = JSON.parse(readFileSync(sysGraphPath, "utf-8"));
-      const edges = sysGraph.edges ?? [];
-      const nodes = sysGraph.nodes ?? [];
-      const fileNodes = nodes.filter((n) => {
-        const key = n.key ?? "";
-        const matchesFile = key.includes(`${repo}::${file}::`);
-        const matchesEntity = !entity || key.includes(entity);
+      const sys = loadSystemGraph(kbPath);
+      if (!sys) return { content: [{ type: "text", text: "No system graph found." }] };
+      const fileNodes = sys.nodes.filter((n) => {
+        const matchesFile = n.key.includes(`${repo}::${file}::`);
+        const matchesEntity = !entity || n.key.endsWith(`::${entity}`);
         return matchesFile && matchesEntity;
       });
       const nodeKeys = new Set(fileNodes.map((n) => n.key));
-      const dependents = edges.filter((e) => nodeKeys.has(e.target) && !nodeKeys.has(e.source));
-      const dependentRepos = new Set(dependents.map((e) => (e.source ?? "").split("::")[0]));
+      const dependents = sys.edges.filter((e) => nodeKeys.has(e.target) && !nodeKeys.has(e.source) && edgeType(e) !== "contains");
+      const dependentRepos = new Set(dependents.map((e) => e.source.split("::")[0]));
       const text = [
         `# Impact Analysis: ${repo}/${file}${entity ? `::${entity}` : ""}`,
         "",
@@ -173,7 +307,7 @@ ${unique.map((r) => `- \`${r}\``).join("\n")}` }] };
         ...fileNodes.slice(0, 20).map((n) => `- \`${n.key}\``),
         "",
         `## Dependents: ${dependents.length} edges from ${dependentRepos.size} repos`,
-        ...dependents.slice(0, 30).map((e) => `- \`${e.source}\` \u2192 \`${e.target}\` (${(e.attributes ?? {}).relation ?? "edge"})`),
+        ...dependents.slice(0, 30).map((e) => `- \`${e.source}\` \u2192 \`${e.target}\` (${edgeType(e) ?? "edge"})`),
         dependents.length > 30 ? `
 ... and ${dependents.length - 30} more` : "",
         "",
@@ -181,6 +315,252 @@ ${unique.map((r) => `- \`${r}\``).join("\n")}` }] };
       ].join("\n");
       return { content: [{ type: "text", text }] };
     }
+    if (name === "trace_path") {
+      const sys = loadSystemGraph(kbPath);
+      if (!sys) return { content: [{ type: "text", text: "No system graph found." }] };
+      const from = args.from;
+      const to = args.to;
+      const repo = args.repo;
+      const fuzzy = args.fuzzy === true;
+      const direction = args.direction ?? "callees";
+      const maxDepth = Math.max(1, Math.min(10, args.maxDepth || 4));
+      const fromKeys = resolveEntityNodes(sys.nodes, from, repo, fuzzy);
+      if (fromKeys.length === 0) {
+        return { content: [{ type: "text", text: `No entity found matching "${from}". Try fuzzy:true.` }] };
+      }
+      const labelOf = new Map(sys.nodes.map((n) => [n.key, nodeLabel(n)]));
+      const adj = buildAdjacency(sys.edges, direction);
+      if (to) {
+        const toKeys = new Set(resolveEntityNodes(sys.nodes, to, repo, fuzzy));
+        if (toKeys.size === 0) {
+          return { content: [{ type: "text", text: `No entity found matching target "${to}". Try fuzzy:true.` }] };
+        }
+        const path = shortestPath(adj, fromKeys, toKeys, maxDepth);
+        if (!path) {
+          return { content: [{ type: "text", text: `No path from "${from}" to "${to}" within ${maxDepth} hops (direction: ${direction}).` }] };
+        }
+        const arrow = direction === "callers" ? " \u2190 " : " \u2192 ";
+        const rendered = path.map((k) => labelOf.get(k) ?? k).join(arrow);
+        return { content: [{ type: "text", text: `# Path (${path.length - 1} hops)
+
+${rendered}
+
+${path.map((k) => `- \`${k}\``).join("\n")}` }] };
+      }
+      const nodes = reachable(adj, fromKeys, maxDepth);
+      if (nodes.length === 0) {
+        return { content: [{ type: "text", text: `No ${direction} reachable from "${from}" within ${maxDepth} hops.` }] };
+      }
+      const byDepth = /* @__PURE__ */ new Map();
+      for (const { key, depth } of nodes) {
+        if (!byDepth.has(depth)) byDepth.set(depth, []);
+        byDepth.get(depth).push(`\`${labelOf.get(key) ?? key}\` (${key})`);
+      }
+      const sections = [...byDepth.entries()].sort((a, b) => a[0] - b[0]).map(([d, ks]) => `## Depth ${d}
+${ks.map((k) => `- ${k}`).join("\n")}`).join("\n\n");
+      return { content: [{ type: "text", text: `# Reachable from "${from}" (${direction}, \u2264${maxDepth} hops)
+
+${nodes.length} nodes:
+
+${sections}` }] };
+    }
+    if (name === "find_dead_code") {
+      const repo = args.repo;
+      const limit = args.limit || 50;
+      const graphPath = join(kbPath, repo, "graph.json");
+      if (!existsSync(graphPath)) {
+        return { content: [{ type: "text", text: `No graph found for repo "${repo}"` }] };
+      }
+      const graph = JSON.parse(readFileSync(graphPath, "utf-8"));
+      const ENTITY_TYPES = /* @__PURE__ */ new Set(["function", "method", "class", "struct", "enum", "trait"]);
+      const inDegree = /* @__PURE__ */ new Map();
+      for (const l of graph.links ?? []) {
+        if (l.type === "contains") continue;
+        inDegree.set(l.target, (inDegree.get(l.target) ?? 0) + 1);
+      }
+      const dead = (graph.nodes ?? []).filter((n) => ENTITY_TYPES.has(n.type) && (inDegree.get(n.id) ?? 0) === 0);
+      if (dead.length === 0) {
+        return { content: [{ type: "text", text: `# Dead code in ${repo}
+
+No zero-caller entities found.` }] };
+      }
+      const rows = dead.slice(0, limit).map((n) => `- \`${n.label ?? n.id}\` (${n.type})${n.file ? ` \u2014 ${n.file}` : ""}`).join("\n");
+      return { content: [{ type: "text", text: `# Dead code in ${repo} (heuristic)
+
+${dead.length} zero-caller entit${dead.length === 1 ? "y" : "ies"}:
+
+${rows}${dead.length > limit ? `
+
+... and ${dead.length - limit} more` : ""}
+
+_Note: exported APIs, reflection, and dynamic dispatch can cause false positives._` }] };
+    }
+    if (name === "get_architecture") {
+      const repo = args.repo;
+      if (repo) {
+        const profile = loadProfile(ctx.projectName, repo);
+        if (!profile) {
+          return { content: [{ type: "text", text: `No profile for "${repo}". Run profiling (requires LLM) to generate one.` }] };
+        }
+        const ep = (xs) => xs?.length ? xs.map((e) => `  - ${e.type}: ${e.identifier} \u2014 ${e.description}`).join("\n") : "  - (none)";
+        const text = [
+          `# ${profile.name} \u2014 ${profile.role} (${profile.domain})`,
+          "",
+          profile.description,
+          "",
+          `**Tech:** ${profile.technologies?.join(", ") || "unknown"}`,
+          `**Entry points:** ${profile.entryPoints?.join(", ") || "unknown"}`,
+          "",
+          "## Exposes",
+          ep(profile.exposes),
+          "",
+          "## Consumes",
+          ep(profile.consumes)
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      }
+      const pgPath = join(kbPath, "PROJECT_GRAPH.json");
+      const pg = existsSync(pgPath) ? JSON.parse(readFileSync(pgPath, "utf-8")) : null;
+      if (pg) {
+        const lines = ["# Project Architecture", "", pg.architectureSummary ?? ""];
+        if (pg.repoRoles && Object.keys(pg.repoRoles).length) {
+          lines.push("", "## Repo Roles");
+          for (const [name2, r] of Object.entries(pg.repoRoles)) {
+            lines.push(`- **${name2}** \u2014 ${r.role} (${r.criticality}): ${(r.responsibilities ?? []).join("; ")}`);
+          }
+        }
+        if (pg.relationships?.length) {
+          lines.push("", "## Relationships");
+          for (const rel of pg.relationships) {
+            lines.push(`- ${rel.from} \u2192 ${rel.to} (${rel.type}): ${rel.description}`);
+          }
+        }
+        if (pg.keyFlows?.length) {
+          lines.push("", "## Key Flows");
+          for (const f of pg.keyFlows) {
+            lines.push(`- **${f.name}** (trigger: ${f.trigger})`);
+            for (const s of f.steps ?? []) lines.push(`  - ${s.repo}/${s.component}: ${s.action} [${s.protocol}]`);
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+      const summaryPath = join(kbPath, "PROJECT_SUMMARY.md");
+      if (existsSync(summaryPath)) {
+        return { content: [{ type: "text", text: readFileSync(summaryPath, "utf-8") }] };
+      }
+      const profiles = loadAllProfiles(ctx.projectName);
+      if (profiles.length) {
+        const text = `# Project Repos
+
+${profiles.map((p) => `- **${p.name}** \u2014 ${p.role} (${p.domain}): ${p.description}`).join("\n")}
+
+_Run project-graph generation (requires LLM) for a full architecture view._`;
+        return { content: [{ type: "text", text }] };
+      }
+      return { content: [{ type: "text", text: "No architecture data yet. Index the project, then run profiling / project-graph generation (requires an LLM) for an architecture overview." }] };
+    }
+    if (name === "search_graph") {
+      const sys = loadSystemGraph(kbPath);
+      if (!sys) return { content: [{ type: "text", text: "No system graph found. Build KB first." }] };
+      const repo = args.repo;
+      const type = args.type;
+      const file = args.file;
+      const minDegree = args.minDegree ?? 0;
+      const limit = args.limit || 50;
+      const nameArg = args.name;
+      let nameTest = () => true;
+      if (nameArg) {
+        try {
+          const re = new RegExp(nameArg, "i");
+          nameTest = (s) => re.test(s);
+        } catch {
+          const lc = nameArg.toLowerCase();
+          nameTest = (s) => s.toLowerCase().includes(lc);
+        }
+      }
+      const degree = /* @__PURE__ */ new Map();
+      for (const e of sys.edges) {
+        if (edgeType(e) === "contains") continue;
+        degree.set(e.source, (degree.get(e.source) ?? 0) + 1);
+        degree.set(e.target, (degree.get(e.target) ?? 0) + 1);
+      }
+      const matches = sys.nodes.filter((n) => {
+        if (repo && !n.key.startsWith(repo + "::")) return false;
+        if (type && n.attributes?.type !== type) return false;
+        const f = n.attributes?.file ?? n.key.split("::")[1] ?? "";
+        if (file && !f.includes(file)) return false;
+        if (nameArg && !(nameTest(n.attributes?.label ?? "") || nameTest(n.key))) return false;
+        return (degree.get(n.key) ?? 0) >= minDegree;
+      }).map((n) => ({ key: n.key, label: nodeLabel(n), type: n.attributes?.type ?? "?", file: n.attributes?.file ?? n.key.split("::")[1] ?? "", deg: degree.get(n.key) ?? 0 })).sort((a, b) => b.deg - a.deg);
+      if (matches.length === 0) {
+        return { content: [{ type: "text", text: "No entities match the given filters." }] };
+      }
+      const rows = matches.slice(0, limit).map((m) => `- \`${m.label}\` (${m.type}, ${m.file}) \u2014 degree ${m.deg}  \`${m.key}\``).join("\n");
+      return { content: [{ type: "text", text: `# search_graph \u2014 ${matches.length} match${matches.length === 1 ? "" : "es"}
+
+${rows}${matches.length > limit ? `
+
+... and ${matches.length - limit} more` : ""}` }] };
+    }
+    if (name === "detect_changes") {
+      const repo = args.repo;
+      const limit = args.limit || 50;
+      if (!ctx.directoryPath) {
+        return { content: [{ type: "text", text: "detect_changes needs a local repo path \u2014 available in local/serve mode only (not remote-proxy mode)." }] };
+      }
+      const candidate = join(ctx.directoryPath, repo);
+      const repoPath = existsSync(join(candidate, ".git")) ? candidate : ctx.directoryPath;
+      if (!existsSync(repoPath)) {
+        return { content: [{ type: "text", text: `Repo path not found: ${repoPath}` }] };
+      }
+      let baseSha = args.baseSha;
+      if (!baseSha) {
+        const metaPath = join(kbPath, repo, "index_meta.json");
+        if (existsSync(metaPath)) {
+          try {
+            baseSha = JSON.parse(readFileSync(metaPath, "utf-8")).lastIndexedSha;
+          } catch {
+          }
+        }
+      }
+      if (!baseSha) {
+        return { content: [{ type: "text", text: "No base commit available. Pass baseSha, or index the repo first so a last-indexed SHA exists." }] };
+      }
+      const diff = getAllChanges(repoPath, baseSha);
+      if (diff.fallbackToFull) {
+        return { content: [{ type: "text", text: `git diff against ${baseSha.slice(0, 7)} failed or is too large to map incrementally. Check the base SHA.` }] };
+      }
+      const changedFiles = getChangedFilesList(diff);
+      if (changedFiles.length === 0 && diff.deleted.length === 0) {
+        return { content: [{ type: "text", text: `No source changes since ${baseSha.slice(0, 7)}.` }] };
+      }
+      const sys = loadSystemGraph(kbPath);
+      const changedKeys = /* @__PURE__ */ new Set();
+      if (sys) {
+        for (const f of changedFiles) {
+          for (const n of sys.nodes) {
+            if (n.key.startsWith(`${repo}::${f}::`) || n.key === `${repo}::${f}`) changedKeys.add(n.key);
+          }
+        }
+      }
+      const dependents = sys ? sys.edges.filter((e) => changedKeys.has(e.target) && !changedKeys.has(e.source) && edgeType(e) !== "contains") : [];
+      const dependentRepos = new Set(dependents.map((e) => e.source.split("::")[0]));
+      const lines = [
+        `# Changes since ${baseSha.slice(0, 7)} \u2014 ${repo}`,
+        "",
+        `## Changed files: ${changedFiles.length} (+${diff.added.length} / ~${diff.modified.length}), deleted ${diff.deleted.length}`,
+        ...changedFiles.slice(0, 30).map((f) => `- ${f}`),
+        "",
+        `## Affected entities: ${changedKeys.size}`,
+        ...[...changedKeys].slice(0, 30).map((k) => `- \`${k}\``),
+        "",
+        `## Dependents: ${dependents.length} edges from ${dependentRepos.size} repo(s)`,
+        ...dependents.slice(0, limit).map((e) => `- \`${e.source}\` \u2192 \`${e.target}\` (${edgeType(e) ?? "edge"})`),
+        "",
+        `## Affected repos: ${[...dependentRepos].join(", ") || "none"}`
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
     return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/tools/search.js

@@ -1,4 +1,6 @@
-import { getRetriever } from "@esankhan3/anvil-knowledge-core";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getRetriever, getKnowledgeBasePath, findChunksInFile } from "@esankhan3/anvil-knowledge-core";
 function registerSearchTools() {
   return [
     {
@@ -37,10 +39,24 @@ function registerSearchTools() {
         },
         required: ["query"]
       }
+    },
+    {
+      name: "get_code_snippet",
+      description: 'Fetch the source code for one entity by qualified name. Pass either id="repo::path/to/file::entity" or the separate repo/file/entity fields. Returns just that symbol \u2014 far cheaper than reading the whole file.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: 'Qualified id "repo::filePath::entity" (or "repo::filePath" for a whole file)' },
+          repo: { type: "string", description: "Repository name (alternative to id)" },
+          file: { type: "string", description: "File path relative to repo root (alternative to id)" },
+          entity: { type: "string", description: "Entity name (optional; with repo/file)" }
+        }
+      }
     }
   ];
 }
 async function handleSearchTool(name, args, ctx) {
+  if (name === "get_code_snippet") return await handleGetCodeSnippet(args, ctx);
   if (!["search_code", "search_semantic", "search_exact"].includes(name)) return null;
   if (!ctx.indexReady) {
     return { content: [{ type: "text", text: "Index not ready. Run reindex tool or wait for auto-indexing to complete." }] };
@@ -78,6 +94,52 @@ ${text}` }] };
     return { content: [{ type: "text", text: `Search failed: ${msg}` }] };
   }
 }
+async function handleGetCodeSnippet(args, ctx) {
+  let repo = args.repo;
+  let file = args.file;
+  let entity = args.entity;
+  if (typeof args.id === "string") {
+    const parts = args.id.split("::");
+    repo = parts[0];
+    if (parts.length >= 3) {
+      file = parts[1];
+      entity = parts.slice(2).join("::");
+    } else if (parts.length === 2) {
+      file = parts[1];
+    }
+  }
+  if (!repo || !file) {
+    return { content: [{ type: "text", text: 'Provide id="repo::file::entity" or repo + file (entity optional).' }] };
+  }
+  const chunksPath = join(getKnowledgeBasePath(ctx.projectName), "chunks.json");
+  if (!existsSync(chunksPath)) {
+    return { content: [{ type: "text", text: "No index found \u2014 chunks.json missing. Index the project first." }] };
+  }
+  try {
+    let matches = await findChunksInFile(
+      chunksPath,
+      (c) => c.repoName === repo && c.filePath === file && (!entity || c.entityName === entity),
+      5
+    );
+    if (matches.length === 0 && entity) {
+      matches = await findChunksInFile(chunksPath, (c) => c.repoName === repo && c.entityName === entity, 5);
+    }
+    if (matches.length === 0) {
+      return { content: [{ type: "text", text: `No snippet found for ${repo}::${file}${entity ? `::${entity}` : ""}` }] };
+    }
+    matches.sort((a, b) => (a.startLine ?? 0) - (b.startLine ?? 0));
+    const text = matches.map(
+      (c) => `### ${c.repoName}/${c.filePath}:${c.startLine}-${c.endLine}${c.entityName ? ` \u2014 ${c.entityName}` : ""}
+\`\`\`${c.language ?? ""}
+${c.content}
+\`\`\``
+    ).join("\n\n");
+    return { content: [{ type: "text", text }] };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Failed to read chunks: ${msg}` }] };
+  }
+}
 export {
   handleSearchTool,
   registerSearchTools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esankhan3/code-search-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for multi-repo code search — GitHub org or local path, zero config",
   "type": "module",
   "license": "MIT",
@@ -23,8 +23,8 @@
     "smoke": "bash scripts/smoke/run-smoke.sh"
   },
   "dependencies": {
-    "@esankhan3/anvil-agent-core": "^0.2.0",
-    "@esankhan3/anvil-knowledge-core": "^0.2.0",
+    "@esankhan3/anvil-agent-core": "^0.4.0",
+    "@esankhan3/anvil-knowledge-core": "^0.3.1",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "optionalDependencies": {