Archtracker MCP

🇯🇵 日本語

archtracker-mcp

Architecture & Dependency Tracker for AI-Driven Development

MCP Server + CLI + Web Viewer + Claude Code Skills

Quick Start • Features • Multi-Layer • Web Viewer • MCP Tools • CLI

______________________________________________________________________

为什么是archtracker？

当AI代理修改代码时，他们 错过级联影响:

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）
• 多层体系结构 --将多个服务/层分析为具有跨层连接检测的统一图
• 交互式Web查看器 --带凸包层分组的力有向图、层次图、D3.js的差异视图
• 安全强化 --XSS安全HTML转义，所有MCP工具上的路径遍历保护（v0.6.0）
• 碰撞模拟 --单击任何文件以可视化可传递的依赖项（BFS遍历）
• 快照困难 --保存架构快照并检测随时间的漂移
• MCP服务器 --通过模型上下文协议为Claude Code/AI代理提供6个工具
• Claude代码技能 --6个斜线命令(/arch-check, /arch-snapshot, /arch-serve等等）
• CI集成 — --ci 模式+自动生成的GitHub操作工作流
• 双语 --完全英语/日语支持（从自动检测 LANG env）
• 黑暗/光明主题 --设置通过本地存储保持不变
• 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键并单击可进入独奏模式）
• 凸包：每一层都用彩色边界进行视觉分组
• 跨层链接：虚线显示层之间的连接（可在设置中切换）
• 层内聚滑块：调整节点在其层内聚集的紧密程度
• 差异突出显示：当图层边界包含更改的文件时，会突出显示图层边界

网络观众

交互式web查看器提供三种可视化模式：

图形视图（力定向）

Graph View

• 拖动、缩放和单击节点以探索依赖关系
• 单击节点以 针 其突出显示--将其他节点悬停以进行比较
• 按带底部药丸的目录过滤，按带顶部标签的层过滤
• 调整重力、层凝聚力、节点大小、字体大小、链接不透明度
• 冲击模式：单击任何文件以查看所有受传递影响的文件

Impact Simulation

图层焦点

Layer Focus

• 按住Shift键并单击图层选项卡 独奏 它；单击其他以添加
• 凸壳显示层边界；虚线显示跨层链接
• 过滤后的物理自动调整，以实现更清晰的分离

层次视图（DAG布局）

Hierarchy View

• 自上而下的分层布局，显示依赖深度
• 单击以用细节面板固定突出显示
• 具有紧凑布局的层感知过滤

差异视图

Diff View

• 建筑变化的颜色编码可视化
• 绿色=添加，红色=删除，黄色=修改，蓝色=受影响
• 对更改的图层进行带突出显示边界的图层分组
• 当存在可供比较的快照时可用

# Launch with auto-reload on file changes
archtracker serve --target src --port 3456 --watch

MCP工具

将archtracker添加为Claude Code或任何兼容MCP的AI代理的MCP服务器：

{
  "mcpServers": {
    "archtracker": {
      "command": "npx",
      "args": ["-y", "archtracker-mcp"]
    }
  }
}

所有工具在以下情况下自动检测多层项目 .archtracker/layers.json 存在。

命令行命令

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)

多层钞票：何时 .archtracker/layers.json 存在和 --target 如果没有明确设置，所有命令都会自动使用多层分析。使用 --root 指定项目根。

Claude代码技能

复制 skills/ 项目的目录：

cp -r node_modules/archtracker-mcp/skills/ .claude/skills/

所有技能都自动支持多层项目。

程序化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操作工作流

archtracker ci-setup --target src
# Creates .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

国际化

从以下位置自动检测语言 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

贡献

看 贡献.md 作为指导方针。

许可证

麻省理工学院 ©联合国907