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