# Local DAG Builder MCP

A private-by-default, local-first DAG editor launched through Model Context Protocol (MCP). Build causal diagrams visually, validate cycles immediately, and save/export portable JSON, SVG, or PNG.

![DAG builder screenshot](docs/screenshots/editor.png)

```mermaid
flowchart LR
  User --> Codex
  Codex --> MCP[MCP server]
  MCP --> Launcher[local process manager]
  Launcher --> Web[React DAG website]
  Web --> Storage[Browser storage / JSON]
```

## Quick start

```powershell
git clone https://github.com/resace3/local-dag-builder-mcp.git
cd local-dag-builder-mcp
npm install
npm run build
npm run start:mcp
```

Then add the MCP configuration below and ask Codex: **Start the local DAG builder.** The tool returns a verified `http://127.0.0.1:8080` URL. For manual web development: `npm run dev`.

## Codex configuration

Codex uses an `mcp_servers` table. Add this to `~/.codex/config.toml` (Windows: `C:\\Users\\<you>\\.codex\\config.toml`):

```toml
[mcp_servers.local_dag_builder]
command = "node"
args = ["C:\\path\\to\\local-dag-builder-mcp\\packages\\mcp-server\\dist\\index.js"]
```

On macOS/Linux, use `/absolute/path/to/local-dag-builder-mcp/packages/mcp-server/dist/index.js`. In WSL, use the Linux path. Restart Codex, then ask it to call `get_dag_builder_status`. See [docs/mcp-tools.md](docs/mcp-tools.md) for details.

## Features

- Drag, edit, duplicate, colour, search and auto-arrange typed nodes.
- Directed React Flow edges with immediate self-loop and cycle rejection.
- Live validity, warnings, counts, and topological order.
- Undo/redo, local save/load, JSON import/export/copy, SVG and PNG exports.
- MCP tools: `start_dag_builder`, `stop_dag_builder`, `get_dag_builder_status`, `create_example_dag`, `validate_dag`, `open_dag_file`.

## Commands

`npm run build` · `npm run dev` · `npm run start:web` · `npm run start:mcp` · `npm test` · `npm run test:e2e` · `npm run lint` · `npm run typecheck`

`scripts/setup.ps1` and `scripts/setup.sh` install and build in one step.

## DAG schema

`{ version: "1.0", name, nodes: [{ id, label, type, description?, color?, position }], edges: [{ id, source, target, label? }] }`. Examples live in `examples/`.

## Security and privacy

The website binds only to `127.0.0.1`; no analytics or external services are used. The MCP server validates ports, uses `spawn` without a shell, caps request sizes, and only reads example files or paths under the project / explicit allowed folder. DAG JSON is data, never executable code. Details: [docs/architecture.md](docs/architecture.md).

## Testing and troubleshooting

Run `npm test`, `npm run typecheck`, then `npm run test:e2e`. If port 8080 is busy, request another port (or the launcher picks the next available port). Delete browser local storage from the editor’s Clear action if a saved graph needs resetting.

MIT licensed.