🗺️ ast-impact-mapper-mcp

An MCP server that uses the TypeScript AST to determine exactly which tests are affected by a code change — so your AI agent stops running the entire suite and starts running only what matters.

🤔 The Problem

When you change src/utils/auth.ts, which tests should run? Most tools either run everything (slow) or guess by filename (wrong). Import graphs don't lie — if a test transitively imports the changed file, it needs to run.

This server builds a precise dependency graph from your TypeScript project and answers that question in milliseconds.

🛠️ Tools

Impact analysis

| Tool | Arguments | What it returns | | ------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | get_affected_tests | project_root, changed_files[] or git_diff | Test files that transitively import any of the changed files | | get_affected_tests_by_branch | project_root, base_branch? | Same as above but runs git diff internally | | get_rename_aware_diff | project_root, base_branch?, similarity_threshold? | Like above but handles file moves/renames and skips whitespace-only changes | | differentiate_type_impact | project_root, changed_files[] | Splits affected tests into must-run vs skippable (type-only changes emit no JS) | | analyze_api_surface_mutation | project_root, file_path | Compares exported signatures against HEAD — breaking_api_change or internal_refactor | | explain_impact | project_root, changed_file, test_file | Step-by-step import chain from a test file to the changed source file |

Code health

| Tool | Arguments | What it returns | | ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------- | | identify_unreachable_modules | project_root, entry_points[]?, limit? | Source files with zero incoming imports — dead code candidates | | detect_architectural_cycles | project_root | Circular import chains — [A → B → C → A] with severity: warning | | get_dependency_graph | project_root, file_path, format? | Direct imports and importers for a specific file (json or mermaid) | | get_coverage_gaps | project_root, source_dirs[]?, limit? | Source files not reachable from any test — completely untested code | | get_test_summary | project_root | Coverage rate, most-imported files, deepest import chains | | refresh_project | project_root | Clears the cached AST — use after git pull or branch switch |

🚀 Setup

1. Install

npm install -g ast-impact-mapper-mcp

Or build from source:

git clone https://github.com/vola-trebla/ast-impact-mapper-mcp.git
cd ast-impact-mapper-mcp
npm install && npm run build

2. Add the MCP server to your editor

Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)

{
  "mcpServers": {
    "ast-impact-mapper": {
      "command": "ast-impact-mapper-mcp"
    }
  }
}

Claude Code

claude mcp add ast-impact-mapper ast-impact-mapper-mcp

💬 Example usage

My project root is /my-project. I just changed these files from git diff:
  src/utils/auth.ts
  src/api/userService.ts

1. get_rename_aware_diff — which tests are affected by this branch (handles renames)?
2. differentiate_type_impact — which of those tests can I skip if the change is type-only?
3. analyze_api_surface_mutation for src/utils/auth.ts — is this a breaking API change?
4. explain_impact — why does tests/login.spec.ts care about auth.ts?
5. detect_architectural_cycles — are there any circular deps I should break first?
6. identify_unreachable_modules — which files are dead code I can safely delete?

📊 Example output

Given a project with this structure:

src/
  fixtures/base-fixture.ts   ← imports home-page + results-page
  pages/google-home-page.ts
  pages/google-results-page.ts
tests/
  google-pom.spec.ts         ← imports base-fixture

get_affected_tests — change google-home-page.ts, find affected tests:

{
  "changed_files": ["/my-project/src/pages/google-home-page.ts"],
  "affected_tests": ["/my-project/tests/google-pom.spec.ts"],
  "total_affected": 1
}

explain_impact — why does the spec depend on google-home-page.ts?

{
  "changed_file": "/my-project/src/pages/google-home-page.ts",
  "test_file": "/my-project/tests/google-pom.spec.ts",
  "found": true,
  "import_chain": [
    "/my-project/tests/google-pom.spec.ts",
    "/my-project/src/fixtures/base-fixture.ts",
    "/my-project/src/pages/google-home-page.ts"
  ]
}

get_test_summary — project-wide health:

{
  "total_source_files": 4,
  "total_test_files": 1,
  "covered_source_files": 3,
  "coverage_rate": 0.75,
  "most_imported_files": [{ "file": "src/fixtures/base-fixture.ts", "imported_by_count": 1 }],
  "deepest_import_chains": [{ "test": "tests/google-pom.spec.ts", "depth": 2 }]
}

🧠 How it works

The server uses ts-morph to load your TypeScript project (with full tsconfig support, including path aliases) and builds two graphs:

• Forward graph: file → files it imports
• Reverse graph: file → files that import it

get_affected_tests does a BFS through the reverse graph starting from the changed files, collecting every file that transitively depends on them, then filters to *.spec.ts / *.test.ts.

explain_impact does a BFS through the forward graph from the test file until it reaches the changed file, then reconstructs the shortest import path.

The project is cached in memory per project_root — the first call parses the AST, subsequent calls reuse it.

🔗 Works great with flakiness-knowledge-graph-mcp

• ast-impact-mapper-mcp answers "which tests are affected by this change?"
• flakiness-knowledge-graph-mcp answers "of those tests, which ones are historically unreliable?"

Together, an AI agent can give you a prioritized, minimal test run: the right tests, ranked by flakiness risk.

📋 Scripts

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)

📄 License

MIT