astro-inspector

Click a UI element in your Astro dev server. Your AI agent gets the exact source file, line, and column.

No browser extension. No editor-specific deep links. Copy an MCP-resolvable hash or a compact source reference straight from the page.

Demo

Related MCP server: Carto MCP Server

Why

Telling an AI agent "fix the padding on the card in the pricing section" makes it guess. It greps, it opens the wrong file, it edits a component that renders somewhere else entirely.

astro-inspector removes the guessing. You point at the pixel. The agent gets the line.

You: [pastes astro_hash_0123456789abcdef01234567] make this card's padding tighter

Agent: → get_astro_element_by_hash
       src/components/PricingCard.astro:24:5  <div> → <div>
       ...edits the right file on the first try

Install

Requires Node.js ≥ 22.12 and Astro ≥ 6.2.2, < 8.

npm install --save-dev astro-inspector

Add the integration:

// astro.config.mjs
import { defineConfig } from "astro/config";
import { astroInspector } from "astro-inspector";

export default defineConfig({
  integrations: [astroInspector()]
});

Ignore the runtime manifest in your project:

# .gitignore
.astro-ai-locator/

Usage

Run astro dev, then:

The hover label

The current target shows a label in the form:

<SourceTag→DomTag> │ FileName.astro │ line:column

The filename keeps its extension, and the arrow is omitted when the source tag and the rendered DOM tag are identical. The full project-relative path is preserved in the DOM metadata, the manifest, and the MCP response. Labels prefer to sit above the target. They use the space below when the label does not fit above but does fit below; if neither side fits, they choose the side with more available space. The result is then clamped to an 8px viewport inset on every edge. The 640px maximum width and ellipsis keep long source names readable without overflowing the screen.

Copy feedback

After a successful click, a bottom-center status toast confirms whether a hash or Context payload was copied. It uses a short pop animation, stays visible long enough to read, and restarts cleanly for rapid consecutive clicks. The toast respects prefers-reduced-motion by fading without the scale or overshoot motion.

Changing locator preferences

A translucent grey fox button sits in the bottom-left corner of every dev page. Click it to open a blurred, high-density settings popover.

• Pick Control, Option / Alt, or Command / Meta from a 28px-row list.

• The active key is marked with a themed keycap; the hovered row stays neutral grey.

• Pick Neutral, Violet, Orange, or Sky under Overlay Color. Violet is the default.

• The selected color updates the current and parent outlines, current fill, hover label, active keycap, and selected color ring.

• Choose 0, 1, 2, or 3 under Parent Levels. The default is 1. 0 hides parent outlines; higher values walk outward through visually distinct ancestors carrying both source-file and source-location metadata.

• Copy As defaults to Hash, which is the precise MCP lookup workflow. Context can combine Tag and Location, with optional Line when Location is selected. Output order is always Tag → Location regardless of click order:

  <Link→a> | /apps/astro/src/components/HospitalListCard.tsx:298:13

• Location can be shown as a Vite workspace-root-relative Path (with a leading /) or an extension-preserving Module name. Turning Location off also turns Line off; the last Path/Module name preference is remembered when Location is enabled again.

• The whole Context row opens and closes its options. Selecting Context from Hash opens it automatically; switching back to Hash does not force it closed. The disclosure starts closed on every page load.

• Pressing or releasing the trigger key never opens or closes the popover.

• Combinations that include another modifier are not intercepted by the locator.

• Drag the fox button to reposition it — the popover follows and the position persists in the browser.

• Close the popover with an outside click or Escape. It always starts closed on reload.

Trigger, Copy As, color, and parent-level choices are stored globally and apply immediately on the current page. Other open locator pages pick them up on refresh.

Options

integrations: [astroInspector({ showAllBoundaries: false })]

MCP setup

Register a project-local stdio command with your MCP host. --project-root must be an absolute path to the Astro project.

{
  "command": "npx",
  "args": [
    "--no-install",
    "astro-inspector-mcp",
    "--project-root",
    "/absolute/path/to/your/astro-project"
  ]
}

