Site Atlas

A semantic map of websites for people and AI agents. Site Atlas scans a site, splits every page into sections (header, hero, content sections, footer…), flags problems, and lets you rearrange the site on a drag‑and‑drop canvas. Everything you plan is exposed through MCP and the CLI, so any AI (Claude, Codex, GPT and others) can read it and implement it in the code.

Why it exists

Looking at a page doesn't answer questions like:

• Which sections does this page have, and in what order?

• Where does each button point, and which links are broken?

• Should this section live on another page?

• What changes if I move section A to page B?

Site Atlas makes that visible and turns your decisions into a concrete plan an AI can execute. Atlas never modifies the site itself: you decide, the AI implements.

Related MCP server: agent-ready-mcp

What it does today (v1)

Coming next (v2): the org chart

Each page as a diagram of pieces, with one line per link coming out of the exact section that contains it. It adds shared components with their own diagram, arrows you can drag and snap to a new target, new connectors, a screenshot view, and changes that stay pending until an AI confirms it applied them. Design under review: organigrama-design.md (Spanish).

How it works

 your site (localhost, staging or production)
        │  Chromium scan (read-only)
        ▼
 ~/.site-atlas/sites/<site>/
   ├── scans/*.json      immutable snapshots of the site
   ├── shots/*.webp      a thumbnail per section
   └── overlay.json      your organization: order, pages, tags
        │
        ├──► local canvas   http://127.0.0.1:4800
        └──► MCP / CLI ──► Claude · Codex · GPT · …  ──► changes in the site's code

Installation

Requirements: Node 24+ and pnpm (npm i -g pnpm).

git clone https://github.com/zavants/site-atlas-zavants.git
cd site-atlas-zavants
pnpm install
pnpm exec playwright install chromium
pnpm build

Quick start

# Scan (up to 30 pages by default)
node dist/cli.js scan http://localhost:4321/

# More options
node dist/cli.js scan https://example.com --max-pages 5 --exclude "/blog/**"

# Open the canvas
node dist/cli.js canvas

Connect it to your AI (MCP)

The MCP server starts with node <path>/dist/cli.js mcp over stdio.

Claude Code (terminal)

claude mcp add site-atlas -- node /path/to/site-atlas-zavants/dist/cli.js mcp

Claude Code (desktop app, without the claude CLI). Add this to ~/.claude.json, inside mcpServers:

"site-atlas": { "type": "stdio", "command": "node", "args": ["/path/to/site-atlas-zavants/dist/cli.js", "mcp"] }

Codex, in ~/.codex/config.toml:

[mcp_servers.site-atlas]
command = "node"
args = ["/path/to/site-atlas-zavants/dist/cli.js", "mcp"]

Other MCP clients (Cursor, Windsurf, Claude Desktop…):

{ "mcpServers": { "site-atlas": { "command": "node", "args": ["/path/to/site-atlas-zavants/dist/cli.js", "mcp"] } } }

Tools

Example prompt for an agent:

"Scan http://localhost:4321 with site-atlas, move the pricing section to /pricing and tell me what needs to change in the code."

Text extracted from the scanned site is marked as untrusted content, so agents treat it as data, not instructions.

Optional markers

Atlas detects sections on its own: top-level header, section and footer, plus visible blocks inside main. On your own site you can set the exact split:

<section data-atlas-block="Hero">…</section>

Data and privacy

• Everything is stored in ~/.site-atlas/, or in the folder set by SITE_ATLAS_HOME.

• Nothing leaves your machine, except the requests to the site you scan.

• On public sites it respects robots.txt and waits 1 s between pages.

• Atlas never writes to the site's repository.

Development

pnpm test            # unit, integration and canvas tests (Vitest + Playwright)
pnpm typecheck       # server (tsc) and canvas (vue-tsc)
pnpm atlas scan …    # CLI without building (tsx)
pnpm dev:canvas      # canvas with hot reload (needs the server on :4800)

Stack: Node 24, TypeScript, Playwright, Hono, Vue 3 + Vite, Zod and @modelcontextprotocol/sdk.

The interface and messages are currently in Spanish.

Tested with

Contributing

Issues and pull requests are welcome. For larger changes, please open an issue first to discuss them. Design decisions live in docs/superpowers/specs/.

License

Open source under the MIT license.