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.

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

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):

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

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.