If your host launches commands from outside the Astro project, point command directly at the binary instead:

/absolute/path/to/your/astro-project/node_modules/.bin/astro-inspector-mcp

The tool

When a prompt contains an astro_hash_ value, the model calls get_astro_element_by_hash and receives:

• the project-relative file path, plus a validated absolute path

• line, column, source tag, and rendered DOM tag

• the code surrounding the selection

Full file contents are never included in the MCP response. The connected CLI or ACP reads only the range it needs, from the validated path.

How it works

In dev mode the Astro integration installs a Vite plugin and a small browser client.

1. Inject. Before Astro/React compilation, the plugin adds source-location attributes to .astro, .tsx, and .jsx tags inside the project root. These data-* attributes survive into the real DOM, including after React islands hydrate.

2. Select. The browser posts the chosen location to an authenticated local dev endpoint.

3. Hash. The server derives a deterministic hash and records it in a manifest.

4. Resolve. A standalone stdio MCP server reads that manifest and maps the hash back to source.

Picking the right element

The client calls document.elementsFromPoint() to get the DOM stack under the pointer. The first metadata-bearing element whose own rendered box contains the point defines the visible layer, so a real DOM overlay blocks elements painted behind it. Within that layer, DOM depth and rendered area keep the most specific eligible element selected.

While the locator is active, ::before and ::after are prevented from intercepting hit testing. A stretched pseudo-element whose host box does not contain the pointer is skipped. Elements with pointer-events: none — which the browser excludes from the hit stack entirely — are collected once on activation, but only descendants of the visible native layer may refine the selected target.

The result: visible overlays remain selectable, stretched pseudo-elements do not hide the real element beneath them, and nested JSX children inside islands still resolve to the correct source location.

Overlay hierarchy

Hash stability

Repeated renders of the same .astro tag share one hash across all DOM instances. When the file changes through HMR — or is deleted — its existing hashes are invalidated.

Runtime files

Per-project selection manifest (gitignore this):

.astro-ai-locator/manifest.json

User-global locator settings, shared across every repository and worktree:

~/.astro-ai-locator/settings.json

The browser never touches this file directly. On page load the client makes one authenticated call to a local Vite endpoint, and the Vite process reads or atomically writes the file. Changes apply immediately on the current page; other open pages pick them up on refresh. Schema-v1 through schema-v4 settings are migrated in memory to schema v5; old Module settings become workspace Path settings. A missing or corrupted file falls back to Option/Alt, Violet, one parent level, and Hash copy with Path + Line ready under Context. The file is not created until you actually change a setting.

Scope

Additional constraints:

• Dev mode only. Production builds receive no client, no endpoint, and no source metadata.

• If clipboard permission is denied, the client falls back to a browser prompt containing the exact Hash or Context payload for manual copy.

• Key combinations the browser never delivers to the page — OS-reserved Command/Meta shortcuts, for example — cannot be intercepted.

• Assumes one Astro dev server per project directory.

Security

Dev endpoints require a token that is regenerated for every process. The element-registration endpoint caps the request body and the source file size, and accepts only real .astro / .tsx / .jsx files inside the project root at valid line and column positions. The workspace-relative path used by Context copy is derived from Vite's detected workspace root only after that validation; it is returned to the authenticated browser for the current click and is not stored in the DOM, manifest, MCP result, or settings. The settings endpoint validates allowlisted trigger keys, color presets, parent levels, copy modes, context fields, Location/Line dependencies, and Location formats before an atomic write.

The MCP server normalizes both manifest and source paths with realpath, blocking path traversal and symlink escapes. On stdio, stdout carries the MCP protocol only — all diagnostics go to stderr.

Current limitations

• A hash is derived from file path, line, column, and DOM tag. Moving the tag or changing what it renders produces a new hash.

• Astro major versions that change the compiler AST need separate compatibility verification.

• This release provides source lookup only. File-write permission and the actual code edits belong to the connected AI host.

License

ISC