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