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):

   {
     "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):

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:

npm install
npm run build

Claude Code

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

{
  "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

{
  "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.

{
  "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 types: 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.

{
  "steps": [
    { "label": "open login", "route": "/login" },
    { "label": "sign in", "actions": [
      { "type": "fill", "selector": "#email", "text": "[email protected]" },
      { "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):

{
  "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:

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).

{
  "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 — free for any use, modification, and redistribution. Contributions welcome.