Ui To Hierarchy

npm version

MCP (Model Context Protocol) server that parses a Next.js App Router project and returns its UI component hierarchy as structured output (markdown tree + JSON), so AI coding agents can ground image/description-based UI edits in exact file/component locations.

When an AI agent cannot confidently act on a screenshot or vague description ("make the card next to the avatar wider"), it can call this MCP to get a precise, structured map of the live component tree — with file:line, layout hints, text content, and conditional branches — so the agent edits the right component in the right file instead of guessing.

Status

Targets Next.js App Router. Static analysis only — no runtime execution, no DOM, no rendering.

Requirements

• Node.js >=20
• An MCP-capable client (Claude Code, Claude Desktop, Cursor, or MCP Inspector)

Run

No install step is needed when used as an MCP server — clients spawn the binary on demand via npx. The three common ways to run it:

1. Via an MCP client (normal usage)

Add the server to your client config (see Use with an MCP client below). The client launches npx -y ui-hierarchy-mcp for you and speaks JSON-RPC over stdio.

2. Standalone for debugging

npx -y ui-hierarchy-mcp

The process speaks JSON-RPC on stdio, so it will sit idle waiting for a client. Useful only to confirm the binary downloads and launches; press Ctrl+C to exit.

3. Interactive UI (MCP Inspector)

npx @modelcontextprotocol/inspector npx -y ui-hierarchy-mcp

Opens a local web UI where you can list and invoke each tool against a real project — the fastest way to explore the output format without wiring up an AI client.

Pointing at a project

Every tool accepts a projectRoot argument (absolute path). To set a default for all calls, export UI_TO_HIERARCH_ROOT before launching the client:

export UI_TO_HIERARCH_ROOT=/abs/path/to/your/nextjs/project

If neither is set, the server falls back to process.cwd() — usually the directory the MCP client was launched from.

Use with an MCP client

Claude Code / Claude Desktop

Add to ~/.claude.json (or per-project .mcp.json):

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

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json per project):

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

Onboard your agent (--init)

Inject a usage guide for ui-hierarchy-mcp into your project's agent instruction files in one command:

npx -y ui-hierarchy-mcp --init

By default this writes a marker block into CLAUDE.md (created if absent) containing the four tool descriptions, a registration snippet, and example calls. Re-running the command is a no-op when the block is already current — safe to wire into CI or repo bootstrap scripts.

Targets

Pick one or more agent instruction surfaces via --target (comma-separated):

Target	File written
claude (default)	CLAUDE.md
codex	AGENTS.md
cursor	.cursor/rules/ui-hierarchy-mcp.mdc (with YAML frontmatter)
copilot	.github/copilot-instructions.md

# Onboard all four agents at once
npx -y ui-hierarchy-mcp --init --target claude,codex,cursor,copilot

Missing parent directories are created automatically.

Flags

• --dry-run — print a per-target plan (would create / would update / would skip) to stderr, write nothing.
• --force — overwrite the marker block even if it has been hand-edited (otherwise the target is skipped with a warning).

--init is fully argv-driven (no prompts) and safe in CI. Running npx ui-hierarchy-mcp without --init still starts the MCP stdio server unchanged.

Tools

All tools accept an optional projectRoot (absolute path) — defaults to UI_TO_HIERARCH_ROOT env var, then process.cwd().

Tool	Purpose
get_full_hierarchy	Returns the ordered layout chain and page component subtree for a Next.js App Router route.
focus_on	Returns the component subtree rooted at a named JSX component, optionally including ancestors.
find_by_text	Finds component nodes whose rendered text content matches a query string. Returns nodes with file:line location.
find_by_style	Finds component nodes that use a given CSS class name or style prop. Returns nodes with file:line location.

Example — get_full_hierarchy

{
  "route": "/dashboard/123",
  "format": "json",
  "projectRoot": "/abs/path/to/your/nextjs/project"
}

route must be a valid Next.js App Router path (start with /, no trailing slash except root). Dynamic segments like [slug], [...rest], [[...optional]] are supported.

Example — focus_on

{
  "component": "DashboardDetail",
  "scope": "full",
  "projectRoot": "/abs/path/to/your/nextjs/project"
}

scope: "up" (ancestors only), "full" (ancestors + subtree, default), or "down" (subtree only).

Example — find_by_text

{
  "query": "Sidebar slot",
  "projectRoot": "/abs/path/to/your/nextjs/project"
}

Example — find_by_style

{
  "class_or_prop": "grid-cols-3",
  "projectRoot": "/abs/path/to/your/nextjs/project"
}

Tech

• TypeScript + @modelcontextprotocol/sdk v1.29
• @babel/parser + @babel/traverse for JSX/TSX AST analysis
• get-tsconfig for tsconfig path-alias resolution
• tinyglobby for file discovery
• ESM-only, Node >=20

Development

Clone and work on the server itself:

git clone https://github.com/dovanhuy2298/ui-to-hierarchy.git
cd ui-to-hierarchy
pnpm install

Common scripts:

Script	Purpose
pnpm dev	Run the CLI directly from TypeScript source (tsx src/cli.ts). Pass args after --, e.g. pnpm dev -- --init --dry-run.
pnpm build	Bundle to dist/ via tsup (ESM, with shebang).
pnpm test	Run the full Vitest suite.
pnpm test:watch	Watch mode.
pnpm test:smoke	Spawn-the-binary smoke test against the MCP stdio contract.
pnpm test:integration	Integration suite against fixture Next.js projects.
pnpm typecheck	tsc --noEmit.
pnpm lint	biome check ..

To test a local build against an MCP client, point its command at the built binary:

{
  "mcpServers": {
    "ui-hierarchy": {
      "command": "node",
      "args": ["/abs/path/to/ui-to-hierarchy/dist/cli.js"]
    }
  }
}

Roadmap

V1 covers Next.js App Router. Internal architecture is pluggable so additional framework parsers (React Native, Vue, Svelte) can be added later without rewriting the core. Caching, watch mode, and HTTP transport are explicitly deferred.

License

MIT © huydv98