ArchToCode Bridge

Local CLI bridge and MCP adapter for ArchToCode. It lets you:

• Generate Mermaid diagrams from local code without uploading your repo.
• Connect the ArchToCode web app to a local AI CLI (Claude, Gemini, Ollama, OpenAI).
• Expose ArchToCode prompts to MCP clients (Claude Code) and push results back to the browser.

What It Is

The package ships two main pieces:

1. Bridge server (HTTP + WebSocket): receives diagram generation requests and streams results back to the browser.
2. MCP adapter (stdio): exposes tools like archtocode_list_prompts and archtocode_generate_diagram to MCP clients.

Install

npm install -g @archtocode/bridge

Quick Start (Web App)

1. Start the bridge in your repo:

archtocode start --provider claude --repo .

2. The bridge prints a handshake token. In the web app:

• Open archtocode.com
• Go to Prompts > AI Model Settings > Local / CLI
• Click Connect and paste the token

3. Click any prompt in the left sidebar. The request is handled locally.

Quick Start (MCP / Claude Code)

1. Start the bridge:

archtocode start --provider claude --repo .

2. Start the MCP adapter (stdio):

archtocode mcp

3. Configure your MCP client (Claude Code) to run archtocode mcp. The adapter uses the stored handshake token from ~/.archtocode/bridge.json.

Commands

archtocode start

Start the local bridge server.

Options:

• --port <number>: port to listen on (default 49321)
• --provider <name>: default CLI provider (default claude)
• --model <name>: default model name for the provider
• --repo <path>: project path to index (default current directory)

Example:

archtocode start --provider claude --model sonnet --repo .

archtocode mcp

Start the MCP adapter (stdio). It reads bridge config from: ~/.archtocode/bridge.json

Options:

• --bridge-url <url>: override bridge URL (default http://127.0.0.1:<port>)
• --token <token>: override handshake token

archtocode doctor

Check prerequisites and CLI availability.

archtocode status

Print bridge status (must be running).

archtocode stop

Request graceful shutdown.

archtocode logs

Shows guidance on where logs are written.

MCP Tools Exposed

When archtocode mcp is running, MCP clients can call:

• archtocode_list_prompts - list available diagram prompts
• archtocode_get_prompt - fetch prompt details by ID
• archtocode_generate_diagram - generate Mermaid via local bridge
• archtocode_push_result - push Mermaid back to the web app

Configuration

The bridge stores its config here: ~/.archtocode/bridge.json

Environment overrides for MCP:

• ARCHTOCODE_BRIDGE_URL
• ARCHTOCODE_BRIDGE_TOKEN

Troubleshooting

posix_spawnp failed on macOS

The postinstall script fixes node-pty helper permissions. If you still see it:

npm install -g @archtocode/bridge

EMFILE: too many open files, watch

Increase file descriptor limit:

ulimit -n 65536

MCP crashes with Cannot read properties of null (reading '_zod')

Update to @archtocode/[email protected] or newer.

Web app returns ANSI/TUI garbage instead of Mermaid

Update to @archtocode/[email protected] or newer. The bridge runs Claude in non-interactive print mode and strips ANSI before Mermaid extraction.

About ArchToCode

ArchToCode (archtocode.com) is a web app for generating and exploring Mermaid diagrams from code. It provides:

• 30+ prompt templates and 16 diagram types
• GitHub and local repository integration
• Diagram rendering, zoom/pan, node inspection, and export
• Local / CLI integration for private, offline-capable analysis

The bridge is the local companion to the web app. Use it when you want private generation with your own local AI CLI.