ast-impact-mapper-mcp

🗺️ ast-impact-mapper-mcp ✨

「手当たり次第に調べるのはやめましょう。変更の影響を受けるテストだけを実行しましょう。」 🐸

ast-impact-mapper-mcp は、AST 解析（ts-morph）と依存関係グラフの追跡を使用して、TypeScript／JavaScript のコードベースを分析する高度な Model Context Protocol（MCP）サーバーです。AI エージェント（Claude や Cursor など）が、関連するテストだけを対象にし、デッドコードを見つけ、循環インポートの依存関係を特定し、API の変更を追跡できるようにします。

---

🧐 インポートグラフが必要な理由

ファイル名の一致（例：auth.ts → auth.test.ts）に基づいて影響を受けるテストを推測する方法は、精度が非常に低いです。些細な変更のたびにテストスイート全体を実行するのは、非常に時間がかかります。

インポートグラフは嘘をつきません。 テストファイルが変更されたソースファイルを間接的にインポートしている場合、そのテストは実行する必要があります。ast-impact-mapper-mcp は双方向のファイル依存関係グラフを構築し、「どのテストを実行すべきか？」という問いにミリ秒単位で回答します。

---

💡 簡単なデモ（実際の e2e フロー）

AI エージェントが共有ヘルパーの src/utils/auth.ts を変更したとします。すべてのテストをむやみに実行したり、名前から推測したりする代わりに、エージェントはこの MCP サーバーを使用します。

1. 影響を受けるテストを特定する

エージェントは、変更されたファイルを指定して get_affected_tests を呼び出します。

// 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. 依存関係を説明する

checkout.spec.ts が auth.ts に依存する理由を理解するため、エージェントは 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"
  ]
}

なるほど！ checkout の spec が user-fixture をインポートし、そこから auth がインポートされているのですね！

3. 実行時への影響を確認する

auth.ts の変更が TypeScript インターフェースの追加だけ（型のみの変更）だった場合、differentiate_type_impact を呼び出すと、エージェントには次のように伝えられます。

{
  "files": [{ "file": "/project/src/utils/auth.ts", "runtime_impact": false }],
  "total_tests_must_run": 0,
  "total_tests_skippable": 1
}

成功です！ 型のみの変更なので、エージェントはテストの実行をすべて省略でき、貴重な CPU 時間と時間を節約できます。

4. 最小限のテストを実行する

実行時の変更が含まれている場合は、エージェントが実行コマンドをリクエストします。

// Tool Call: generate_test_command({ changed_files: ["src/utils/auth.ts"], runner: "vitest" })
{
  "command": "npx vitest run tests/checkout.spec.ts"
}

---

🛠️ MCP ツールのリファレンス

すべてのツールには、一貫性のある型安全なスキーマ（引数は snake_case）が設定されています。

1. 影響範囲のマッピングと追跡

• get_affected_tests

  変更されたソースファイルを間接的にインポートしているすべてのテストファイルを検索します。

  • 引数:
    • project_root (string、必須): TypeScript プロジェクトの絶対パスです。
    • changed_files (string[]、任意): 変更されたファイルのパスです。
    • git_diff (string、任意): git diff --name-only の標準出力そのものです。
  • 戻り値: 変更されたファイル、影響を受けるテスト、合計数の詳細なマップです。

• get_affected_tests_by_branch

  git を使って現在の状態とベースブランチを自動的に比較し、影響を受けるテストを検索します。

  • 引数:
    • project_root (string、必須)
    • base_branch (string、デフォルト: "main"): 比較対象のブランチです。

• get_rename_aware_diff

  ファイルの移動や名前変更を追跡し（git diff -M を使用）、フォーマットや空白の変更を無視する、非常に堅牢なブランチ影響分析です。

  • 引数:
    • project_root (string、必須)
    • base_branch (string、デフォルト: "main")
    • similarity_threshold (number、デフォルト: 90): 移動と判定する類似度のしきい値（%）です。

• explain_impact

  変更されたソースファイルが特定のテストに影響する理由を示す、インポートの正確な経路を追跡して説明します。

  • 引数:
    • project_root (string、必須)
    • changed_file (string、必須)
    • test_file (string、必須)

• generate_test_command

  影響を受けるテストのサブセットに対応したテストランナー（vitest、jest、または playwright）用のコマンドラインを生成します。

  • 引数:
    • project_root (string、必須)
    • changed_files (string[]、必須)
    • runner (enum: jest、vitest、playwright、デフォルト: vitest)

