Code Atlas

Explore a codebase on a shared canvas with your coding agent.

Code Atlas maps Go HTTP endpoints to the MySQL tables they touch, with SQL operations and source references. Open a card to investigate, make an editable copy, and ask your agent to turn a particular flow into a new diagram tab. The browser and agent work on the same local state through MCP.

Early prototype: Go source analysis and MySQL query syntax are supported. Route detection currently recognizes literal r.Get, r.Post, r.Put and r.Delete registrations with a named handler. Other router styles need an adapter.

What you can do

• See all detected endpoints and tables, including endpoints with no detected SQL.

• Distinguish API cards from table shapes; inspect SELECT / INSERT / UPDATE / DELETE operations, SQL text, source locations and static call paths inside a card.

• Inspect column evidence from Go db tags and detected ALTER TABLE statements.

• Move cards, expand details in place, and hold Shift to select and move a group.

• Create tabs from an empty canvas or a rich copy of the generated map. Add rectangles, comments, connections and annotations, with undo/redo.

• Let an MCP-connected agent create or update tabs using the original source-backed API/table cards. Shared revisions prevent silent overwrites; a conflicting browser save is preserved as a separate copy.

• Send a browser request with a snapshot of the active tab and selected elements.

SQL JOIN evidence is available through atlas_get_database. The default canvas shows endpoint-to-table access; it does not draw table-to-table JOINs automatically.

Related MCP server: chrome-devtools-mcp

Quick start

Requirements: Node.js 22.12+, npm, and Go 1.20+ on your PATH.

git clone https://github.com/puppypepper/code-atlas.git
cd code-atlas
npm ci
npm run build
npm start -- --project ./examples/demo

Open http://127.0.0.1:4317. The bundled demo is an original, synthetic order service with seven endpoints and four tables. It is parsed as source only; no sample application or database needs to run.

To inspect your own repository:

npm start -- --project /absolute/path/to/your/go-repository --port 4317

Stop the previous server before changing projects on the same port, or select a different port. Atlas reads the target files; it does not build or run the target, connect to its database, or modify its source.

For persistent local settings, copy atlas.config.example.json to atlas.config.json and change project to your repository's absolute path. atlas.config.json is ignored by Git. Options resolve in this order: CLI flags → exported ATLAS_PROJECT / PORT variables → local config → current working directory / port 4317. .env files are not loaded automatically.

Connect your coding agent

After building, add this stdio MCP server to your client:

{
  "command": "node",
  "args": [
    "/absolute/path/to/code-atlas/bin/atlas.mjs",
    "--project", "/absolute/path/to/your/go-repository",
    "--port", "4317"
  ]
}

Replace both paths. If a browser server already serves the same project and port, the agent shares it. Otherwise the MCP process starts its own local server. Use atlas_open to retrieve the URL. Atlas does not require a separate model API key; your coding agent handles model access.

Client-specific templates:

• Claude MCP JSON

• Codex TOML, using the format in the official MCP documentation

Reconnect the client after upgrading Atlas so it registers the current tools.

Ask for a focused diagram

For example, ask your connected agent:

Create a new tab explaining the order-creation API. Show validation, transactions, database writes and failure paths, with source references.

The agent should read atlas_get_database to find the exact route ID, inspect handlers and helpers using atlas_get_source, and call atlas_create_board. routeIds creates rich API/table cards automatically; additional nodes and labeled edges explain the flow. Existing tabs can be read with atlas_get_boards and updated with atlas_patch_board using expectedRevision.

To try a prewritten example against the bundled demo, keep its web server running and execute:

node examples/create-demo-board.mjs

This uses a real stdio MCP connection to add an annotated Order creation tab. Pass --port 4318 if the demo server uses a different port.

Request work from the browser

Use 「AIに依頼」 in the top-right corner. Requests preserve the tab revision, selected nodes/edges, annotations and source references at submission time. Then tell your existing agent conversation: “Process the pending Atlas request.” The agent retrieves it with atlas_wait_for_request and completes it by passing requestId to a board update or note.

MCP alone cannot wake an idle chat or start a new agent turn. A running agent can wait up to 25 seconds per tool call; automatic chat activation requires a separate integration with the chat host. Browser submission does not itself start inference.

Editing controls

API names, SQL and column evidence remain tied to source. Custom text is an annotation, rather than an edit to the indexed facts.

MCP tools

Local data and analysis limits

• Storage: editable tabs, requests, notes and source snapshots are stored in the tool's ignored .atlas/ directory, keyed by target project path. Browser storage also holds generated-map positions and draft backups. These can contain private source; keep them local. Target settings, .env files and local preview*.png captures are ignored as well.

• Network: the server binds to loopback and checks Host/Origin. The browser talks to it over HTTP/SSE. This is a single-user local tool, not an authenticated service for network deployment. Atlas has no built-in hosted model service; your agent's own data handling still applies.

• Analysis: Go AST and SQL parsing produce static candidates, not execution traces or query counts. Dynamic dispatch, type resolution, conditional execution, ORM-generated queries and dynamically assembled SQL may be incomplete. Detected JOINs do not imply database foreign-key constraints.

• Schema: columns come from source evidence, not a live database schema.

• Scan limits: at most 250 text files, 4 MB total, 200 KB per file and directory depth 10. Hidden directories, symlinks, vendor, build outputs and common asset directories are skipped. Only indexed project files are available through MCP.

• Refresh: restart the server after changing target source. Editable tabs are retained across reindexing; source references may need review after code moves.

Development

npm ci
npm run build:indexer
# Set the target explicitly; Vite proxies to the API on port 4317.
ATLAS_PROJECT=/absolute/path/to/your/go-repository npm run dev
npm test
npm run build

Development serves the API on 4317 and Vite on 5173. npm test includes a real stdio MCP integration test that binds to loopback port 14317; keep that port free. Builds compile the Go indexer, check TypeScript and bundle the frontend.

src/          Browser canvas, rich cards, inline details and shared-tab state
shared/       Graph and board models shared by browser and server
server/       Source analysis, persistence, HTTP/SSE and stdio MCP bridge
go-index/     Source-only Go AST and SQL extraction
examples/     Client configs, original demo source and MCP diagram example
tests/        Parser, graph, persistence, conflicts and MCP integration tests

License

MIT. See each dependency's own license for its terms.