内容
# Atlas UI
MCP 服务器让 Claude 深度了解您的前端代码库——组件、钩子、服务、路由、数据流，所有这些。指向一个 React 或 Vue 项目，它会构建一个目录，Claude 可以在工作时查询。
## TLDR: 快速开始
1. **配置 VS Code**（通过您的 MCP 扩展设置，例如 `.vscode/mcp.json`）：
```json
{
"mcpServers": {
"atlas-ui": {
"command": "node",
"args": ["/绝对路径/to/atlas-ui/dist/server.js"],
"env": {
"WORKSPACE_ROOT": "/绝对路径/to/your/target/project"
}
}
}
}
```
2. **重启 VS Code 并尝试这些提示：**
- *"列出项目中的所有组件。"* (`list_all_components`)
- *"Button 组件的属性是什么？"* (`get_component_props`)
- *"显示 UserProfile 组件的数据流。"* (`get_data_flow`)
- *"有哪些死代码可以删除？"* (`find_dead_code`)
## 它做什么
与其让 Claude 在每次需要了解事物如何组合时都在您的代码库中 grep，不如让该服务器预先扫描您的项目并公开一组用于导航架构的工具。它了解：
- **组件、页面、钩子、服务、适配器、上下文、存储** —— 按架构层分类（存储涵盖 Pinia、Zustand 和 Redux Toolkit）
- **属性和接口** —— 从 TypeScript 定义中解析
- **依赖链** —— 什么使用什么，上游和下游
- **路由图** —— React Router 和 Vue Router，以及基于文件的路由（Next.js App/Pages Router，Nuxt），包括受保护的路由和嵌套布局
- **数据流** —— 跟踪从组件 → 钩子/存储 → 服务 → 适配器 → API 端点完整的路径
- **死代码** —— 查找未被任何人导入的已导出项目（像 `App.tsx`/`main.tsx` 这样的入口点计为用法，因此根挂载组件不会被错误标记）
- **可驱动的选择器** —— 每个组件的 `data-testid` 值和表单字段，带有现成的选择器，因此流程可以被脚本化而无需阅读源代码
它会自动检测您的项目是 React 还是 Vue，并相应地设置合理的扫描目标。文件监视会随着您的工作保持缓存新鲜。
目录范围内的列表和搜索结果返回紧凑的摘要以降低 token 成本；`get_component_detail` 具有完整的元数据，而 `list_all_components` 接受 `verbose: true` 以获取所有内容。当名称与多个文件匹配时，基于名称的工具返回一个 `ambiguous` 结果以及候选项，而不是猜测 —— 调用时带有 `file`（路径子字符串）以选择一个。
## 设置
**从 npm**（无需克隆）：
```bash
npx atlas-ui-mcp /path/to/your/app
```
或在 MCP 配置中，`"command": "npx", "args": ["-y", "atlas-ui-mcp", "/path/to/your/app"]`.
**从源代码：**
```bash
npm install
npm run build
```
### Claude 代码
将以下内容添加到您的项目的 `.mcp.json`（或 `~/.claude/mcp.json` 以全局使用）：
```json
{
"mcpServers": {
"atlas-ui": {
"command": "node",
"args": ["/path/to/atlas-ui/dist/server.js"],
"env": {
"WORKSPACE_ROOT": "/path/to/your/project"
}
}
}
}
```
### Claude 桌面版
**macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"atlas-ui": {
"command": "node",
"args": ["/path/to/atlas-ui/dist/server.js"],
"env": {
"WORKSPACE_ROOT": "/path/to/your/project"
}
}
}
}
```
`WORKSPACE_ROOT` 告诉服务器您的项目位于哪里。您也可以将其作为 CLI 参数传递 (`node dist/server.js /path/to/project`)。如果两者都没有设置，它默认为服务器所在目录的上两级。
## 配置
在项目根目录下创建一个 `.atlas-ui.json` 以自定义扫描。 如果您不创建它，服务器会自动检测您的框架并使用它找到的默认值。
```json
{
"scanTargets": [
{ "dir": "src/components", "extensions": [".tsx"], "type": "component" },
{ "dir": "src/pages", "extensions": [".tsx"], "type": "page" },
{ "dir": "src/hooks", "extensions": [".ts", ".tsx"], "type": "hook" },
{ "dir": "src/services", "extensions": [".ts"], "type": "service" },
{ "dir": "src/adapters", "extensions": [".ts"], "type": "adapter" },
{ "dir": "src/contexts", "extensions": [".tsx"], "type": "context" }
],
"routeFiles": ["src/App.tsx"],
"aliases": {
"@/": "src/"
},
"exclude": ["node_modules", "dist", "build", "__tests__", "*.test.*", "*.spec.*"]
}
```
| 字段 | 它做什么 |
|-------|-------------|
| `scanTargets` | 要扫描的目录，查找哪些扩展名，以及它们属于哪一层架构。有效类型：`component`、`page`、`hook`、`service`、`adapter`、`context`、`store`、`dto`、`type` |
| `routeFiles` | 路由解析的入口点（React Router 或 Vue Router）。Next.js / Nuxt 基于文件的路由将自动发现这些文件 |
| `aliases` | 路径别名，以便服务器可以解析像 `@/components/Button` 这样的导入 |
| `exclude` | 要跳过的 glob 模式 |
| `phiCompliance` | `{ "enabled": true }` 开启 PHI/HIPAA 启发式算法（查询缓存设置，console.log 接近患者数据，web-storage 使用）。默认关闭 - 非医疗项目获得零 PHI 噪音 |
### 框架默认值
**React** - 扫描 `src/components` (.tsx)、`src/pages` (.tsx)、`src/hooks` (.ts/.tsx)、`src/services` (.ts)、`src/adapters` (.ts)、`src/contexts` (.tsx)、`src/stores` + `src/store` (.ts)。路由来自 `src/App.tsx`，以及 Next.js `app/`/`pages/` 文件路由，当 `next` 是依赖项时。
**Vue** - 扫描 `src/components` (.vue)、`src/views` + `src/pages` (.vue)、`src/composables` (.ts)、`src/services` (.ts)、`src/adapters` (.ts)、`src/stores` + `src/store` (.ts)。路由来自 `src/router/index.ts`，以及 Nuxt `pages/` 文件路由，当 `nuxt` 是依赖项时。
## 工具
### `list_all_components`
紧凑的目录列表： `{ totalCount, lastScanned, byLayer, components }` 其中每个条目都是一个摘要（名称、层、类别、路径、描述、路由）。使用 `layer` 进行筛选；传递 `verbose: true` 以获取完整的元数据对象。
### `search_components`
对整个代码库按名称、路径或关键词进行模糊搜索。多令牌评分，按相关性排名。返回带有 `_score` 的紧凑摘要；`limit` 限制结果（默认为 20）。
### `get_component_props`
返回组件的 TypeScript 属性接口 - 属性名称、类型、必填/可选、默认值和 JSDoc 描述。接受目录 `name` 或 `componentPath`；失败返回 `{ error }` 以及原因。
### `find_similar_components`
用普通英语描述您要找的东西，它会使用关键词 + 结构匹配（使用的钩子、子组件、数据获取模式、层）查找匹配的组件。返回紧凑的摘要。
### `get_component_detail`
任何项目的完整元数据转储 - 属性、钩子、状态、子项、事件处理程序、数据获取、`testIds` 和 `formFields`（用于 `capture_flow` 的可驱动选择器）、可访问性信息、API 端点、架构层。
### `find_component_usages`
查找组件/钩子/服务被导入或渲染的所有位置。返回文件、父组件和行号。还扫描入口点（`App.tsx`、`main.tsx`、布局）和位于扫描目标之外的路由文件。适合在进行更改前的冲击分析。
### `whats_affected`
编辑→验证的胶水。给它更改的文件（或让它读取 `git status`），它会遍历依赖图上游到每个受影响的组件和页面，将它们映射到路由，并返回具体的 `check_page` / `render_component` 建议。编辑 → `whats_affected` → 精确检查哪些内容。
### `get_architecture_overview`
整个应用程序的高级视图 - 按层分类的计数、类别分解、数据流链和路由图。
### `get_dependency_chain`
跟踪任何项目的上游（什么使用它）和下游（它依赖于什么）。支持递归深度 1-3。
### `get_route_map`
完整的路由 → 页面 → 组件映射，包含保护状态、使用的钩子、子组件、动态段和嵌套路由。涵盖 React Router、Vue Router 和基于文件的路由（Next.js App/Pages Router、Nuxt）。
### `get_hook_detail`
深入了解钩子/组合函数 - 参数、返回类型、查询键、适配器调用、数据获取模式以及哪些组件使用它。
### `find_dead_code`
查找从未被任何地方导入的已导出项目。按层可选筛选。仅从入口点或路由文件引用的组件被正确视为活动。
### `get_data_flow`
跟踪完整的数据路径：组件 → 组合函数/钩子/存储 → 服务 → 适配器 → API 端点 - **包括子组件获取的端点**（页面很少自己获取所有内容）。存储介导的流（Pinia/Zustand）在每个链中显示为 `stores` 步骤。遍历子渲染树（以 `depth` 为界，默认为 3，加上循环保护）。每个链都用到达它的 `via` 渲染路径标记，并且 `allEndpoints` 给出渲染路由命中的一切的并集。节省您手动链接 `get_component_detail` + `get_hook_detail` 调用。
> **名称冲突：** `get_component_detail`、`get_component_props`、`get_hook_detail`、`get_dependency_chain` 和 `get_data_flow` 在名称与多个文件匹配时返回 `{ ambiguous: true, candidates: [...] }`。不要沉默地选择一个，而是自动调用带有 `file`（路径子字符串）以消歧义。
## 运行时浏览器工具 - 让代理检查他们的工作
上述工具静态地理解您的代码。这些工具中有五个驱动一个真正的（无头）浏览器针对您的**正在运行的应用程序**，因此代理可以看到更改的结果而不是猜测。它们重用静态目录 - 路由图自动将组件解析为其 URL，因此您命名更改的组件，浏览器知道去哪里。
由 Playwright/Chromium 提供支持。它们需要您的开发服务器正在运行，并且可以优雅地降级 - 即使没有安装浏览器二进制文件，静态工具也可以正常工作。
### `render_component`
在实时应用中渲染目录组件并返回**截图和运行时诊断**（控制台错误、未捕获的异常、失败的网络请求）。通过路由图解析 `component` → URL；或传递原始 `route`。传递 `params` 以获取动态段（例如 `{"id": "123"}`）。截图作为图像返回，代理可以查看。
### `check_page`
"我的更改是否破坏了任何东西"的得力助手。导航到任何 `url`（绝对路径，或相对于开发服务器的路径）并获取截图 + 控制台错误 + 未捕获的异常 + 失败的网络调用。编辑后调用它以确认页面仍然渲染干净。
### `verify_data_flow`
源代码与运行时检查。渲染组件的路由，监视**实际网络流量**，并根据 `get_data_flow` 预测的端点进行检查（包括子树）。匹配是方法感知的 - 预测的 `GET /users` 不再确认观察到的 `DELETE /users`。关键输出是 **`unexpectedApiCalls`** - 观察到的调用映射到 *没有* 预测的端点。这是真正的漂移信号：动态/模板文字 URL、应用级引导获取超出组件树，或真正的差异。`verdict` 为 `confirmed` 时，观察到的所有调用都已核算。（预测但未观察到的端点是预期的 - 渲染只执行子树的一小部分，因此那些被报告为计数，而不是列表。）
传递 `actions`（与 `capture_flow` 操作的形状相同）在加载后驱动页面并在读取网络之前 - 填写表单，单击保存，并验证下一个屏幕作为一个流程。无操作时，仅渲染时调用（通常为 GET）是可观察的。
### `inspect_rendered_page`
反向桥。打开一个实时页面并报告哪些**目录组件实际上已安装**到它上面，映射回源文件 - “我编辑什么来改变我正在查看的内容？”无需 grep。通过遍历 React/Vue 开发内部实现，因此它需要开发版本（而非生产版本）。接受目录 `component`、`route` 或原始 `url`；返回 `{ framework, mounted: [{name, count, relativePath, architectureLayer}], unmatched }`，纯文本。
### `capture_flow`
驱动一个**单个持久页面**的多步骤用户流，并对每一步都截图。一步可以导航（`component`/`route`/`url`）和/或运行**交互** - 因此代理可以登录、填写表单、提交并验证下一个屏幕作为一个流程。页面状态（cookie、表单值、SPA 路由）在步骤之间传递。每个步骤报告它触发的 **API 调用**（`{method, path, status}`），因此“单击 Save 实际 POST？” 在同一个调用中得到答案。聚合诊断信息到单个通过/失败；在失败的操作上截图失败状态并停止。
提示：`get_component_detail` 暴露每个组件的 `testIds` 和 `formFields`（带有现成的选择器） - 从那里构建您的步骤，而不是阅读源代码。
每个步骤的 `actions` 按顺序运行。支持的操作类型：`click`、`fill`、`select`、`check`、`uncheck`、`hover`、`press`、`waitFor`。选择器接受 CSS 或 Playwright 引擎（`#email`、`text=Submit`、`role=button[name="Save"]`）。`fill`/`select` 使用 `text`；`press` 使用 `key`。
**自动优先显示匹配项**。响应式布局通常会两次渲染相同的控件（桌面和隐藏的移动变体），操作和 `waitFor` 目标是选择器匹配的第一个**可见**匹配项，因此隐藏的副本永远不会固定点击或等待超时，并且不需要 `:visible` 后缀。如果每个匹配项都保持隐藏，超时错误会显示它（`N match(es) but none visible`）而不是出现通用重试日志。这适用于所有操作运行程序：`capture_flow` 步骤、`verify_data_flow` 操作以及 `browser.login` 预步骤。
```jsonc
{
"steps": [
{ "label": "open login", "route": "/login" },
{ "label": "sign in", "actions": [
{ "type": "fill", "selector": "#email", "text": "${APP_EMAIL}" },
{ "type": "fill", "selector": "#password", "text": "${APP_PASSWORD}" },
{ "type": "click", "selector": "button[type=submit]" },
{ "type": "waitFor", "selector": "#dashboard" },
]},
{ "label": "verify dashboard", "component": "Dashboard" }
]
}
```
填写的值按长度报告，而不是内容，因此密码/令牌不会泄露到转录中。
### 浏览器配置
在 `.atlas-ui.json` 中添加 `browser` 块（所有字段可选 - 这些是默认值）：```json
{
"browser": {
"devServerUrl": "http://localhost:5173",
"headless": true,
"viewport": { "width": 1280, "height": 800 },
"outputDir": ".atlas-ui/captures",
"routeParams": { "id": "1" }
}
}
```
| 字段 | 它做什么 |
|-------|-------------|
| `devServerUrl` | 运行应用程序的基 URL。MCP 假设开发服务器已经启动。 |
| `headless` | 运行 Chromium 无头（默认 `true`）。设置为 `false` 以观看。 |
| `viewport` | 截图尺寸。 |
| `outputDir` | 写入截图/视频的位置（相对于您的项目，git-ignored）。 |
| `routeParams` | 动态路由段的默认值；每个调用的 `params` 覆盖它们。 |
首次设置下载浏览器二进制文件：```bash
npx playwright install chromium
### 登录预步骤（身份验证路由）
如果您的应用程序后面有登录，请添加 `login` 块。会话 **一次** 在首次浏览器使用时进行身份验证，并且因为每个工具都共享一个页面，因此该会话在所有调用中持续存在。 **将凭证放入 env vars** 并引用它们 `${VAR}`；永远不要内联机密配置（配置被提交）。
```jsonc
{
"browser": {
"devServerUrl": "http://localhost:5173",
"login": {
"url": "/login",
"url": "/login",
"actions": [
{ "type": "fill", "selector": "#email", "text": "${APP_EMAIL}" },
{ "type": "fill", "selector": "#password", "text": "${APP_PASSWORD}" },
{ "type": "click", "selector": "button[type=submit]" }
],
"successSelector": "text=Logout"
}
}
}
```
| 字段 | 它做什么 |
|-------|-------------|
| `url` | 登录表单的位置（绝对或相对于开发服务器）。 |
| `actions` | 与 `capture_flow` 相同的操作类型 (`fill`, `click`, …)。`text` 支持 `${ENV_VAR}`。 |
| `successSelector` | 等待它以确认登录成功（例如，“注销”链接）。 |
| `successUrlIncludes` | 或确认 URL 已更改为包含此子字符串。 |
env 变量必须对 MCP 服务器进程可见（在您的 `mcp.json` 服务器条目中设置 `env` 块）。登录失败时，会拆除会话，下一次调用会重试，而不是默默地运行未经身份验证。填写的值按长度报告，因此凭证永远不会出现在工具输出中。
> **SPA 注意：** 所有浏览器工具共享一个页面，因此应用内/会话存储的身份验证在导航期间存活下来。如果您的应用将令牌存储在 `sessionStorage` 中（常见），则每个页面方法都会丢失它 - 共享页面是使登录预步骤粘在一起的原因。
## License
[MIT](LICENSE) - 免费用于任何用途、修改和重新分发。欢迎贡献。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器