Impact Graph MCP

MCP plugin for AST-based impact analysis of TypeScript codebases.

Understand the blast radius of any code change before you make it.

Installation

npm install -g impact-graph-mcp

Usage

Add to your MCP configuration:

{
  "mcpServers": {
    "impact-graph": {
      "command": "impact-graph",
      "args": [],
      "type": "stdio"
    }
  }
}

Or run the installer from a project root:

impact-graph install

This writes an impact-graph entry into .mcp.json in the current directory.

---

Tools

analyze_impact

Analyzes the impact of modifying a function, file, or module in a TypeScript project.

Input:

Field	Type	Required	Description
target	string	Yes	Function name, file path, or module identifier
root_dir	string	No	Project root directory (defaults to CWD)

Output:

Field	Type	Description
target	string	The analyzed target
direct_dependents	string[]	Files/modules that directly call or import the target
indirect_dependents	string[]	Downstream callers (transitive)
usage_count	number	Number of direct usages
risk_score	number	Numerical risk score (0–100)
risk_factors	string[]	Scored risk signals contributing to the score
risk_explanation	string[]	Human-readable reasons behind the risk score
next_actions	string[]	Prioritized, actionable checklist for safe modification
entry_points	string[]	Entry points (API routes, CLI commands) that reach this target
layers_affected	string[]	System layers touched: api, auth, frontend, database, core
is_critical	boolean	Whether the target is on a critical path
impact_summary	object	Severity, blast radius, and primary concern
recommended_strategy	string[]	High-level rule-based modification strategies
suggested_tests	string[]	Test scenarios to add or run
safe_changes	string[]	Change types that are generally safe for this target
risky_changes	string[]	Change types that need extra care
top_dependents	string[]	The most important dependents to inspect first (up to 5)
graph	ImpactGraph	Full bounded dependency graph (up to 30 nodes) centered on the target
focus_graph	ImpactGraph	Filtered high-signal graph showing only the most important relationships (up to 20 nodes)

ImpactGraph shape

interface ImpactGraph {
  nodes: {
    id: string;
    label: string;
    type: 'function' | 'file' | 'module';
    layer: string;
    risk: 'low' | 'moderate' | 'high';
  }[];
  edges: {
    from: string;
    to: string;
    type: 'calls' | 'imports';
  }[];
}

The focus_graph applies the same shape but retains only:

• The target node
• Direct dependents and direct dependencies
• High-priority nodes: entry points (+10), high-risk nodes (+8), critical-layer nodes (api/auth/database, +5), indirect dependents (+3)
• Edges are only included when both endpoints are in the graph

---

Example response

{
  "target": "loginUser",
  "usage_count": 3,
  "risk_score": 72,
  "risk_explanation": [
    "Reachable from user-facing entry points",
    "Part of authentication flow",
    "Multiple modules directly depend on this"
  ],
  "next_actions": [
    "Add regression tests before modifying this code",
    "Make incremental changes instead of large refactors",
    "Test authentication flows thoroughly after changes",
    "Ensure session and token handling remain intact",
    "Test all user-facing flows that rely on this function"
  ],
  "impact_summary": {
    "severity": "high",
    "blast_radius": "medium",
    "primary_concern": "affects authentication flow"
  },
  "recommended_strategy": [
    "add tests before modifying",
    "validate authentication and session behavior"
  ],
  "suggested_tests": [
    "valid login",
    "invalid credentials",
    "expired session",
    "authorized access",
    "unauthorized access"
  ],
  "safe_changes": [
    "internal logic refactors",
    "logging additions",
    "performance improvements without signature changes"
  ],
  "risky_changes": [
    "changing return types",
    "modifying function signatures",
    "altering authentication or authorization logic"
  ],
  "top_dependents": [
    "src/app/api/login/route.ts"
  ],
  "graph": {
    "nodes": [
      { "id": "loginUser", "label": "loginUser", "type": "function", "layer": "auth", "risk": "moderate" },
      { "id": "src/app/api/login/route.ts", "label": "route.ts", "type": "file", "layer": "api", "risk": "low" }
    ],
    "edges": [
      { "from": "src/app/api/login/route.ts", "to": "loginUser", "type": "calls" }
    ]
  },
  "focus_graph": {
    "nodes": [
      { "id": "loginUser", "label": "loginUser", "type": "function", "layer": "auth", "risk": "moderate" },
      { "id": "src/app/api/login/route.ts", "label": "route.ts", "type": "file", "layer": "api", "risk": "low" }
    ],
    "edges": [
      { "from": "src/app/api/login/route.ts", "to": "loginUser", "type": "calls" }
    ]
  }
}

---

Visualization

Open a local browser visualization for a specific target:

impact-graph visualize loginUser

Open an interactive full-project visualization (searchable sidebar, click any node to graph it):

impact-graph visualize

Both commands run analyze_impact and push the result to a local web server that stays running in the background at http://127.0.0.1:51789. On first run the browser opens to that URL automatically. Every subsequent visualize call updates the same open tab in place — no new files, no new tabs.

If the server fails to start (e.g., port conflict), the command falls back to writing a temporary HTML file and opening it directly. Set IMPACT_GRAPH_PORT to use a different port.

