Skip to main content
Glama

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 org chart. 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.

Site Atlas org chart with a sample site: pages as diagrams of pieces, one line per link, shared components and a planned page


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

Section-level scanning

Renders each page in Chromium, splits it into sections and records name, type (narrative, visual, conversion), detected role, headings, links, forms, media and a thumbnail.

Issues

Broken links, missing anchors, forms without an action, placeholder images, sections without an anchor, missing or duplicate headings, duplicate ids.

Org chart

Each page is a diagram of pieces, with one line per link, drawn from the exact section that contains it: blue to another section, red to a page that doesn't exist, gray to an external site. Shared components (header, footer) get their own diagram. Drag a piece to reorder it or move it to another page, drag a line's end to point it at a new target, drag from the + of a piece to add a connector, add planned pages, and undo or redo any of it. A Screenshots view swaps the diagram for the real thumbnails. Also: tags with filters, a trash zone, Real / Planned views and live updates. Every piece shows its detected role (hero, logos, features, steps, products, pricing, FAQ, testimonials, team, contact…), read from the structure and the wording of the rendered page in Spanish, English and Portuguese; the filter bar lists the roles present on the map, and in Edit mode you can correct a role by hand, which survives every re-scan.

Plan for AI

The differences between the real site and the plan, in plain language and JSON. Each change is pending until the AI that implements it confirms it (with a note), and then it is applied.

Lossless re-scans

Your organization survives site changes: sections are matched by anchor, fingerprint or text similarity, and anything unmatched becomes an orphan you can reassign.

Local and safe

Runs on your machine or on a server. By default the canvas listens on 127.0.0.1 only, protected against CSRF and DNS rebinding; on a server it is guarded by a token. No telemetry. Atlas never writes to your site's repository.

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

New here? docs/tutorial.md walks the whole thing: install, your first scan, reading and rearranging the canvas, connecting Claude Code or Codex, and the round trip where an agent implements your plan and confirms it. What follows is the reference.

One line, Linux or macOS (servers included). It finds or installs Node 24, installs the package with npm, downloads Chromium and runs site-atlas doctor:

curl -fsSL https://raw.githubusercontent.com/zavants/site-atlas-zavants/main/install.sh | bash

No root needed: without a Node 24+ on the machine it puts a private one under ~/.site-atlas/node, and without a writable global npm folder it installs under ~/.site-atlas/npm and links site-atlas into ~/.local/bin. Knobs: SITE_ATLAS_SOURCE=release|npm|git, SITE_ATLAS_REF=<branch or tag>, SITE_ATLAS_NO_SETUP=1.

With npm (any OS with Node 24+, including Windows):

npm install -g site-atlas        # or the tarball of a release: npm install -g https://github.com/zavants/site-atlas-zavants/releases/latest/download/site-atlas.tgz
site-atlas setup                 # downloads Chromium; on Linux add --with-deps (root) to also install its system libraries
site-atlas doctor                # checks Node, Chromium, the canvas files and the data folder

Docker:

docker build -t site-atlas https://github.com/zavants/site-atlas-zavants.git
docker run -d --name site-atlas -p 4800:4800 -v site-atlas:/data -e SITE_ATLAS_TOKEN=<secret> site-atlas
docker exec site-atlas site-atlas scan https://example.com

From source (to work on Atlas itself): see Development.

Quick start

site-atlas canvas        # opens http://127.0.0.1:4800

The start page is where everything begins: paste a URL (with optional limits on pages and paths), watch the scan progress, and the canvas of the new atlas opens when it finishes. Every atlas you made before is listed as a card with its size, its issues, how much of the plan is still pending, and buttons to open, re-scan, rename or delete it, plus a ready-made prompt for your AI agent.

The same from the terminal:

# Scan (up to 30 pages by default)
site-atlas scan http://localhost:4321/

# More options
site-atlas scan https://example.com --max-pages 5 --exclude "/blog/**"

CLI

Command

Purpose

setup [--with-deps] · doctor [--json]

Download Chromium · check the installation (--json for an agent to read)

scan <url> · canvas [site] [--host <ip>] [--port <n>] [--token <t>]

Scan a site · start the canvas (see Run on a server)

plan <site>

Print the plan: pending and applied changes

advise <site> · advise <site> --file <advice.md> --summary "<one line>" --mode own|advisory