---

2. TypeScript に特化した詳細なコード分析

• differentiate_type_impact

  インポートと型を調べて、型のみの変更（インターフェース、型、または import type のエクスポート）を特定します。変更が実行時バンドルに影響しない場合、テストの実行を完全に省略できます。

  • 引数:
    • project_root (string、必須)
    • changed_files (string[]、必須)

• analyze_api_surface_mutation

  ファイルを HEAD バージョンと比較し、公開 API を変更しているか（breaking_api_change）、内部実装の編集のみか（internal_refactor）を判定します。

  • 引数:
    • project_root (string、必須)
    • file_path (string、必須)

• generate_skeleton_view

  関数やメソッドの本体を取り除き、シグネチャ、JSDoc、行番号のみを残した、トークン効率に優れたファイルのスケルトンを生成します。

  • 引数:
    • project_root (string、必須)
    • file_path (string、必須)
    • include_jsdoc (boolean、デフォルト: true)
    • include_private_members (boolean、デフォルト: false)

• get_symbol_dependency_graph

  ファイル間の宣言レベルの依存関係（関数、クラス、変数）を追跡し、内部宣言の使用箇所を特定します。

  • 引数:
    • project_root (string、必須)
    • file_path (string、必須)
    • symbol_name (string、任意): マッピングする特定のエクスポートシンボルです。
    • direction (enum: forward、reverse、bidirectional、デフォルト: bidirectional)

---

3. コードベースの健全性とグラフ分析

• identify_unreachable_modules

  被インポート数がゼロの孤立したソースファイル（安全に削除できるデッドコード）を検出します。標準的なエントリーポイントは自動的に考慮されます。

  • 引数：
    • project_root（string、必須）
    • entry_points（string[]、任意）：警告対象から除外するエントリーポイントを明示的に指定します。
    • limit（number、デフォルト：50）

• detect_architectural_cycles

  モジュールの初期化順序が予測不能になる循環依存ループ（例：A → B → C → A）を検出します。

  • 引数：
    • project_root（string、必須）

• get_dependency_graph

  ファイルの直接のインポート元／インポート先を、JSON 形式または視覚的な Mermaid TD フローチャートで返します。

  • 引数：
    • project_root（string、必須）
    • file_path（string、必須）
    • format（enum：json、mermaid、デフォルト：json）

• get_coverage_gaps

  インポートカバレッジがゼロのファイル、つまりどのテストファイルからもインポートされていないファイルを特定します。

  • 引数：
    • project_root（string、必須）
    • source_dirs（string[]、任意）
    • limit（number、デフォルト：50）

• get_test_summary

  テストカバレッジ率、最も深いインポートチェーン、リスクが高く最も多くインポートされているモジュールの概要を提示します。

  • 引数：
    • project_root（string、必須）

• refresh_project

  AST と依存関係グラフのキャッシュを無効化します。ブランチのチェックアウト後や、リモートの git 更新を取得した後に実行してください。

  • 引数：
    • project_root（string、必須）

---

🚀 インストールとセットアップ

1. グローバルインストール

npm install -g ast-impact-mapper-mcp

2. エディター／エージェントクライアントの設定

VS Code / Cursor

次の内容を .cursor/mcp.json または .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

---

💬 シナリオ例

共有ページコンポーネント src/pages/login-page.ts を変更するとします。

1. AI エージェントが get_rename_aware_diff を実行します： ページオブジェクトを間接的にインポートしているのは tests/auth.spec.ts だけだと検出します。
2. AI エージェントが differentiate_type_impact を実行します： 型定義インターフェースのみを追加したことを確認し、type_only_change に分類します。その結果、テスト実行を完全に省略し、開発者の作業時間を節約できます。
3. AI エージェントが explain_impact を実行します： tests/auth.spec.ts がなぜそれに依存しているのかを尋ねられた場合、次のパスを表示します。 tests/auth.spec.ts → src/fixtures/app.ts → src/pages/login-page.ts。

---

🔗 エコシステム

• ast-impact-mapper-mcp は「変更によって影響を受けるテストはどれですか？」に答えます 🗺️
• flakiness-graph-mcp は「影響を受けるテストのうち、過去に不安定だったものはどれですか？」に答えます 📊
• これらを組み合わせることで、優先順位付けされた、堅牢で最小限のテストスイートを実行するための、完璧なフィードバックループが構築されます。

---

🛠️ CLI 開発

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

---

📄 ライセンス

MIT © vola-trebla 🐸