# 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.

![API and table mapping of the bundled synthetic order-service fixture](docs/images/api-map.png)

## 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.

## Quick start

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

```sh
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:

```sh
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:

```json
{
  "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](examples/claude.mcp.json)
- [Codex TOML](examples/codex.config.toml), using the format in the
  [official MCP documentation](https://developers.openai.com/codex/mcp/)

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:

```sh
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.

![An annotated order-creation tab created through MCP](docs/images/agent-board.png)

### 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

| Action | Control |
| --- | --- |
| Open API/table details | Click its card; click again or press Escape to close |
| Move a card | Drag |
| Select a group | Hold Shift and drag a rectangle over fully enclosed cards |
| Add a tab | **＋**, then blank canvas or copy of the initial map |
| Add a box/comment | Choose the tool, then click empty canvas |
| Edit text | Double-click a custom box; use the memo action on a source-backed card |
| Finish editing | Click outside or press Cmd/Ctrl+Enter; Escape cancels |
| Connect cards | Drag between connection handles |
| Delete selection | Delete |
| Undo / redo | Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z |
| Rename a tab | Double-click its name or use the pencil button |

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

| Tool | Purpose |
| --- | --- |
| `atlas_open` | Session URL and project |
| `atlas_get_graph` | Search indexed symbols and relationships |
| `atlas_get_database` | API/table access, SQL, call paths and JOIN evidence |
| `atlas_get_source` | Exact lines from the indexed source snapshot |
| `atlas_get_selection` | Current browser selection, including editable tabs |
| `atlas_get_boards` | Tab summaries or a complete tab with its revision |
| `atlas_create_board` | Create a rich editable diagram tab |
| `atlas_patch_board` | Update a tab with optimistic revision checking |
| `atlas_wait_for_request` | Retrieve queued browser requests and their context |
| `atlas_add_note` | Add a cited explanation and optionally complete a request |
| `atlas_set_view` | Change visibility in the source graph |
| `atlas_patch_graph` | Add agent-authored concepts and relationships |

## 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

```sh
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.

```text
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](LICENSE). See each dependency's own license for its terms.