io.github.vola-trebla/ast-impact-mapper-mcp
MCP server that uses TypeScript AST to find which tests are affected by a code change
Open source Open in the app JSON README (API)
About
MCP server that uses TypeScript AST to find which tests are affected by a code change
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- vola-trebla
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.1
- Last push
- 2026-05-21T12:59:02Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:39
- Updated
- 2026-08-29 04:01:39
- Origin id
io.github.vola-trebla/ast-impact-mapper-mcp
README
# 🗺️ ast-impact-mapper-mcp ✨
[](https://www.npmjs.com/package/ast-impact-mapper-mcp)
[](https://www.npmjs.com/package/ast-impact-mapper-mcp)
[](https://github.com/vola-trebla/ast-impact-mapper-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
> **"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:
```json
// 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`:
```json
// 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:
```json
{
"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:
```json
// 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
```bash
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`:
```json
{
"mcpServers": {
"ast-impact-mapper": {
"command": "npx",
"args": ["-y", "ast-impact-mapper-mcp"]
}
}
}
```
#### Claude Code CLI
```bash
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`](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
```bash
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 🐸