🗺️ ast-impact-mapper-mcp ✨

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

ast-impact-mapper-mcp is 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.

🧐 Why import graphs?

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-mcp builds a bidirectional file dependency graph and answers "which tests should I run?" in milliseconds.

💡 Quick Showcase (Real-World e2e Flow)

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:

1. Identify Affected Tests

The agent calls get_affected_tests with 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
}

2. Explain the Connection

To understand why checkout.spec.ts depends on auth.ts, the agent calls explain_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!_

3. Check for Runtime Impact

If the change in auth.ts was only adding a TypeScript interface (type-only change), calling differentiate_type_impact tells 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._

4. Run Minimal Tests

If it _does_ contain 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"
}

🛠️ MCP Tools Reference

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

1. Impact Mapping & Tracing

• #### get_affected_tests

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 of git diff --name-only.
• Returns: Detailed map of changed files, affected tests, and totals.

• #### get_affected_tests_by_branch

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.

• #### get_rename_aware_diff

Highly robust branch impact analysis that tracks file moves/renames (via git 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.

• #### explain_impact

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)

• #### generate_test_command

Constructs CLI commands for test runners (vitest, jest, or playwright) 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

• #### differentiate_type_impact

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

• Arguments:
• project_root (string, required)
• changed_files (string[], required)

• #### analyze_api_surface_mutation

Compares a file against its HEAD version 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)

• #### generate_skeleton_view

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)

• #### get_symbol_dependency_graph

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)

3. Codebase Health & Graph Insights

• #### identify_unreachable_modules

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)

• #### detect_architectural_cycles

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

• Arguments:
• project_root (string, required)

• #### get_dependency_graph

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

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

• #### get_coverage_gaps

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)

• #### get_test_summary

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

• Arguments:
• project_root (string, required)

• #### refresh_project

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

• Arguments:
• project_root (string, required)

🚀 Installation & Setup

1. Global Installation

npm install -g ast-impact-mapper-mcp

2. Configure Editor / Agent Client

#### VS Code / Cursor

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

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

#### Claude Code CLI

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

💬 Example Scenario

Imagine you modify a shared page component: src/pages/login-page.ts.

1. AI Agent runs `get_rename_aware_diff`:

It detects that only tests/auth.spec.ts imports the page object transitively.

1. AI Agent runs `differentiate_type_impact`:

It sees you only added a type definition interface, classifying it as type_only_change -> it skips running the test execution completely, saving developer cycles!

1. AI Agent runs `explain_impact`:

If asked why tests/auth.spec.ts depends on it, it renders the path: tests/auth.spec.ts → src/fixtures/app.ts → src/pages/login-page.ts.

🔗 The Ecosystem

• `ast-impact-mapper-mcp` answers: _"Which tests are affected by my changes?"_ 🗺️
• [`flakiness-graph-mcp`](https://github.com/vola-trebla/flakiness-graph-mcp) answers: _"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.

🛠️ CLI Development

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

📄 License

MIT © vola-trebla 🐸