archtracker-mcp

面向 AI 驱动开发的架构与依赖追踪器
MCP Server + CLI + Web Viewer + Claude Code Skills

快速开始 • 功能特性 • 多层架构 • Web 查看器 • MCP 工具 • CLI • 日本語

## 为什么选择 archtracker？ 当 AI agents 修改代码时，它们**会忽略连锁影响**： | 问题 | 不使用 archtracker | 使用 archtracker | |---------|-------------------|------------------| | Agent 修改了 `auth.ts` | 不知道有 12 个文件依赖于它 | 立即看到所有 12 个受影响的文件 | | 重构时文件重命名 | AI 在下次会话中引用旧路径 | `context` 命令提供当前有效路径 | | 添加了新依赖 | 无法看到耦合度的增加 | Diff 报告标记出架构变更 | | PR 审查 | 手动追踪依赖关系 | CI 自动检查架构偏移 | | 多服务项目 | 无法跨边界查看 | 支持层级感知分析与跨层链接检测 | **archtracker-mcp** 提供依赖分析、快照比对、影响模拟和交互式可视化 —— 所有功能均可通过 MCP tools、CLI、Web UI 或 Claude Code Skills 访问。 ## 功能特性 - **依赖图谱分析** — 基于正则的静态分析，支持 **13 种语言** (JS/TS, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala) - **多层架构** — 将多个服务/层级作为统一图谱分析，支持跨层连接检测 (v0.5.0 新增) - **交互式 Web 查看器** — 力导向图与凸包层级分组，层级图，以及基于 D3.js 的差异视图 - **影响模拟** — 点击任意文件可视化其传递性依赖项 (BFS 遍历) - **快照比对** — 保存架构快照并随时间检测偏移 - **MCP Server** — 通过 Model Context Protocol 为 Claude Code / AI agents 提供 5 个工具 - **Claude Code Skills** — 6 个斜杠命令 (`/arch-check`, `/arch-snapshot`, `/arch-serve` 等) - **CI 集成** — `--ci` 模式 + 自动生成 GitHub Actions 工作流 - **双语支持** — 完整支持英语/日语 (从 `LANG` 环境变量自动检测) - **深色/浅色主题** — 设置通过 localStorage 持久化 - **SVG/PNG 导出** — 导出依赖图谱用于文档 ## 快速开始 ### 安装 ``` npm install -g archtracker-mcp ``` ### 1. 分析您的项目 ``` archtracker analyze --target src ``` ### 2. 保存基线快照 ``` archtracker init --target src ``` ### 3. 启动 Web 查看器 ``` archtracker serve --target src --watch # => http://localhost:3000 ``` ### 4. 检查架构偏移 ``` archtracker check --target src ``` ## 多层架构 对于具有多个服务或层级的项目（例如前端 + 后端 + 共享库），archtracker 可以将其作为统一图谱进行分析。 ### 设置 在项目根目录创建 `.archtracker/layers.json`： ``` { "version": "1.0", "layers": [ { "name": "Frontend", "targetDir": "frontend/src", "language": "javascript", "color": "#58a6ff", "description": "React Web App" }, { "name": "Backend", "targetDir": "backend/app", "language": "python", "color": "#3fb950", "description": "FastAPI Server" } ], "connections": [ { "fromLayer": "Frontend", "fromFile": "api/client.ts", "toLayer": "Backend", "toFile": "main.py", "type": "api-call", "label": "REST API" } ] } ``` 或生成模板： ``` archtracker layers init ``` ### 使用 当 `layers.json` 存在时，所有命令自动使用多层模式： ``` archtracker analyze --root . # Analyzes all layers archtracker serve --root . --watch # Web viewer with layer tabs and convex hulls archtracker check --root . # Cross-layer diff check ``` 每一层都使用其独立的语言设置进行分析，然后合成为带有前缀路径的统一图谱（例如 `Backend/worker.py`）。 ### 带层级的 Web 查看器 - **层级标签**：多选切换以聚焦特定层级（Shift+点击进入独立模式） - **凸包分组**：每一层都用彩色边界线进行视觉分组 - **跨层链接**：显示层级间连接的虚线（可在设置中切换） - **Layer Cohesion 滑块**：调整节点在层级内的聚集紧密程度 - **差异高亮**：包含变更文件的层级边界会被高亮显示 ## Web 查看器 交互式 Web 查看器提供三种可视化模式： ### 图谱视图 (力导向)  - 拖拽、缩放并点击节点以探索依赖关系 - 点击节点以**固定**其高亮 —— 悬停其他节点进行比较 - 使用底部按钮按目录过滤，使用顶部标签按层级过滤 - 调整重力、层级凝聚力、节点大小、字体大小、链接透明度 - **影响模式**：点击任意文件查看所有受传递影响的文件  ### 层级视图 (DAG 布局)  - 分层自上而下的布局，显示依赖深度 - 点击固定高亮及详情面板 - 支持层级过滤及紧凑重排 ### 差异视图  - 架构变更的颜色编码可视化 - 绿色 = 新增，红色 = 删除，黄色 = 修改，蓝色 = 受影响 - 分组显示并高亮变更层级的边界 - 当存在用于比较的快照时可用 ``` # 文件更改时自动重载启动 archtracker serve --target src --port 3456 --watch ``` ## MCP Tools 将 archtracker 作为 MCP server 添加到 Claude Code 或任何兼容 MCP 的 AI agent： ``` { "mcpServers": { "archtracker": { "command": "npx", "args": ["-y", "archtracker-mcp"] } } } ``` | Tool | 描述 | |------|-------------| | `generate_map` | 分析依赖图谱并返回原始 JSON (用于程序化调用) | | `analyze_existing_architecture` | 综合性的人类可读分析报告 | | `save_architecture_snapshot` | 保存快照到 `.archtracker/snapshot.json` | | `check_architecture_diff` | 将快照与当前代码进行比对，显示影响 | | `get_current_context` | 获取有效文件路径和架构摘要 | | `search_architecture` | 按路径、影响、关键度或孤立状态搜索 | 当 `.archtracker/layers.json` 存在时，所有工具自动检测多层项目。 ## CLI Commands ``` archtracker init [options] Generate initial architecture snapshot archtracker analyze [options] Comprehensive analysis report archtracker check [options] Compare snapshot with current code archtracker context [options] Show architecture context (for AI sessions) archtracker serve [options] Launch interactive web viewer archtracker ci-setup [options] Generate GitHub Actions workflow archtracker layers init Create template layers.json archtracker layers list List configured layers Options: -t, --target Target directory (default: "src") -r, --root Project root (default: ".") -l, --language Target language (auto-detected if omitted) -p, --port Port for web viewer (default: 3000) -w, --watch Watch for file changes and auto-reload -e, --exclude Exclude patterns (regex) -n, --top Top N components in analysis (default: 10) --save Save snapshot after analysis --ci CI mode: exit 1 if review needed --json JSON output (context command) --lang Language: en | ja (auto-detected from LANG) ``` ## Claude Code Skills 将 `skills/` 目录复制到您的项目： ``` cp -r node_modules/archtracker-mcp/skills/ .claude/skills/ ``` | Skill | 描述 | |-------|-------------| | `/arch-analyze` | 运行综合性架构分析 | | `/arch-check` | 将快照与当前代码进行比对 | | `/arch-snapshot` | 保存当前架构快照 | | `/arch-context` | 使用有效路径初始化 AI 会话 | | `/arch-search` | 搜索架构 (路径、影响、关键、孤立) | | `/arch-serve` | 在浏览器中启动交互式 Web 查看器 | 所有 Skill 均自动支持多层项目。 ## 编程 API ``` import { analyzeProject, analyzeMultiLayer, saveSnapshot, loadSnapshot, computeDiff, formatDiffReport, formatAnalysisReport, } from "archtracker-mcp"; // Single-directory analysis const graph = await analyzeProject("src", { exclude: ["__tests__"] }); // Multi-layer analysis const layers = [ { name: "Frontend", targetDir: "frontend/src", language: "javascript" }, { name: "Backend", targetDir: "backend/app", language: "python" }, ]; const multi = await analyzeMultiLayer(".", layers); // Snapshot const snapshot = await saveSnapshot(".", graph); // Diff const prev = await loadSnapshot("."); if (prev) { const diff = computeDiff(prev.graph, graph); console.log(formatDiffReport(diff)); } ``` ## CI / CD ### 自动生成 GitHub Actions 工作流 ``` archtracker ci-setup --target src # 创建 .github/workflows/arch-check.yml ``` ### 手动设置 ``` # .github/workflows/arch-check.yml name: Architecture Check on: pull_request: branches: [main] jobs: arch-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "20" - run: npm ci - run: npx archtracker check --target src --ci ``` ## i18n 语言从 `LANG` / `LC_ALL` 环境变量自动检测： ``` LANG=ja_JP.UTF-8 archtracker analyze # Japanese output archtracker --lang ja check # Explicit Japanese ``` Web 查看器也支持通过设置面板切换语言。 ## 系统要求 - **Node.js** >= 18.0.0 支持的语言: JavaScript/TypeScript, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala ## 许可证 [MIT](LICENSE) © un907

