{
  "markdown": "# 🗺️ ast-impact-mapper-mcp ✨\n\n[![npm version](https://img.shields.io/npm/v/ast-impact-mapper-mcp.svg)](https://www.npmjs.com/package/ast-impact-mapper-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/ast-impact-mapper-mcp.svg)](https://www.npmjs.com/package/ast-impact-mapper-mcp)\n[![CI](https://github.com/vola-trebla/ast-impact-mapper-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vola-trebla/ast-impact-mapper-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> **\"Stop boiling the ocean. Run only the tests that actually care about your changes.\"** 🐸\n\n`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.\n\n---\n\n## 🧐 Why import graphs?\n\nGuessing 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.\n\n**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.\n\n---\n\n## 💡 Quick Showcase (Real-World e2e Flow)\n\nImagine 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:\n\n### 1. Identify Affected Tests\n\nThe agent calls `get_affected_tests` with the changed file:\n\n```json\n// Tool Call: get_affected_tests({ changed_files: [\"src/utils/auth.ts\"] })\n{\n  \"changed_files\": [\"/project/src/utils/auth.ts\"],\n  \"affected_tests\": [\"/project/tests/checkout.spec.ts\"],\n  \"total_affected\": 1\n}\n```\n\n### 2. Explain the Connection\n\nTo understand why `checkout.spec.ts` depends on `auth.ts`, the agent calls `explain_impact`:\n\n```json\n// Tool Call: explain_impact({ changed_file: \"src/utils/auth.ts\", test_file: \"tests/checkout.spec.ts\" })\n{\n  \"found\": true,\n  \"import_chain\": [\n    \"/project/tests/checkout.spec.ts\",\n    \"/project/src/fixtures/user-fixture.ts\",\n    \"/project/src/utils/auth.ts\"\n  ]\n}\n```\n\n_Aha! The checkout spec imports the user-fixture, which imports auth!_\n\n### 3. Check for Runtime Impact\n\nIf the change in `auth.ts` was only adding a TypeScript interface (type-only change), calling `differentiate_type_impact` tells the agent:\n\n```json\n{\n  \"files\": [{ \"file\": \"/project/src/utils/auth.ts\", \"runtime_impact\": false }],\n  \"total_tests_must_run\": 0,\n  \"total_tests_skippable\": 1\n}\n```\n\n_Success! Since it is a type-only change, the agent can skip running tests entirely, saving precious CPU cycles and time._\n\n### 4. Run Minimal Tests\n\nIf it _does_ contain runtime changes, the agent requests the execution command:\n\n```json\n// Tool Call: generate_test_command({ changed_files: [\"src/utils/auth.ts\"], runner: \"vitest\" })\n{\n  \"command\": \"npx vitest run tests/checkout.spec.ts\"\n}\n```\n\n---\n\n## 🛠️ MCP Tools Reference\n\nAll tools are configured with consistent, type-safe schemas (arguments in `snake_case`).\n\n### 1. Impact Mapping & Tracing\n\n- #### `get_affected_tests`\n\n  Finds all test files transitively importing changed source files.\n  - **Arguments:**\n    - `project_root` (string, required): Absolute path to the TypeScript project.\n    - `changed_files` (string[], optional): Modified file paths.\n    - `git_diff` (string, optional): Raw stdout of `git diff --name-only`.\n  - **Returns:** Detailed map of changed files, affected tests, and totals.\n\n- #### `get_affected_tests_by_branch`\n\n  Automatically diffs the current state against a base branch using git to find affected tests.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `base_branch` (string, default: `\"main\"`): Branch to compare against.\n\n- #### `get_rename_aware_diff`\n\n  Highly robust branch impact analysis that tracks file moves/renames (via `git diff -M`) and ignores formatting/whitespace changes.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `base_branch` (string, default: `\"main\"`)\n    - `similarity_threshold` (number, default: `90`): % similarity threshold to declare a move.\n\n- #### `explain_impact`\n\n  Traces and explains the exact chain of imports showing why a changed source file affects a specific test.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `changed_file` (string, required)\n    - `test_file` (string, required)\n\n- #### `generate_test_command`\n  Constructs CLI commands for test runners (`vitest`, `jest`, or `playwright`) matching the affected tests subset.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `changed_files` (string[], required)\n    - `runner` (enum: `jest`, `vitest`, `playwright`, default: `vitest`)\n\n---\n\n### 2. TypeScript-specific Deep Code Analysis\n\n- #### `differentiate_type_impact`\n\n  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!\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `changed_files` (string[], required)\n\n- #### `analyze_api_surface_mutation`\n\n  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`).\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `file_path` (string, required)\n\n- #### `generate_skeleton_view`\n\n  Generates a token-optimized skeleton of a file by stripping out function and method bodies, keeping only signatures, JSDocs, and line numbers.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `file_path` (string, required)\n    - `include_jsdoc` (boolean, default: `true`)\n    - `include_private_members` (boolean, default: `false`)\n\n- #### `get_symbol_dependency_graph`\n  Traces declaration-level dependencies (functions, classes, variables) across files, finding internal declarations usage.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `file_path` (string, required)\n    - `symbol_name` (string, optional): Specific export symbol to map.\n    - `direction` (enum: `forward`, `reverse`, `bidirectional`, default: `bidirectional`)\n\n---\n\n### 3. Codebase Health & Graph Insights\n\n- #### `identify_unreachable_modules`\n\n  Finds orphaned source files that have zero incoming imports (dead code safe to prune). Automatically respects standard entry points.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `entry_points` (string[], optional): Explicit entry-points to exclude from warning.\n    - `limit` (number, default: `50`)\n\n- #### `detect_architectural_cycles`\n\n  Locates circular dependency loops (e.g. `A → B → C → A`) which cause unpredictable module initialization orders.\n  - **Arguments:**\n    - `project_root` (string, required)\n\n- #### `get_dependency_graph`\n\n  Returns direct imports/importers of a file in JSON format or as a visual **Mermaid TD flowchart**.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `file_path` (string, required)\n    - `format` (enum: `json`, `mermaid`, default: `json`)\n\n- #### `get_coverage_gaps`\n\n  Identifies files with zero import coverage — those that are never imported by any test file.\n  - **Arguments:**\n    - `project_root` (string, required)\n    - `source_dirs` (string[], optional)\n    - `limit` (number, default: `50`)\n\n- #### `get_test_summary`\n\n  Provides a high-level view of test coverage rate, deepest import chains, and high-risk most-imported modules.\n  - **Arguments:**\n    - `project_root` (string, required)\n\n- #### `refresh_project`\n  Invalidates AST and dependency graphs cache. Run this after checking out branches or pulling remote git updates.\n  - **Arguments:**\n    - `project_root` (string, required)\n\n---\n\n## 🚀 Installation & Setup\n\n### 1. Global Installation\n\n```bash\nnpm install -g ast-impact-mapper-mcp\n```\n\n### 2. Configure Editor / Agent Client\n\n#### VS Code / Cursor\n\nAdd the following to your `.cursor/mcp.json` or `.vscode/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ast-impact-mapper\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ast-impact-mapper-mcp\"]\n    }\n  }\n}\n```\n\n#### Claude Code CLI\n\n```bash\nclaude mcp add ast-impact-mapper npx -- -y ast-impact-mapper-mcp\n```\n\n---\n\n## 💬 Example Scenario\n\nImagine you modify a shared page component: `src/pages/login-page.ts`.\n\n1. **AI Agent runs `get_rename_aware_diff`**:\n   It detects that only `tests/auth.spec.ts` imports the page object transitively.\n2. **AI Agent runs `differentiate_type_impact`**:\n   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!\n3. **AI Agent runs `explain_impact`**:\n   If asked why `tests/auth.spec.ts` depends on it, it renders the path:\n   `tests/auth.spec.ts` → `src/fixtures/app.ts` → `src/pages/login-page.ts`.\n\n---\n\n## 🔗 The Ecosystem\n\n- **`ast-impact-mapper-mcp`** answers: _\"Which tests are affected by my changes?\"_ 🗺️\n- **[`flakiness-graph-mcp`](https://github.com/vola-trebla/flakiness-graph-mcp)** answers: _\"Of those affected tests, which ones are historically unstable?\"_ 📊\n- Together, they form a perfect feedback loop for running a prioritized, resilient, and minimal test suite.\n\n---\n\n## 🛠️ CLI Development\n\n```bash\nnpm run build        # Compile TypeScript to dist/\nnpm run lint         # Run ESLint validation\nnpm run format       # Format files via Prettier\nnpm test             # Run unit tests via Vitest\n```\n\n---\n\n## 📄 License\n\nMIT © vola-trebla 🐸\n",
  "bytes": 9835,
  "sha": "c14a0b72c73c5875f51776c32c552096380ce7252d682f87ee7325c8636f4b60",
  "repo_slug": "vola-trebla/ast-impact-mapper-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vola_trebla_ast_impact_mapper__d7da78fc/readme"
}