🗺️ 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.

• #### `get_affected_tests_by_branch`

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

• #### `get_rename_aware_diff`

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

• #### `explain_impact`

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

• #### `generate_test_command`

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

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!

• #### `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`).

• #### `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.

• #### `get_symbol_dependency_graph`

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

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.

• #### `detect_architectural_cycles`

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

• #### `get_dependency_graph`

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

• #### `get_coverage_gaps`

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

• #### `get_test_summary`

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

• #### `refresh_project`

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

🚀 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.

2. 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!

3. 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`** 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 🐸