archtracker-mcp _(日本語)

AI駆動開発のためのアーキテクチャ & 依存関係トラッカー
MCP サーバー + CLI + Web ビューア + Claude Code Skills

## なぜ archtracker？ AI エージェントがコードを修正する際、**波及的な影響を見逃します**： | 問題 | archtracker なし | archtracker あり | |------|-----------------|-----------------| | `auth.ts` を変更 | 12ファイルが依存していることを知らない | 影響を受ける全12ファイルを即座に表示 | | リファクタでファイル名変更 | 次のセッションで古いパスを参照 | `context` コマンドで現在の有効パスを取得 | | 新しい依存関係を追加 | 結合度の増加が見えない | 差分レポートがアーキテクチャ変更を検出 | | PRレビュー | 手動で依存関係を追跡 | CIが自動でアーキテクチャドリフトをチェック | | マルチサービス構成 | サービス境界を跨ぐ影響が見えない | レイヤー対応分析でクロスレイヤー接続を検出 | **archtracker-mcp** は依存関係分析、スナップショット差分、影響シミュレーション、インタラクティブな可視化を提供します。MCP ツール、CLI、Web UI、Claude Code Skills からアクセス可能です。 ## 機能 - **依存関係グラフ分析** — 正規表現ベースの静的解析、**13言語**対応（JS/TS, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala） - **マルチレイヤーアーキテクチャ** — 複数サービス/レイヤーを統合グラフとして分析、クロスレイヤー接続の自動検出（v0.5.0 新機能） - **インタラクティブ Web ビューア** — D3.js による力学モデルグラフ（凸包レイヤーグループ表示）、階層図、差分ビュー - **影響シミュレーション** — ファイルをクリックして推移的な被依存ファイルを可視化（BFS探索） - **スナップショット差分** — アーキテクチャスナップショットを保存し、ドリフトを検出 - **MCP サーバー** — Model Context Protocol 経由で5つのツールを提供 - **Claude Code Skills** — 6つのスラッシュコマンド（`/arch-check`、`/arch-snapshot`、`/arch-serve` 等） - **CI 統合** — `--ci` モード + GitHub Actions ワークフロー自動生成 - **多言語対応** — 日本語・英語完全対応（`LANG` 環境変数から自動検出） - **ダーク/ライトテーマ** — localStorage で設定を永続化 - **SVG/PNG エクスポート** — ドキュメント用にグラフをエクスポート ## 快速开始 ### 安装 ``` npm install -g archtracker-mcp ``` ### 1. プロジェクトを分析 ``` archtracker analyze --target src ``` ### 2. ベースラインスナップショットを保存 ``` archtracker init --target src ``` ### 3. Web ビューアを起動 ``` archtracker serve --target src --watch # => http://localhost:3000 ``` ### 4. 检查架构漂移 ``` archtracker check --target src ``` ## 多层架构 フロントエンド + バックエンド + 共有ライブラリなど、複数のサービスやレイヤーを持つプロジェクトを統合的に分析できます。 ### 设置 プロジェクトルートに `.archtracker/layers.json` を作成： ``` { "version": "1.0", "layers": [ { "name": "Frontend", "targetDir": "frontend/src", "language": "javascript", "color": "#58a6ff", "description": "React Web App" }, { "name": "Backend", "targetDir": "backend/app", "language": "python", "color": "#3fb950", "description": "FastAPI Server" } ], "connections": [ { "fromLayer": "Frontend", "fromFile": "api/client.ts", "toLayer": "Backend", "toFile": "main.py", "type": "api-call", "label": "REST API" } ] } ``` テンプレートの自動生成： ``` archtracker layers init ``` ### 使い方 `layers.json` が存在する場合、全コマンドが自動的にマルチレイヤーモードで動作します： ``` archtracker analyze --root . # 全レイヤーを分析 archtracker serve --root . --watch # レイヤータブ・凸包表示付き Web ビューア archtracker check --root . # クロスレイヤー差分チェック ``` 各レイヤーは独立した言語設定で個別に分析され、プレフィックス付きパス（例: `Backend/worker.py`）で統合グラフにマージされます。 ### Web ビューアでのレイヤー表示 - **レイヤータブ**: 複数選択トグルで特定レイヤーにフォーカス（Shift+クリックでソロモード） - **凸包グループ**: 各レイヤーが色付きの境界で視覚的にグループ化 - **クロスレイヤーリンク**: レイヤー間接続を点線で表示（設定で切替可能） - **Layer Cohesion スライダー**: レイヤー内ノードの凝集度を調整 - **差分ハイライト**: 変更を含むレイヤーの境界がハイライト ## Web 查看器 インタラクティブな Web ビューアは3つの可視モードを提供します： ### グラフビュー（力学モデル）  - ドラッグ、ズーム、クリックでノードの依存関係を探索 - ノードをクリックでハイライトを**ピン固定** — 他のノードをホバーして比較 - 下部のピルでディレクトリごと、上部のタブでレイヤーごとにフィルタリング - 重力、レイヤー凝集力、ノードサイズ、フォントサイズ、リンク透明度を調整可能 - **影響モード**: ファイルをクリックして推移的に影響を受ける全ファイルを表示  ### 階層ビュー（DAGレイアウト）  - 依存の深さを示すレイヤー型トップダウンレイアウト - クリックでピン固定 + 詳細パネル - レイヤー対応フィルタリング + コンパクト再配置 ### 差分ビュー  - アーキテクチャ変更の色分け可視化 - 緑=追加、赤=削除、黄=変更、青=影響 - 変更を含むレイヤー境界のハイライト表示 - スナップショットが存在する場合に利用可能 ``` # ファイル変更の自動リロード付きで起動 archtracker serve --target src --port 3456 --watch ``` ## MCP Tools archtracker を MCP サーバーとして Claude Code や MCP 互換 AI エージェントに追加： ``` { "mcpServers": { "archtracker": { "command": "npx", "args": ["-y", "archtracker-mcp"] } } } ``` | ツール | 説明 | |--------|------| | `generate_map` | 依存関係グラフを解析し構造化JSONで返す（プログラム用） | | `analyze_existing_architecture` | 包括的な人間向け分析レポート | | `save_architecture_snapshot` | `.archtracker/snapshot.json` にスナップショットを保存 | | `check_architecture_diff` | スナップショットと現在のコードを比較し影響を表示 | | `get_current_context` | 有効なファイルパスとアーキテクチャサマリーを取得 | | `search_architecture` | パス、影響範囲、重要度、孤立ファイルで検索 | `.archtracker/layers.json` が存在する場合、全ツールがマルチレイヤーモードを自動検出します。 ## CLI Commands ``` archtracker init [options] 初期アーキテクチャスナップショットを生成 archtracker analyze [options] 包括的な分析レポート archtracker check [options] スナップショットと現在のコードを比較 archtracker context [options] アーキテクチャコンテキストを表示（AIセッション用） archtracker serve [options] インタラクティブ Web ビューアを起動 archtracker ci-setup [options] GitHub Actions ワークフローを生成 archtracker layers init テンプレート layers.json を作成 archtracker layers list 設定済みレイヤーを一覧表示 オプション: -t, --target 対象ディレクトリ（デフォルト: "src"） -r, --root プロジェクトルート（デフォルト: "."） -l, --language 対象言語（省略時は自動検出） -p, --port Web ビューアのポート（デフォルト: 3000） -w, --watch ファイル変更の監視と自動リロード -e, --exclude 除外パターン（正規表現） -n, --top 分析の上位N件（デフォルト: 10） --save 分析後にスナップショットを保存 --ci CIモード: 要確認ファイルがあれば exit 1 --json JSON形式で出力（context コマンド） --lang 言語: en | ja（LANG から自動検出） ``` ## Claude Code Skills `skills/` ディレクトリをプロジェクトにコピー： ``` cp -r node_modules/archtracker-mcp/skills/ .claude/skills/ ``` | スキル | 説明 | |--------|------| | `/arch-analyze` | 包括的なアーキテクチャ分析を実行 | | `/arch-check` | スナップショットと現在のコードを比較 | | `/arch-snapshot` | 現在のアーキテクチャスナップショットを保存 | | `/arch-context` | 有効なファイルパスでAIセッションを初期化 | | `/arch-search` | アーキテクチャ検索（パス、影響、重要度、孤立） | | `/arch-serve` | インタラクティブ Web ビューアを起動 | 全スキルがマルチレイヤープロジェクトに自動対応します。 ## 编程 API ``` import { analyzeProject, analyzeMultiLayer, saveSnapshot, loadSnapshot, computeDiff, formatDiffReport, formatAnalysisReport, } from "archtracker-mcp"; // 単一ディレクトリ分析 const graph = await analyzeProject("src", { exclude: ["__tests__"] }); // マルチレイヤー分析 const layers = [ { name: "Frontend", targetDir: "frontend/src", language: "javascript" }, { name: "Backend", targetDir: "backend/app", language: "python" }, ]; const multi = await analyzeMultiLayer(".", layers); // スナップショット const snapshot = await saveSnapshot(".", graph); // 差分比較 const prev = await loadSnapshot("."); if (prev) { const diff = computeDiff(prev.graph, graph); console.log(formatDiffReport(diff)); } ``` ## CI / CD ### GitHub Actions ワークフローの自動生成 ``` archtracker ci-setup --target src # .github/workflows/arch-check.yml を生成 ``` ## 多言語対応 `LANG` / `LC_ALL` 環境変数から自動検出されます： ``` LANG=ja_JP.UTF-8 archtracker analyze # 日本語出力 archtracker --lang ja check # 明示的に日本語指定 ``` Web ビューアでも設定パネルから言語を切り替え可能です。 ## 動作要件 - **Node.js** >= 18.0.0 対応言語: JavaScript/TypeScript, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala ## 贡献 [CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。 ## 许可证 [MIT](LICENSE) © un907

标签：AI驱动开发, Claude集成, GNU通用公共许可证, MCP服务器, MITM代理, Node.js, SOC Prime, Web查看器, 上下文感知, 云安全监控, 代码重构, 依赖管理, 开发工具, 影响分析, 暗色界面, 架构可视化, 架构追踪, 自动化攻击, 软件供应链, 静态分析