Print the stored recommendation · store one, which the canvas home card then shows

confirm <site> <changeId> --note "<what you changed and where>" · reopen <site> <changeId> --note "<why>"

Mark a change applied once it is in the code · set it back to pending

move <site> <blockKey> <toPage> · delete <site> <blockKey> · restore <site> <blockKey>

Propose moving or deleting a section, or cancel the deletion

role <site> <blockKey> <role>

Correct the detected role of a section (features, pricing, faq, steps…), or auto to go back to the detected one

page add <site> <path> · page remove <site> <path>

Planned pages

relink <site> <owner> · unlink <site> <owner> · link add <site> <owner> · link remove <site> <linkId>

Change, remove, add or drop links

component rename <site> <componentId> <name>

Rename a shared component (header, footer)

An agent without MCP can work from the terminal alone: site-atlas plan my-site, implement the pending changes, then site-atlas confirm my-site <changeId> --note "<what you changed and where>".

Run on a server

Scans and the plan work the same on a server as on a laptop: install Atlas there, scan, and point your agents at it over SSH or MCP. For the canvas you have two options.

SSH tunnel (simplest, nothing exposed). Keep the default local bind and forward the port from your machine:

ssh -L 4800:127.0.0.1:4800 user@server   # then open http://127.0.0.1:4800 locally

Bind to the network with a token. Anything but 127.0.0.1 requires a token; Atlas generates one when you don't give one and prints a link that sets it as a cookie:

site-atlas canvas --host 0.0.0.0 --token "$(openssl rand -base64 24)"
# Canvas: http://203.0.113.10:4800/s/
# Open it once with this link (it sets a cookie): http://203.0.113.10:4800/s/?token=…
# Token for the API (Authorization: Bearer): …

With a token, every request except /api/health needs Authorization: Bearer <token> or that cookie, and cookie-authenticated writes must be same-origin. The token travels in clear text over HTTP: put a reverse proxy with HTTPS in front (Caddy, nginx) before using it outside a trusted network. The options also read SITE_ATLAS_HOST, SITE_ATLAS_PORT and SITE_ATLAS_TOKEN, which suits a service unit:

# /etc/systemd/system/site-atlas.service
[Unit]
Description=Site Atlas canvas
After=network.target

[Service]
User=atlas
Environment=SITE_ATLAS_HOST=0.0.0.0 SITE_ATLAS_PORT=4800 SITE_ATLAS_TOKEN=change-me
ExecStart=/usr/local/bin/site-atlas canvas
Restart=on-failure

[Install]
WantedBy=multi-user.target

The Docker image does the same: it listens on every interface of the container, reads SITE_ATLAS_TOKEN, and keeps its data in the /data volume.

Connect it to your AI (MCP)

The MCP server starts with site-atlas mcp over stdio (from a source checkout: node <path>/dist/cli.js mcp).

Claude Code (terminal)

claude mcp add site-atlas -- site-atlas mcp

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

"site-atlas": { "type": "stdio", "command": "site-atlas", "args": ["mcp"] }

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

[mcp_servers.site-atlas]
command = "site-atlas"
args = ["mcp"]

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

{ "mcpServers": { "site-atlas": { "command": "site-atlas", "args": ["mcp"] } } }

On Windows, npm installs site-atlas.cmd; if a client cannot start it, use "command": "node" with "args": ["<npm prefix>/node_modules/site-atlas/dist/cli.js", "mcp"] (npm prefix -g prints the folder).

Tools (24)

Tool

Purpose

atlas_scan

Scan a site and reconcile your existing organization

atlas_list_sites

List scanned sites, with their mode and the summary of their advice

atlas_get_map

Map of pages and sections, with kinds, detected roles, tags and planned order

atlas_get_block

Section details (components, issues, thumbnail)

atlas_list_issues

Issues from the latest scan

atlas_set_advice · atlas_get_advice

Store a recommendation next to the atlas, with the site's mode · read the stored one

atlas_tags · atlas_set_block_tags

Create, rename, delete and assign tags

atlas_set_block_role

Correct the detected role of a section, or clear it to go back to the detected one

atlas_move_block · atlas_add_planned_page

Rearrange the planned order

atlas_get_plan

The plan (Markdown + JSON, optional status): what to change in the site's code

atlas_confirm_change · atlas_reopen_change

Mark a change applied (with a note) or set it back to pending