To stop the background server, kill the node process via Task Manager (Windows) or kill $(lsof -ti:51789) (macOS/Linux).

Browser visualization layout

The single-target visualization is a dark-theme two-panel page:

Left panel — dependency graph

• SVG node graph with radial layout; target node at center with glow ring
• Full Graph / Focus Graph toggle — switch between the full bounded graph and the filtered high-signal graph
• Arrowhead edges; dashed lines for imports, solid for calls
• Node hover tooltip showing path, layer, type, and risk
• Color legend: red = high risk, orange = moderate, green = low

Right panel — full analysis data (340 px, scrollable)

Section	Content
Stats grid	Risk score + color bar, severity, blast radius, primary concern
Next Actions	Imperative checklist (up to 7 items)
Risk Explanation	Plain-language reasons behind the score
Layers Affected	Color-coded layer tags (api, auth, database, frontend, core)
Recommended Strategy	High-level modification strategies
Suggested Tests	Test scenario tags
Safe & Risky Changes	Side-by-side columns
Top Dependents	Most important files to inspect first
Entry Points	API routes and CLI commands that reach the target
All Dependents (collapsed)	Full direct + indirect dependent lists
Risk Factors (collapsed)	Raw scored risk signal breakdown

All sections are collapsible. The page has no external dependencies — CSS, JS, and SVG are fully inlined.

Full-project visualization layout

The no-target visualization (impact-graph visualize) adds a sidebar on the left. Clicking any symbol swaps both the graph and the analysis panel to show that symbol's impact data. The full analysis panel and Full/Focus toggle are identical to the single-target page.

Region	Content
Sidebar (280px)	Searchable list of all exported symbols, sorted by risk; risk-dot, layer badge
Graph wrap (flex)	SVG dependency graph with Full/Focus toggle, arrowhead edges, hover tooltips
Analysis panel (340px)	Same collapsible sections as single-target — stats, Next Actions, Risk Explanation, Layers, Strategy, Tests, Safe/Risky Changes, Top Dependents, Entry Points, All Dependents, Risk Factors

For React or Next.js apps, the package also exposes a minimal SVG force graph component:

import { GraphView } from 'impact-graph-mcp/web/GraphView';
import type { ImpactGraph } from 'impact-graph-mcp/graph';

export function GraphPage({ graph }: { graph: ImpactGraph }) {
  return <GraphView graph={graph} target="loginUser" />;
}

The viewer uses d3-force, colors high-risk nodes red, moderate-risk nodes yellow, and low-risk nodes green.

---

CLI Commands

Command	Description
impact-graph	Start MCP server over stdio
impact-graph install	Add impact-graph MCP entry to .mcp.json in the current project
impact-graph visualize <target>	Open browser visualization for a specific function/file
impact-graph visualize	Open interactive full-project visualization with searchable sidebar

---

Layers Detected

Layer	Matched paths
api	app/api/, /route.ts, /handler.ts, /api/
auth	/auth/, auth.ts, /middleware.ts, /session/
frontend	/page.tsx, /components/, .tsx, /ui/
database	/db/, /schema, /queries, /migrations/, .sql
core	/lib/, /utils, /types, /config/, /constants

---

next_actions Rules

The next_actions field produces a concise, deduped checklist (max 7 items) using these deterministic rules:

Condition	Actions added
risk_score > 70	"Add regression tests before modifying this code"; "Make incremental changes instead of large refactors"
layers_affected includes api	"Avoid breaking API contracts (request/response shape)"; "Verify all endpoints using this function"
layers_affected includes auth	"Test authentication flows thoroughly after changes"; "Ensure session and token handling remain intact"
layers_affected includes database	"Validate data consistency after modification"; "Check for unintended data mutations"
usage_count > 20	"Refactor incrementally to avoid widespread breakage"; "Search for all usages before modifying"
Combined dependents > 5	"Consider creating a wrapper instead of modifying directly"; "Update dependents carefully if changing function signature"
Entry points present	"Test all user-facing flows that rely on this function"

If no rules match, falls back to: "Proceed with the smallest behavior-preserving change".

---

focus_graph Filtering

The focus_graph reduces the full graph to ≤ 20 nodes using an importance score:

Signal	Score
Entry point	+10
High risk	+8
Direct dependent or direct dependency	+6
Critical layer (api, auth, database)	+5
Indirect dependent	+3

Priority order when capping:

1. Target (always kept)
2. Direct dependents + direct dependencies (always attempted, trimmed by score if over cap)
3. High-priority nodes (entry points, high risk, critical layers)
4. Remaining nodes with any positive importance score, closest first

Only edges where both endpoints are included in the focused set are kept.

---

Development

npm run dev       # Watch mode
npm run build     # Production build
npm test          # Run tests
npm run lint      # ESLint
npm pack --dry-run  # Inspect package contents before publish

---

Publishing

Publishing is handled via GitHub Actions on each GitHub Release:

1. Update code; run lint, tests, build, and pack dry-run.
2. npm version <patch|minor|major> — bumps package.json and creates the git tag.
3. git push origin main && git push origin <tag>.
4. Create a GitHub Release for that tag — Actions publishes to npm automatically.

---

License

MIT