# Atlas UI

MCP server that gives Claude deep awareness of your frontend codebase — components, hooks, services, routes, data flow, the whole thing. Point it at a React or Vue project and it builds a catalog that Claude can query while it works.

## TLDR: Quick Start

1. **Configure VS Code** (via your MCP extension settings, e.g. `.vscode/mcp.json`):
   ```json
   {
     "mcpServers": {
       "atlas-ui": {
         "command": "node",
         "args": ["/absolute/path/to/atlas-ui/dist/server.js"],
         "env": {
           "WORKSPACE_ROOT": "/absolute/path/to/your/target/project"
         }
       }
     }
   }
   ```
2. **Restart VS Code and try these prompts:**
   - *"List all the components in my project."* (`list_all_components`)
   - *"What are the props for the Button component?"* (`get_component_props`)
   - *"Show me the data flow for the UserProfile component."* (`get_data_flow`)
   - *"Are there any dead components we can delete?"* (`find_dead_code`)

## What it does

Instead of Claude grep-ing around your codebase every time it needs to understand how things fit together, this server scans your project up front and exposes a set of tools for navigating the architecture. It understands:

- **Components, pages, hooks, services, adapters, contexts, stores** — categorized by architecture layer (stores cover Pinia, Zustand, and Redux Toolkit)
- **Props and interfaces** — parsed from TypeScript definitions
- **Dependency chains** — what uses what, upstream and downstream
- **Route maps** — React Router and Vue Router, plus file-based routing (Next.js App/Pages Router, Nuxt), including protected routes and nested layouts
- **Data flow** — traces the full path from component → hook/store → service → adapter → API endpoint
- **Dead code** — finds exported items that nothing imports (entry points like `App.tsx`/`main.tsx` count as usage, so root-mounted components aren't false-flagged)
- **Drivable selectors** — each component's `data-testid` values and form fields with ready-to-use selectors, so flows can be scripted without reading source

It auto-detects whether your project is React, Vue and sets up sensible scan targets accordingly. File watching keeps the cache fresh as you work.

Catalog-wide listings and search results return compact summaries to keep token cost down; `get_component_detail` has the full metadata, and `list_all_components` accepts `verbose: true` when you really want everything. When a name matches multiple files, name-based tools return an `ambiguous` result with candidates instead of guessing — re-call with `file` (a path substring) to pick one.

## Setup

**From npm** (no clone needed):

```bash
npx atlas-ui-mcp /path/to/your/app
```

or in an MCP config, `"command": "npx", "args": ["-y", "atlas-ui-mcp", "/path/to/your/app"]`.

**From source:**

```bash
npm install
npm run build
```

### Claude Code

Add to your project's `.mcp.json` (or `~/.claude/mcp.json` for global):

```json
{
  "mcpServers": {
    "atlas-ui": {
      "command": "node",
      "args": ["/path/to/atlas-ui/dist/server.js"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}
```

### Claude Desktop

**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` tells the server where your project lives. You can also pass it as a CLI arg (`node dist/server.js /path/to/project`). If neither is set, it defaults to two directories up from the server because that's where mine lives. Feel free to update if you have a common folder for MCPs.

## Configuration

Drop a `.atlas-ui.json` in your project root to customize scanning. If you don't create one, the server auto-detects your framework and uses defaults based on what it finds.

```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.*"]
}
```

| Field | What it does |
|-------|-------------|
| `scanTargets` | Directories to scan, what extensions to look for, and what architecture layer they belong to. Valid types: `component`, `page`, `hook`, `service`, `adapter`, `context`, `store`, `dto`, `type` |
| `routeFiles` | Entry points for route parsing (React Router or Vue Router). Next.js / Nuxt file-based routes are discovered automatically alongside these |
| `aliases` | Path aliases so the server can resolve imports like `@/components/Button` |
| `exclude` | Glob patterns to skip |
| `phiCompliance` | `{ "enabled": true }` turns on PHI/HIPAA heuristics (query cache settings, console.log near patient data, web-storage use). Off by default — non-healthcare projects get zero PHI noise |

### Defaults by framework

**React** — scans `src/components` (.tsx), `src/pages` (.tsx), `src/hooks` (.ts/.tsx), `src/services` (.ts), `src/adapters` (.ts), `src/contexts` (.tsx), `src/stores` + `src/store` (.ts). Routes from `src/App.tsx`, plus Next.js `app/`/`pages/` file routes when `next` is a dependency.

**Next.js** (when `next` is a dependency) — the React defaults widen to the layouts Next sanctions: shared code colocated inside the App Router dir (`app/`- and `src/app/`-nested `components`, `hooks`, `contexts`, `providers`, `services`, `lib`, `stores`), the `src`-level `src/lib` + `src/providers`, and root-level dirs next to `app/` or `pages/` (`components`, `hooks`, `lib`, `pages`, ...). Directories that don't exist are skipped, so this costs nothing on plain `src/*` layouts.

**Vue** — scans `src/components` (.vue), `src/views` + `src/pages` (.vue), `src/composables` (.ts), `src/services` (.ts), `src/adapters` (.ts), `src/stores` + `src/store` (.ts). Routes from `src/router/index.ts`, plus Nuxt `pages/` file routes when `nuxt` is a dependency.

**Nuxt** (when `nuxt` is a dependency) — the Vue defaults widen to Nuxt's root-level dirs (`components`, `layouts`, `pages`, `composables`, `stores`, `utils`) and their Nuxt 4 `app/`-nested equivalents.

### Scan coverage warning

Layout conventions are unbounded, so no default list can cover them all — but a scan that misses the app should say so instead of returning a near-empty catalog that reads as "this app has no components". After every scan, the server checks for UI source files (`.tsx`/`.jsx`/`.vue`) that no scan target covers. When the misses outweigh the catalog (or the catalog is empty), `list_all_components` and `get_architecture_overview` include a `coverageWarning` naming the heaviest uncovered directories, so the fix is a copy-paste `scanTargets` entry in `.atlas-ui.json`. Files owned by file-based routing (Next App Router special files, `pages/` routes) don't count as missed.

## Tools

### `list_all_components`
Compact catalog listing: `{ totalCount, lastScanned, byLayer, components }` where each entry is a summary (name, layer, category, path, description, route). Filter with `layer`; pass `verbose: true` for full metadata objects.

### `search_components`
Fuzzy search across the whole codebase by name, path, or keywords. Multi-token scoring, ranked by relevance. Returns compact summaries with `_score`; `limit` caps results (default 20).

### `get_component_props`
Returns the TypeScript prop interface for a component — prop names, types, required/optional, defaults, and JSDoc descriptions. Accepts a catalog `name` or a `componentPath`; failures come back as `{ error }` with the reason.

### `find_similar_components`
Describe what you're looking for in plain English and it finds matching components using keyword + structural matching (hooks used, child components, data fetching patterns, layer). Returns compact summaries.

### `compare_implementations`
The reuse **guardrail**. `find_similar_components` / `search_components` score on structural metadata, so they rank near-duplicates to the top — exactly the ones whose subtle behavioral differences matter most — with no signal that the bodies diverge. Before unifying two look-alikes, this tool compares them at **sub-file granularity** and tells you whether that's safe.

Give it two symbol references `{ file, symbol, enclosingSymbol? }`. Each resolves a function, arrow, class/static method, object getter/method, or a `computed()` / `useMemo()` / `useCallback()` (compared by its callback body). It normalizes away comments, formatting, quote style, numeric form, and semicolon/trailing-comma noise, then diffs the token streams and returns:

- `verdict` — `equivalent` (byte-equal after normalization → safe to unify) or `diverges`
- `divergences[]` — each classified (`literal`, `callee-changed`, `guard-changed`, `operator-changed`, `added-block`, `removed-block`, `changed`) with the original source snippet on each side and file line spans (`locA` / `locB`)

Works for **both Vue and React** off the same engine — a `.vue` `<script>` is extracted to TS and its lines mapped back, so a Vue composable/computed and a React hook/memo compare on equal footing (you can even compare one against the other). `b.file` may be omitted to compare two symbols in the same file. Identifiers and type annotations are preserved (no alpha-renaming); Options-API `this.x` vs composable `x.value` access styles are not normalized in v1.

### `get_component_detail`
Full metadata dump for any item — props, hooks, state, children, event handlers, data fetching, `testIds` and `formFields` (drivable selectors for `capture_flow`), accessibility info, API endpoints, architecture layer.

### `find_component_usages`
Find everywhere a component/hook/service is imported or rendered. Returns files, parent components, and line numbers. Also scans entry points (`App.tsx`, `main.tsx`, layouts) and route files that live outside scan targets. Good for impact analysis before making changes.

### `whats_affected`
The edit→verify glue. Give it changed files (or let it read `git status`) and it walks the dependency graph upstream to every affected component and page, maps those to routes, and returns concrete `check_page` / `render_component` suggestions. Edit → `whats_affected` → check exactly what matters.

### `get_architecture_overview`
High-level view of the whole app — counts by layer, category breakdown, data flow chains, and the route map.

### `get_dependency_chain`
Traces upstream (what uses it) and downstream (what it depends on) for any item. Supports recursive depth 1-3.

### `get_route_map`
Full route → page → component mapping with protection status, hooks used, child components, dynamic segments, and nested routes. Covers React Router, Vue Router, and file-based routing (Next.js App/Pages Router, Nuxt).

### `get_section_map`
The companion to `get_route_map` for SPAs that multiplex **one route** into several in-app sections — a role shell / tabbed page / sidebar switch where the lists are section switches, not routes (so `get_route_map` can't point at them). For each routed page (and each page/root shell) it detects a **view multiplexer**: a single state variable gating sibling sub-views. Works for both frameworks off their own constructs — Vue `v-if="view === 'x'"` + `@click="view = 'x'"`, React `{tab === 'x' && <X/>}` + `onClick={() => setTab('x')}` — never off app-specific names.

Returns `{ containers, note? }`. Each container carries its `route` (when routed), its `selector` (the state variable), and `sections[]`. Each section has:
- `id` — the literal the selector takes for this section (e.g. `"prescriptions"`)
- `child` — the component rendered for it
- `reachedBy` — `query` (the view syncs to a URL param), `click` (a control switches it), or `unknown` (statically unprovable — e.g. a store/reducer or non-literal condition; drive the UI to explore)
- `queryParam` — `{ key, value }` when URL-reachable
- `activator` — `{ selector, label }`, the drivable control that switches to the section (a `[data-testid]` or `text=` selector), when statically identifiable

`note` (present only on an empty result) explains why nothing was found. A fully route-based app returns no containers — this tool adds signal exactly where the route map goes quiet.

**Driving to a section.** The runtime tools consume this map so you don't have to wire the click yourself. `render_component`, `verify_data_flow`, `inspect_rendered_page`, and each `capture_flow` step take a `section` argument (or you can just name the section's `child` component) — the tool navigates to the container's route and then reveals the section automatically: it appends the query param for a `query` section, or clicks the `activator` for a `click` section, *before* it screenshots and reads the network. So a section's own render, console, and API calls (with Phase-1 row counts) are what get captured — no guessed sidebar clicks.

### `get_hook_detail`
Deep dive on a hook/composable — parameters, return type, query keys, adapter calls, data fetching pattern, and which components use it.

### `find_dead_code`
Finds exported items that are never imported anywhere. Optionally filter by layer. Components referenced only from entry points or route files are correctly treated as live.

### `get_data_flow`
Traces the full data path: component → composable/hook/store → service → adapter → API endpoint — **including endpoints fetched by child components** (a page rarely fetches everything itself). Store-mediated flows (Pinia/Zustand) surface in a `stores` step per chain. Walks the child render tree (bounded by `depth`, default 3, plus a cycle-guard). Each chain is tagged with the `via` render path that reached it, and `allEndpoints` gives the union of everything the rendered route hits. Saves you from manually chaining `get_component_detail` + `get_hook_detail` calls.

> **Name collisions:** `get_component_detail`, `get_component_props`, `get_hook_detail`, `get_dependency_chain`, and `get_data_flow` return `{ ambiguous: true, candidates: [...] }` when a name matches multiple files. Instead of silently picking one, automatically re-calls with `file` (a path substring) to disambiguate.

## Runtime browser tools — let agents check their work

The tools above understand your code statically. These five drive a real (headless) browser against your **running app**, so an agent can *see* the result of a change instead of guessing. They reuse the static catalog — the route map resolves a component to its URL automatically, so you name the component you changed and the browser knows where to go.

Powered by Playwright/Chromium. They require your dev server to be running and degrade gracefully — the static tools work even if the browser binaries aren't installed.

### `render_component`
Render a catalog component in the live app and return a **screenshot plus runtime diagnostics** (console errors, uncaught exceptions, failed network requests). Resolves `component` → URL via the route map; or pass a raw `route`. Pass `params` for dynamic segments (e.g. `{"id": "123"}`). The screenshot comes back as an image the agent can look at. For a component that lives inside a one-route shell, pass `section` (see `get_section_map`) — or just name the section's child `component` — and it auto-reveals that section (query-append or activator click) before the shot, reporting how under `viewSection`.

### `check_page`
The "did my change break anything" workhorse. Navigate to any `url` (absolute, or a path relative to the dev server) and get back a screenshot + console errors + uncaught exceptions + failed network calls. Call it after an edit to confirm the page still renders clean.

### `verify_data_flow`
Source-vs-runtime check. Renders a component's route, watches the **real network traffic**, and checks it against the endpoints `get_data_flow` predicts (child tree and stores included). Matching is method-aware — a predicted `GET /users` no longer "confirms" an observed `DELETE /users`. The key output is **`unexpectedApiCalls`** — observed calls that map to *no* predicted endpoint. That's the real drift signal: dynamic/template-literal URLs, app-level bootstrap fetches outside the component's tree, or genuine divergence. `verdict` is `confirmed` when every observed call is accounted for. (Predicted-but-unobserved endpoints are expected — a render exercises only a slice of what the subtree *could* call — so those are reported as a count, not a list.) Each observed call (matched or unexpected) also carries the response-body summary — `bytes`, `rowCount`, `rowsFrom`, `totalCount` — so drift and payload-shape can be read from one result.

Pass `actions` (same shape as `capture_flow` actions) to drive the page after load and before the network is read — fill the form, click Save, and the resulting `POST` gets verified too. Without actions, only render-time calls (typically GETs) are observable.

### `inspect_rendered_page`
The reverse bridge. Opens a live page and reports which **catalog components are actually mounted** on it, mapped back to source files — "what do I edit to change the thing I'm looking at?" without grepping. Works by walking React/Vue dev internals, so it needs the dev build (not prod). Takes a catalog `component`, a `route`, or a raw `url`; returns `{ framework, mounted: [{name, count, relativePath, architectureLayer}], unmatched }`, text-only.

### `capture_flow`
Drive a multi-step user flow against a **single persistent page** and screenshot each step. A step can navigate (`component`/`route`/`url`) and/or run **interactions** — so an agent can log in, fill a form, submit, and verify the next screen as one flow. Page state (cookies, form values, SPA route) carries across steps. Each step reports the **API calls it triggered** (`{method, path, status, bytes, rowCount, rowsFrom, totalCount}`), so "did clicking Save actually POST?" *and* "how many rows did that list return?" are answered in the same call. Aggregates diagnostics into a single pass/fail; on a failed action it screenshots the broken state and stops.

> **Response-body summary:** for JSON API responses, each call also carries a payload summary alongside `{method, path, status}` — `bytes` (response size), `rowCount` (rows in the primary collection), `rowsFrom` (which JSON key was counted: `$` for a top-level array, or a key path like `data` / `data.items`), and `totalCount` (a server-reported pagination total, when the body has one). Count-level assertions — "the projects call returned 1578 scoped rows" — no longer need a drop to `curl`. The row heuristic is framework- and app-agnostic: it counts a top-level array, a well-known envelope key (`data`/`results`/`items`/`records`/`content`/`edges`/…), or an object's sole array property, and always reports `rowsFrom` so a wrong guess is visible rather than silent. Bodies are read only for xhr/fetch or `/api/` responses, and only their shape — never their contents — is reported.

Tip: `get_component_detail` exposes each component's `testIds` and `formFields` (with ready-made selectors) — build your steps from those instead of reading source.

Each step's `actions` run in order. Supported action `type`s: `click`, `fill`, `select`, `check`, `uncheck`, `hover`, `press`, `waitFor`. Selectors accept CSS or Playwright engines (`#email`, `text=Submit`, `role=button[name="Save"]`). `fill`/`select` use `text`; `press` uses `key`.

**Visible matches are preferred automatically.** Responsive layouts often render the same control twice (a desktop and a hidden mobile variant); actions and `waitFor` target the first *visible* match of the selector, so hidden duplicates never pin a click or wait until timeout, and no `:visible` suffix is needed. If every match stays hidden, the timeout error says so (`N match(es) but none visible`) instead of surfacing a generic retry log. This applies to all action runners: `capture_flow` steps, `verify_data_flow` actions, and the `browser.login` pre-step.

```jsonc
{
  "steps": [
    { "label": "open login", "route": "/login" },
    { "label": "sign in", "actions": [
      { "type": "fill", "selector": "#email", "text": "demo@acme.dev" },
      { "type": "fill", "selector": "#password", "text": "••••••" },
      { "type": "click", "selector": "text=Log in" },
      { "type": "waitFor", "selector": "#dashboard" }
    ]},
    { "label": "verify dashboard", "component": "Dashboard" }
  ]
}
```

Filled values are reported by length, not content, so passwords/tokens don't leak into the transcript.

### Browser configuration

Add a `browser` block to `.atlas-ui.json` (all fields optional — these are the defaults):

```json
{
  "browser": {
    "devServerUrl": "http://localhost:5173",
    "headless": true,
    "viewport": { "width": 1280, "height": 800 },
    "outputDir": ".atlas-ui/captures",
    "routeParams": { "id": "1" }
  }
}
```

| Field | What it does |
|-------|-------------|
| `devServerUrl` | Base URL of your running app. The MCP assumes the dev server is already up. |
| `headless` | Run Chromium headless (default `true`). Set `false` to watch it drive. |
| `viewport` | Screenshot dimensions. |
| `outputDir` | Where screenshots/videos are written (relative to your project, git-ignored). |
| `routeParams` | Default values for dynamic route segments; per-call `params` override them. |

First-time setup downloads the browser binary:

```bash
npx playwright install chromium
```

### Login pre-step (authenticated routes)

If your app is behind a login, add a `login` block. The session authenticates **once** on first browser use, and because every tool shares a single page, that session persists across all calls — so protected routes render logged-in. Put **credentials in env vars** and reference them with `${VAR}`; never inline secrets (the config is committed).

```jsonc
{
  "browser": {
    "devServerUrl": "http://localhost:5173",
    "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"
    }
  }
}
```

| Field | What it does |
|-------|-------------|
| `url` | Where the login form lives (absolute or dev-server-relative). |
| `actions` | The same action types as `capture_flow` (`fill`, `click`, …). `text` supports `${ENV_VAR}`. |
| `successSelector` | Wait for this to confirm login succeeded (e.g. a "Logout" link). |
| `successUrlIncludes` | Or confirm the URL changed to include this substring. |

The env vars must be visible to the MCP server process (set them in the `env` block of your `mcp.json` server entry). On login failure the session tears down and the next call retries, rather than silently running unauthenticated. Filled values are reported by length, so credentials never appear in tool output.

> **SPA note:** all browser tools share one page so in-app/session-storage auth survives navigation. If your app stores its token in `sessionStorage` (common), a per-page approach would lose it — sharing the page is what makes the login pre-step stick.

## License

[MIT](LICENSE) — free for any use, modification, and redistribution. Contributions welcome.