# @circuitry-ide/mcp-server

MCP (Model Context Protocol) server that gives AI coding agents access to [Circuitry](https://www.circuitry.dev) - a visual workflow and diagramming platform.

## What It Does

- **Visualize Code**: Create code nodes from project files with bidirectional sync
- **Understand Diagrams**: AI agents can comprehend user-drawn flowcharts and diagrams
- **Create Flowcharts**: Generate visual flowcharts via Circuitry's chat agent
- **Data Visualization**: Create spreadsheets and charts from code analysis

## Prerequisites

1. **Circuitry Server** - Download from [circuitry.dev/download](https://www.circuitry.dev/download)
2. **Node.js 18+**
3. **An MCP-compatible AI client** (Claude Code, Cursor, VS Code, Gemini CLI, etc.)

## Setup

### 1. Install & Configure Circuitry Server

1. Download **Circuitry Server** from [circuitry.dev/download](https://www.circuitry.dev/download)
2. Launch the app (appears in your system tray)
3. Click the tray icon → **Server → Preferences**
4. Click **"Generate New Access Key"**
5. Copy the key — you'll need it in the next step

### 2. Run MCP Setup (Required)

```bash
npx @circuitry-ide/mcp-server setup
```

This will prompt you to enter:
- **EServer address** — press Enter for default (`http://localhost:3030`)
- **Access key** — paste the key you generated above

This stores your credentials in `~/.circuitry/mcp-config.json`.

### 3. Add to Your AI Client

#### Claude Code

```bash
claude mcp add circuitry npx @circuitry-ide/mcp-server
```

Or manually add to `~/.claude/config.json`:

```json
{
  "mcpServers": {
    "circuitry": {
      "command": "npx",
      "args": ["-y", "@circuitry-ide/mcp-server"]
    }
  }
}
```

#### Cursor

Settings → MCP → Add New MCP Server:

```json
{
  "mcpServers": {
    "circuitry": {
      "command": "npx",
      "args": ["-y", "@circuitry-ide/mcp-server"]
    }
  }
}
```

#### VS Code / Copilot

```bash
code --add-mcp '{"name":"circuitry","command":"npx","args":["-y","@circuitry-ide/mcp-server"]}'
```

#### Gemini CLI

```bash
gemini mcp add circuitry npx @circuitry-ide/mcp-server
```

#### Cline / Windsurf

Add to your MCP configuration using the standard format above.

### 4. Restart Your Client

Restart your AI client to load the MCP server.

## Usage Examples

### Visualize Code Files

```
You: Show me the auth files as code nodes in Circuitry

Agent: I'll create code nodes from your auth files...
Done! Created 4 code nodes:
- auth/login.ts
- auth/logout.ts
- auth/middleware.ts
- auth/types.ts

Changes sync bidirectionally with your source files.
```

### Understand User-Drawn Flows

```
You: I've drawn a flow of how I think the auth should work

Agent: I'll analyze your flow in Circuitry...

I can see you've drawn a 5-node authentication flow:
1. Start → Login Form
2. Login Form → Validate Credentials
3. Validate Credentials → branches to Success/Failure
...
```

### Create Flowcharts

```
You: Create a flowchart showing the error handling flow

Agent: I'll ask Circuitry's agent to create this flowchart...

Done! Created a flowchart with 7 nodes showing:
- Error detection
- Classification (runtime vs validation)
- Logging paths
- User notification
- Recovery options
```

## Available Tools

### Connection
| Tool | Description |
|------|-------------|
| `circuitry.status` | Check connection status |
| `circuitry.connect` | Request connection (shows permission dialog) |

### Workflow Understanding
| Tool | Description |
|------|-------------|
| `workflow.getActive` | Get current visible workflow info |
| `workflow.getStructure` | Get simplified workflow structure |
| `workflow.resolveFlow` | Resolve user reference ("this flow") to node IDs |
| `workflow.getNodeSummary` | Get simplified node details |

### Node Operations
| Tool | Description |
|------|-------------|
| `nodes.list` | List all nodes in the workflow |
| `nodes.get` | Get a node by ID |
| `nodes.update` | Update node configuration |
| `nodes.delete` | Delete a node |

### Code Nodes
| Tool | Description |
|------|-------------|
| `code.create` | Create code node (from file path with sync, OR with name+content) |
| `code.createBatch` | Create multiple code nodes from files |
| `code.setCode` | Update code content (syncs to source if applicable) |

### Sheet Nodes
| Tool | Description |
|------|-------------|
| `sheet.create` | Create a spreadsheet node with data |
| `sheet.setData` | Replace sheet data |

> The tables above are a hand-picked highlight. The **full** tool catalog is
> fetched live from the connected Circuitry app (see below), so it grows with the
> app — there may be many more tools available than are listed here.

## How tools stay in sync (dynamic discovery)

This package does **not** hard-code the tool catalog. On a successful
`circuitry.connect`, the server fetches the app's live tool definitions over the
existing relay (`tools.getDefinitions`) and advertises them to your AI client —
so **when Circuitry adds a tool, you get it without updating this package.**

Resolution order for the active tool list:

1. **Live fetch** from the connected app (freshest).
2. **Disk cache** of the last successful fetch (`~/.circuitry-mcp/tools-cache.json`) — used when offline.
3. **Bundled snapshot** (`tools-snapshot.json`, shipped in the npm tarball) — first-run fallback.

The `circuitry.*` connection tools are always available regardless of source.

If the app reports it needs a newer server than you have (version handshake), the
server keeps working with whatever it can parse and surfaces an update-required
notice on `circuitry.connect` / `circuitry.status`:

```
npm i -g @circuitry-ide/mcp-server@latest   # or just use `npx @circuitry-ide/mcp-server`
```

The bundled snapshot is regenerated at publish time from the app's source of
truth (`circuitry/src/lib/circuitry-api/tool-definitions.ts`) via
`npm run mcp:generate` in the app repo. There is no manual parity step to run.

> Dynamic discovery landed in **2.1.0** — see [CHANGELOG.md](./CHANGELOG.md).

### Safety note — external write tools

Tools invoked through this MCP server run against the app **without** the chat's
plan-approval UI that gates the in-app agent. The mitigations are:
(1) the connection itself is **user-approved** via the permission dialog raised
by `circuitry.connect`, and (2) most edits are revertible via `workflow.undo`.

## Configuration

### Config File

Location: `~/.circuitry/mcp-config.json`

```json
{
  "eserverUrl": "http://localhost:3030",
  "accessKey": "your-key-here",
  "configured": true
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `CIRCUITRY_ESERVER_URL` | Override EServer URL |
| `CIRCUITRY_ACCESS_KEY` | Override access key |

## Commands

```bash
# Run setup wizard
npx @circuitry-ide/mcp-server setup

# Check current configuration
npx @circuitry-ide/mcp-server status
```

## Troubleshooting

### "Cannot connect to EServer"

1. **Check EServer is running**: Look for the Circuitry icon in your system tray
2. **Start Circuitry Server**: Download from [circuitry.dev/download](https://www.circuitry.dev/download)
3. **Verify URL**: Run `npx @circuitry-ide/mcp-server status`

### "Invalid access key"

1. **Create new key**: Circuitry Server → Preferences → Generate New Access Key
2. **Re-run setup**: `npx @circuitry-ide/mcp-server setup`

### "No Circuitry browser client connected"

1. **Open Circuitry**: Make sure the Circuitry app is open
2. **Refresh**: Try refreshing the Circuitry page

## Development

```bash
# Clone and install
git clone https://github.com/circuitry-dev/circuitry-mcp-server.git
cd circuitry-mcp-server
npm install

# Build
npm run build

# Test locally
npx tsx src/index.ts setup
npx tsx src/index.ts status
```

To test local changes, point your MCP config to the built output:

```json
{
  "mcpServers": {
    "circuitry": {
      "command": "node",
      "args": ["/path/to/circuitry-mcp-server/dist/index.js"]
    }
  }
}
```

## License

This is **proprietary software**, provided so you can install and run it to connect your
AI tools to the Circuitry service. The source is published for transparency and
interoperability — it is **not** open-source, and viewing it grants no right to copy,
modify, redistribute, or build a competing product. You may download, install and run it
to use Circuitry; all other rights are reserved. See [LICENSE](./LICENSE) for the full
terms. "Circuitry" and the Circuitry logo are trade marks of Circuitry.

Use of the Circuitry service through this software is also governed by the
[Circuitry Terms of Service](https://www.circuitry.dev/terms).

## Links

- [Circuitry Website](https://www.circuitry.dev)
- [Download Circuitry Server](https://www.circuitry.dev/download)
- [Report Issues](https://github.com/circuitry-dev/circuitry-mcp-server/issues)