depgraph-core 1.8.0 → 1.9.0

package/README.md

@@ -311,18 +311,18 @@ DepGraph ships an **MCP server** (`depgraph-mcp`) that lets Claude analyze your
 
 ### Quick setup
 
-**1. Build the MCP server**
+**If the package is published to npm** (zero-install, always up to date):
 ```bash
-npm install
-npm run release:all   # compiles + bundles both CLI and MCP server
+claude mcp add depgraph -- npx -p depgraph-core depgraph-mcp
 ```
 
-**2. Register with Claude Code** (run once)
+**If running from a local build** (clone the repo first):
 ```bash
-claude mcp add depgraph -- node /absolute/path/to/depgraph/depgraph-mcp.js
+npm install && npm run release:all
+npm run mcp:register
 ```
 
-**3. Use it** — open Claude Code in any project and ask naturally:
+**Then use it** — open Claude Code in any project and ask naturally:
 ```
 Summarize the dependency graph of /Users/me/my-app
 What is the risk of changing getUserById in /Users/me/my-app?

package/depgraph-mcp.js

@@ -24110,28 +24110,79 @@ function buildPipeline(projectDir) {
   const metrics = computeMetrics(graph);
   return { files, parsed, graph, metrics };
 }
-function analyzeProject(projectDir) {
+function buildSubgraph(graph, focusName, maxDepth) {
+  const focusNode = [...graph.nodes.values()].find((n) => n.name === focusName);
+  if (!focusNode) return { nodes: /* @__PURE__ */ new Map(), edges: [] };
+  const included = /* @__PURE__ */ new Set();
+  const queue = [{ id: focusNode.id, depth: 0 }];
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift();
+    if (included.has(id)) continue;
+    included.add(id);
+    if (depth >= maxDepth) continue;
+    for (const edge of graph.edges) {
+      if (edge.from === id && !included.has(edge.to)) queue.push({ id: edge.to, depth: depth + 1 });
+      if (edge.to === id && !included.has(edge.from)) queue.push({ id: edge.from, depth: depth + 1 });
+    }
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  for (const id of included) {
+    const node = graph.nodes.get(id);
+    if (node) nodes.set(id, node);
+  }
+  return {
+    nodes,
+    edges: graph.edges.filter((e) => included.has(e.from) && included.has(e.to))
+  };
+}
+function buildProseSummary(summary) {
+  const s = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  const shortIds = (ids) => ids.slice(0, 3).map((id) => id.split("__")[0]).join(", ") + (ids.length > 3 ? ` (+${ids.length - 3} more)` : "");
+  const parts = [
+    `${s(summary.totalFiles, "file")}, ${s(summary.totalNodes, "node")}, ${s(summary.totalEdges, "edge")}.`
+  ];
+  if (summary.criticalNodes.length > 0) {
+    parts.push(
+      `${s(summary.criticalNodes.length, "critical node")} \u2014 change carefully: ${shortIds(summary.criticalNodes)}.`
+    );
+  }
+  if (summary.entryPoints.length > 0) {
+    parts.push(`${s(summary.entryPoints.length, "entry point")}: ${shortIds(summary.entryPoints)}.`);
+  }
+  if (summary.leafNodes.length > 0) {
+    parts.push(`${s(summary.leafNodes.length, "leaf node")} (pure utilities with no outgoing deps).`);
+  }
+  if (summary.isolatedNodes.length > 0) {
+    parts.push(`${s(summary.isolatedNodes.length, "isolated node")} \u2014 potential dead code: ${shortIds(summary.isolatedNodes)}.`);
+  }
+  return parts.join(" ");
+}
+function analyzeProject(projectDir, opts = {}) {
+  const { verbosity = "full", focus, depth = 3 } = opts;
   const { files, parsed, metrics } = buildPipeline(projectDir);
   const totalLines = parsed.reduce((sum, f) => sum + f.lines, 0);
-  return {
-    meta: {
-      version: VERSION,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      totalFiles: parsed.length,
-      totalLines
-    },
-    summary: {
-      totalNodes: metrics.nodes.size,
-      totalEdges: metrics.edges.length,
-      entryPoints: getEntryPoints(metrics),
-      leafNodes: getLeafNodes(metrics),
-      isolatedNodes: getIsolatedNodes(metrics),
-      criticalNodes: getCriticalNodes(metrics)
-    },
-    nodes: [...metrics.nodes.values()],
-    edges: metrics.edges,
-    files: parsed
+  const graph = focus ? buildSubgraph(metrics, focus, depth) : metrics;
+  const meta = {
+    version: VERSION,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    totalFiles: parsed.length,
+    totalLines
+  };
+  const summary = {
+    totalNodes: graph.nodes.size,
+    totalEdges: graph.edges.length,
+    entryPoints: getEntryPoints(graph),
+    leafNodes: getLeafNodes(graph),
+    isolatedNodes: getIsolatedNodes(graph),
+    criticalNodes: getCriticalNodes(graph)
   };
+  if (verbosity === "sketch") {
+    return { meta, summary, nodes: [], edges: [], files: [] };
+  }
+  if (verbosity === "overview") {
+    return { meta, summary, nodes: [...graph.nodes.values()], edges: [], files: [] };
+  }
+  return { meta, summary, nodes: [...graph.nodes.values()], edges: graph.edges, files: parsed };
 }
 function analyzeImpact(projectDir, targetNode, changeDescription) {
   const { metrics } = buildPipeline(projectDir);
@@ -24149,16 +24200,68 @@ function analyzeGitImpact(options) {
   }));
   return { changedEntities, impacts };
 }
-function getGraphSummary(projectDir) {
+function getGraphSummary(projectDir, verbosity = "overview") {
   const { files, parsed, metrics } = buildPipeline(projectDir);
-  return {
+  const base = {
     totalFiles: files.length,
     totalNodes: metrics.nodes.size,
     totalEdges: metrics.edges.length,
+    criticalNodes: getCriticalNodes(metrics)
+  };
+  if (verbosity === "sketch") {
+    return { ...base, entryPoints: [], leafNodes: [], isolatedNodes: [] };
+  }
+  return {
+    ...base,
     entryPoints: getEntryPoints(metrics),
     leafNodes: getLeafNodes(metrics),
-    isolatedNodes: getIsolatedNodes(metrics),
-    criticalNodes: getCriticalNodes(metrics)
+    isolatedNodes: getIsolatedNodes(metrics)
+  };
+}
+function describeNode(projectDir, nodeName) {
+  const { metrics } = buildPipeline(projectDir);
+  const node = [...metrics.nodes.values()].find((n) => n.name === nodeName);
+  if (!node) {
+    return {
+      found: false,
+      name: nodeName,
+      file: "",
+      line: 0,
+      type: "",
+      lang: "",
+      centralityScore: 0,
+      inDegree: 0,
+      outDegree: 0,
+      importedBy: [],
+      imports: [],
+      role: "not found"
+    };
+  }
+  const importedBy = [...new Set(
+    metrics.edges.filter((e) => e.to === node.id).map((e) => metrics.nodes.get(e.from)?.name).filter((n) => Boolean(n))
+  )];
+  const imports = [...new Set(
+    metrics.edges.filter((e) => e.from === node.id).map((e) => metrics.nodes.get(e.to)?.name).filter((n) => Boolean(n))
+  )];
+  let role;
+  if (node.centralityScore > 20) role = "critical shared dependency";
+  else if (node.inDegree === 0 && node.outDegree > 0) role = "entry point";
+  else if (node.outDegree === 0 && node.inDegree > 0) role = "leaf";
+  else if (node.inDegree === 0 && node.outDegree === 0) role = "isolated \u2014 potential dead code";
+  else role = "connector";
+  return {
+    found: true,
+    name: node.name,
+    file: node.file,
+    line: node.line,
+    type: node.type,
+    lang: node.lang,
+    centralityScore: node.centralityScore,
+    inDegree: node.inDegree,
+    outDegree: node.outDegree,
+    importedBy,
+    imports,
+    role
   };
 }
 
@@ -24168,16 +24271,17 @@ var server = new McpServer({
   version: VERSION
 });
 server.tool(
-  "analyze_project",
-  "Scan a project directory and return its full dependency graph \u2014 nodes, edges, entry points, leaf nodes, isolated nodes, critical nodes, and per-file metadata. Use this to understand the full structure of a codebase before making changes.",
+  "describe_node",
+  'PREFERRED first tool for questions about a specific function, class, or entity. Returns what depends on it, what it depends on, its file/line, type, and role \u2014 all in ~50 tokens. Use this INSTEAD of analyze_project when the question is "tell me about X" or "what uses X" or "what does X import". Much cheaper than loading the full graph.',
   {
-    projectDir: external_exports.string().describe(
-      "Absolute path to the project directory to analyze (e.g. /Users/me/my-app)"
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
+    nodeName: external_exports.string().describe(
+      'Exact name of the entity to look up (e.g. "getUserById", "UserService", "AuthMiddleware")'
     )
   },
-  async ({ projectDir }) => {
+  async ({ projectDir, nodeName }) => {
     try {
-      const result = analyzeProject(projectDir);
+      const result = describeNode(projectDir, nodeName);
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
@@ -24191,15 +24295,22 @@ server.tool(
 );
 server.tool(
   "get_graph_summary",
-  "Get a lightweight summary of the dependency graph \u2014 file/node/edge counts, entry points, leaf nodes, isolated nodes, and critical nodes \u2014 without returning the full graph data. Faster than analyze_project when you only need the overview.",
+  'Get a project-wide overview \u2014 file/node/edge counts, critical nodes, entry points, leaf nodes, and isolated nodes. Use verbosity "sketch" (~50 tokens) for a quick orientation, "overview" for the full summary. Use format "prose" to get a single readable sentence (~100 tokens) instead of JSON. Call this before analyze_project or when you only need counts and structure, not full node data.',
   {
-    projectDir: external_exports.string().describe("Absolute path to the project directory")
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
+    verbosity: external_exports.enum(["sketch", "overview", "full"]).optional().describe(
+      '"sketch" = counts + critical nodes only (~50 tokens). "overview" = full summary with entry/leaf/isolated lists (default). "full" = same as overview.'
+    ),
+    format: external_exports.enum(["json", "prose"]).optional().describe(
+      '"json" = structured JSON object (default). "prose" = single readable paragraph (~100 tokens) \u2014 use when you want compact context without JSON overhead.'
+    )
   },
-  async ({ projectDir }) => {
+  async ({ projectDir, verbosity, format }) => {
     try {
-      const result = getGraphSummary(projectDir);
+      const result = getGraphSummary(projectDir, verbosity ?? "overview");
+      const text = format === "prose" ? buildProseSummary(result) : JSON.stringify(result, null, 2);
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        content: [{ type: "text", text }]
       };
     } catch (err) {
       return {
@@ -24211,16 +24322,14 @@ server.tool(
 );
 server.tool(
   "simulate_impact",
-  "Simulate the cascading downstream impact of changing a specific function, class, or entity. Returns a risk score (0-100), risk level (LOW/MEDIUM/HIGH/CRITICAL), a list of all affected nodes with their change requirements, a testing plan, and actionable recommendations.",
+  'PREFERRED tool when the question is impact-oriented: "what breaks if I change X?". Use this INSTEAD of analyze_project \u2014 it requires no graph preload and costs ~200 tokens vs ~80k for the full graph. Returns risk score (0-100), risk level (LOW/MEDIUM/HIGH/CRITICAL), all affected nodes, a testing plan, and recommendations.',
   {
-    projectDir: external_exports.string().describe(
-      "Absolute path to the project directory"
-    ),
+    projectDir: external_exports.string().describe("Absolute path to the project directory"),
     targetNode: external_exports.string().describe(
       'Name of the function, class, or entity to simulate changing (e.g. "getUserById")'
     ),
     changeDescription: external_exports.string().describe(
-      'Human-readable description of the proposed change (e.g. "removing the userId parameter")'
+      'Description of the proposed change (e.g. "removing the userId parameter")'
     )
   },
   async ({ projectDir, targetNode, changeDescription }) => {
@@ -24237,9 +24346,40 @@ server.tool(
     }
   }
 );
+server.tool(
+  "analyze_project",
+  'Return the dependency graph. EXPENSIVE at full verbosity \u2014 use verbosity "sketch" or "overview", or narrow scope with "focus" + "depth" to avoid token overload. Prefer describe_node for single-entity questions, simulate_impact for risk questions, and get_graph_summary for project-wide orientation.',
+  {
+    projectDir: external_exports.string().describe(
+      "Absolute path to the project directory to analyze (e.g. /Users/me/my-app)"
+    ),
+    verbosity: external_exports.enum(["sketch", "overview", "full"]).optional().describe(
+      '"sketch" = meta + summary only, no nodes/edges (~100 tokens). "overview" = meta + summary + nodes, no edges. "full" = complete graph incl. edges and file detail (default, can be very large).'
+    ),
+    focus: external_exports.string().optional().describe(
+      "Entity name to centre the graph on \u2014 returns only the subgraph within `depth` hops of this node (bidirectional). Use to scope the result to one module instead of the whole project."
+    ),
+    depth: external_exports.number().optional().describe(
+      "Max BFS hops from the focus node (default 3). Only used when focus is set."
+    )
+  },
+  async ({ projectDir, verbosity, focus, depth }) => {
+    try {
+      const result = analyzeProject(projectDir, { verbosity, focus, depth });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
 server.tool(
   "git_impact",
-  "Detect which functions/classes changed in a git diff and simulate their downstream impact on the whole project. Supports three modes: uncommitted changes, a specific commit, or a branch comparison.",
+  'PREFERRED tool for "what did this commit/branch change and what does it break?". Detects changed functions/classes from a git diff and simulates their downstream impact \u2014 no manual entity name needed. Supports uncommitted changes, a specific commit SHA, or a branch comparison.',
   {
     projectDir: external_exports.string().describe(
       "Absolute path to the project directory (must be a git repository)"

package/depgraph.js

@@ -4173,7 +4173,7 @@ function getFlag(flag) {
 }
 function printHelp() {
   console.log(`
-${bold("DepGraph")} ${dim("v1.8.0")}
+${bold("DepGraph")} ${dim("v1.9.0")}
 ${dim("Dependency mapping \xB7 Impact simulation \xB7 Developer intelligence")}
 
 ${bold("USAGE")}
@@ -4222,7 +4222,7 @@ ${bold("GIT EXAMPLES")}
 function printBanner() {
   console.log(`
 ${bold("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501")}
-${bold("  DepGraph")}  ${dim("v1.8.0")}
+${bold("  DepGraph")}  ${dim("v1.9.0")}
 ${bold("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501")}
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depgraph-core",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Dependency mapping and impact simulation for JS/TS projects",
   "main": "depgraph.js",
   "bin": {