atlas_relink · atlas_unlink · atlas_add_link · atlas_remove_link

Propose changing, removing or adding links, or drop a link proposal

atlas_mark_deleted · atlas_restore · atlas_remove_planned_page

Propose deleting a section, undo it, remove a planned page

atlas_rename_component

Rename a shared component, e.g. "Header 1" to "Main header"

atlas_open_canvas

Canvas URL

Changes proposed on the canvas, by the CLI or by an agent stay pending in the plan. After implementing one in the code, the agent calls atlas_confirm_change (or site-atlas confirm) and the change moves to applied.

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.

Use it from your AI (plugin)

The MCP entry above hands an agent the tools. The plugin hands it the tools and the method: four skills it loads on its own, or that you call by name. It installs from this repository, which is also its marketplace, in either agent.

Claude Code

claude plugin marketplace add zavants/site-atlas-zavants
claude plugin install site-atlas@site-atlas

In the desktop app the second step is + → Add plugins → Site Atlas.

Codex

codex plugin marketplace add zavants/site-atlas-zavants
codex plugin add site-atlas@site-atlas

Both agents start a plugin's MCP server when a session starts, so a session that is already open needs /reload-plugins (Claude Code) or a new session (Codex).

The plugin does not carry the scanner. It looks for the site-atlas command on your PATH, then in ~/.site-atlas/npm/bin and ~/.local/bin, then in the global npm folder, and last in a source checkout around itself; SITE_ATLAS_BIN overrides all of them. When it finds nothing, the first skill installs it.

Skill

What it does

atlas

Scans a URL into pages and sections, opens the canvas, and reports the shape of the site with its most frequent issues

atlas-advise

Reads the whole atlas, writes a prioritized recommendation along five fixed axes, puts what it can on the canvas as pending changes, and stores the advice on the atlas

atlas-apply

Implements the pending changes in the code of your own site, re-scans to verify, and confirms each one

site-atlas-setup

Installs the CLI, downloads its Chromium, and works through a failing check

Two modes, stored on the atlas and switchable from the home card of the canvas. In my site (own) the agent advises and implements, verifying each change with a re-scan. In someone else's site (advisory) it observes and recommends only: the plan stays a proposal, the deliverable is a report, and atlas-apply refuses.

What it cannot see, which atlas-advise restates whenever it shaped the advice:

  • up to 30 pages by default, one origin, robots.txt respected;

  • the rendered DOM at desktop size: no login, no interaction, no mobile layout;

  • sections and their roles come from heuristics, and you can correct any of them;

  • issues are structural, not content or performance.

Cursor, Windsurf and Claude Desktop have no plugin format here: point them at the server with the plain MCP entry above.

CLI on Windows (Git Bash)

Git Bash rewrites arguments that start with / into Windows paths (/~hero becomes C:/Program Files/Git/~hero) before the CLI sees them. Start the command with MSYS_NO_PATHCONV=1:

MSYS_NO_PATHCONV=1 site-atlas move my-site /~hero /pricing

The CLI refuses arguments that look rewritten and tells you to do this. PowerShell and cmd are not affected.

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. Chromium goes to Playwright's cache (PLAYWRIGHT_BROWSERS_PATH to move it).

  • 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

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

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)
npm pack             # the tarball that `npm install -g` and the installer use

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

Releases. Bump version in package.json, then tag it (git tag v0.2.0 && git push --tags). The release workflow builds the package, attaches site-atlas.tgz to a GitHub release (what install.sh downloads) and publishes to npm when the NPM_TOKEN secret is set.

The interface and messages are currently in Spanish.

Tested with

Site

Result

Local marketing site (HTML, 15 sections)

15 sections with their real names; found a broken link, 4 sections without an anchor, placeholder images and a form without an action

stripe.com (1 page)

10 sections, 8 with a readable name, in 26 s

vercel.com (1 page)

6 sections, all with a readable name

Agent round trip (terminal-only Claude agent, CLI only, no MCP)

Read site-atlas plan, implemented a section delete and a relink in the site source, verified with curl, confirmed both with notes; after a re-scan the plan reports the site already matches it

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
      9 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to crawl live websites, audit AEO readiness, generate Schema.org @graph JSON-LD, llms.txt, ai.txt, and robots.txt, inject structured data into HTML, validate optimizations, and retrieve framework-specific code snippets.
      MIT