ast-impact-mapper-mcp

Uses TypeScript AST to determine which tests are affected by code changes

"Stop boiling the ocean. Run only the tests that actually care about your changes."🐸

ast-impact-mapper-mcpis an advanced Model Context Protocol (MCP) server that analyzes your TypeScript/JavaScript codebase using AST parsing (ts-morph) and dependency graph tracing. It helps AI agents (like Claude or Cursor) target only the relevant tests, find dead code, identify circular import dependencies, and trace API mutations.

Guessing affected tests based on matching filenames (e.g.auth.ts->auth.test.ts) is highly inaccurate. Running the entire test suite on every minor change is extremely slow.

Import graphs do not lie.If a test file transitively imports a modified source file, it must be run.ast-impact-mapper-mcpbuilds a bidirectional file dependency graph and answers "which tests should I run?" in milliseconds.

Imagine your AI agent modifies a shared helper:src/utils/auth.ts. Instead of blindly running all tests or guessing by name, the agent uses this MCP server:

The agent callsget_affected_testswith the changed file:

// Tool Call: get_affected_tests({ changed_files: ["src/utils/auth.ts"] }) { "changed_files": ["/project/src/utils/auth.ts"], "affected_tests": ["/project/tests/checkout.spec.ts"], "total_affected": 1 }

To understand whycheckout.spec.tsdepends onauth.ts, the agent callsexplain_impact:

// Tool Call: explain_impact({ changed_file: "src/utils/auth.ts", test_file: "tests/checkout.spec.ts" }) { "found": true, "import_chain": [ "/project/tests/checkout.spec.ts", "/project/src/fixtures/user-fixture.ts", "/project/src/utils/auth.ts" ] }

Aha! The checkout spec imports the user-fixture, which imports auth!

If the change inauth.tswas only adding a TypeScript interface (type-only change), callingdifferentiate_type_impacttells the agent:

{ "files": [{ "file": "/project/src/utils/auth.ts", "runtime_impact": false }], "total_tests_must_run": 0, "total_tests_skippable": 1 }

Success! Since it is a type-only change, the agent can skip running tests entirely, saving precious CPU cycles and time.

If itdoescontain runtime changes, the agent requests the execution command:

// Tool Call: generate_test_command({ changed_files: ["src/utils/auth.ts"], runner: "vitest" }) { "command": "npx vitest run tests/checkout.spec.ts" }

All tools are configured with consistent, type-safe schemas (arguments insnake_case).

Finds all test files transitively importing changed source files.

- Arguments:

- project_root(string, required): Absolute path to the TypeScript project.
- changed_files(string[], optional): Modified file paths.
- git_diff(string, optional): Raw stdout ofgit diff --name-only.

Automatically diffs the current state against a base branch using git to find affected tests.

- Arguments:

- project_root(string, required)
- base_branch(string, default:"main"): Branch to compare against.

Highly robust branch impact analysis that tracks file moves/renames (viagit diff -M) and ignores formatting/whitespace changes.

- Arguments:

- project_root(string, required)
- base_branch(string, default:"main")
- similarity_threshold(number, default:90): % similarity threshold to declare a move.

Traces and explains the exact chain of imports showing why a changed source file affects a specific test.

- Arguments:

- project_root(string, required)
- changed_file(string, required)
- test_file(string, required)

Constructs CLI commands for test runners (vitest,jest, orplaywright) matching the affected tests subset.

- Arguments:

- project_root(string, required)
- changed_files(string[], required)
- runner(enum:jest,vitest,playwright, default:vitest)

2. TypeScript-specific Deep Code Analysis

Inspects imports and types to isolate type-only changes (interfaces, types, orimport typeexports). Helps skip test execution entirely if the changes do not impact the runtime bundle!

- Arguments:

- project_root(string, required)
- changed_files(string[], required)

Compares a file against itsHEADversion and determines if it modifies the public API (breaking_api_change) or only contains internal implementation edits (internal_refactor).

- Arguments:

- project_root(string, required)
- file_path(string, required)

Generates a token-optimized skeleton of a file by stripping out function and method bodies, keeping only signatures, JSDocs, and line numbers.

- Arguments:

- project_root(string, required)
- file_path(string, required)
- include_jsdoc(boolean, default:true)
- include_private_members(boolean, default:false)

Traces declaration-level dependencies (functions, classes, variables) across files, finding internal declarations usage.

- Arguments:

- project_root(string, required)
- file_path(string, required)
- symbol_name(string, optional): Specific export symbol to map.
- direction(enum:forward,reverse,bidirectional, default:bidirectional)

Finds orphaned source files that have zero incoming imports (dead code safe to prune). Automatically respects standard entry points.

- Arguments:

- project_root(string, required)
- entry_points(string[], optional): Explicit entry-points to exclude from warning.
- limit(number, default:50)

Locates circular dependency loops (e.g.A → B → C → A) which cause unpredictable module initialization orders.

- Arguments:

- project_root(string, required)

Returns direct imports/importers of a file in JSON format or as a visualMermaid TD flowchart.

- Arguments:

- project_root(string, required)
- file_path(string, required)
- format(enum:json,mermaid, default:json)

Identifies files with zero import coverage — those that are never imported by any test file.

- Arguments:

- project_root(string, required)
- source_dirs(string[], optional)
- limit(number, default:50)

Provides a high-level view of test coverage rate, deepest import chains, and high-risk most-imported modules.

- Arguments:

- project_root(string, required)

Invalidates AST and dependency graphs cache. Run this after checking out branches or pulling remote git updates.

- Arguments:

- project_root(string, required)

Add the following to your.cursor/mcp.jsonor.vscode/mcp.json:

{ "mcpServers": { "ast-impact-mapper": { "command": "npx", "args": ["-y", "ast-impact-mapper-mcp"] } } }

claude mcp add ast-impact-mapper npx -- -y ast-impact-mapper-mcp

Imagine you modify a shared page component:src/pages/login-page.ts.
- AI Agent runsget_rename_aware_diff: It detects that onlytests/auth.spec.tsimports the page object transitively.
- AI Agent runsdifferentiate_type_impact: It sees you only added a type definition interface, classifying it astype_only_change-> it skips running the test execution completely, saving developer cycles!
- AI Agent runsexplain_impact: If asked whytests/auth.spec.tsdepends on it, it renders the path:tests/auth.spec.ts→src/fixtures/app.ts→src/pages/login-page.ts.

- ast-impact-mapper-mcpanswers:"Which tests are affected by my changes?"🗺️
- flakiness-graph-mcpanswers:"Of those affected tests, which ones are historically unstable?"📊
- Together, they form a perfect feedback loop for running a prioritized, resilient, and minimal test suite.

npm run build # Compile TypeScript to dist/ npm run lint # Run ESLint validation npm run format # Format files via Prettier npm test # Run unit tests via Vitest

Official Chrome DevTools MCP server for controlling and inspecting a live Chrome browser from coding agents such as Gemini, Claude, Cursor, and Copilot.