kicad-mcp-server/docs/UI_AUTO_LAUNCH.md

# KiCAD UI Auto-Launch Feature

Automatically detect and launch KiCAD UI when needed, providing seamless visual feedback for PCB design operations.

---

## 🎯 Overview

The KiCAD MCP server can now:

- ✅ Detect if KiCAD UI is running
- ✅ Launch KiCAD automatically when needed
- ✅ Open projects directly in the UI
- ✅ Work across Linux, macOS, and Windows

---

## 🚀 Quick Start

### Enable Auto-Launch

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "KICAD_AUTO_LAUNCH": "true"
      }
    }
  }
}
```

### Manual Control (Default)

Without `KICAD_AUTO_LAUNCH=true`, you manually control when KiCAD launches using the new MCP tools.

---

## 🛠️ New MCP Tools

### 1. `check_kicad_ui`

Check if KiCAD is currently running.

**Parameters:** None

**Example:**

```typescript
{
  "command": "check_kicad_ui",
  "params": {}
}
```

**Response:**

```json
{
  "success": true,
  "running": true,
  "processes": [
    {
      "pid": "12345",
      "name": "pcbnew",
      "command": "/usr/bin/pcbnew /tmp/project.kicad_pcb"
    }
  ],
  "message": "KiCAD is running",
  "backend": "ipc",
  "realtime_sync": true,
  "ipc_connected": true
}
```

### 2. `launch_kicad_ui`

Launch KiCAD UI, optionally with a project file.

**Parameters:**

- `projectPath` (optional): Path to `.kicad_pcb` file to open
- `autoLaunch` (optional): Whether to launch if not running (default: true)

**Example:**

```typescript
{
  "command": "launch_kicad_ui",
  "params": {
    "projectPath": "/tmp/mcp_demo/New_Project.kicad_pcb"
  }
}
```

**Response:**

```json
{
  "success": true,
  "running": true,
  "launched": true,
  "message": "KiCAD launched successfully",
  "project": "/tmp/mcp_demo/New_Project.kicad_pcb",
  "processes": [...],
  "backend": "ipc",
  "realtime_sync": true,
  "ipc_connected": true
}
```

If IPC is not enabled, no board is open, or the IPC connection is otherwise not
available yet, these status fields report `backend: "swig"`,
`realtime_sync: false`, and `ipc_connected: false`.

### IPC Reconnect After Launch

When the MCP server starts before KiCAD, it may initially fall back to the SWIG
backend. `launch_kicad_ui` and `check_kicad_ui` now refresh the live backend
status after KiCAD is running, and normal IPC-capable board tools retry IPC on
their next call. Agents do not need to switch to special `ipc_*` tools; they can
retry standard tools such as `get_board_info`, `get_layer_list`,
`get_component_list`, `get_nets_list`, or `query_traces`.

---

## 🔄 Workflow Examples

### Example 1: Manual Launch

```
User: "Check if KiCAD is running"
Claude: Uses check_kicad_ui → "KiCAD is not running"

User: "Launch it with the demo project"
Claude: Uses launch_kicad_ui → KiCAD opens with project loaded!
```

### Example 2: Auto-Launch Mode

With `KICAD_AUTO_LAUNCH=true`:

```
User: "Create a new Arduino shield PCB"
Claude:
  1. Creates project
  2. Detects KiCAD not running
  3. Automatically launches KiCAD with the new project
  4. You see the board in real-time as it's designed!
```

### Example 3: Side-by-Side Design

```
┌────────────────────────────────────────────────────────┐
│ Workflow: AI-Assisted PCB Design                      │
├────────────────────────────────────────────────────────┤
│                                                        │
│  1. User: "Create a 100mm square board"               │
│     → Claude creates project                          │
│     → KiCAD auto-launches if not running             │
│                                                        │
│  2. User: "Add 4 mounting holes at corners"           │
│     → Claude adds holes                               │
│     → KiCAD detects file change, prompts to reload   │
│     → User clicks "Yes" → sees holes appear!          │
│                                                        │
│  3. User: "Perfect! Now add a circular outline..."    │
│     → Iterative design continues...                   │
│                                                        │
└────────────────────────────────────────────────────────┘
```

---

## ⚙️ Configuration Options

### Environment Variables

| Variable            | Default     | Description                    |
| ------------------- | ----------- | ------------------------------ |
| `KICAD_AUTO_LAUNCH` | `false`     | Auto-launch KiCAD when needed  |
| `KICAD_EXECUTABLE`  | auto-detect | Override KiCAD executable path |

### Custom Executable Path

If KiCAD is installed in a non-standard location:

```json
{
  "env": {
    "KICAD_AUTO_LAUNCH": "true",
    "KICAD_EXECUTABLE": "/opt/kicad/bin/pcbnew"
  }
}
```

---

## 🔍 How It Works

### Process Detection

**Linux:**

```bash
pgrep -f "pcbnew|kicad"
```

**macOS:**

```bash
pgrep -f "KiCad|pcbnew"
```

**Windows:**

```powershell
tasklist /FI "IMAGENAME eq pcbnew.exe"
```

### Auto-Discovery of Executable

The system searches for KiCAD in:

**Linux:**

- `/usr/bin/pcbnew`
- `/usr/local/bin/pcbnew`
- `/usr/bin/kicad`

**macOS:**

- `/Applications/KiCad/KiCad.app/Contents/MacOS/kicad`
- `/Applications/KiCad/pcbnew.app/Contents/MacOS/pcbnew`

**Windows:**

- `C:/Program Files/KiCad/9.0/bin/pcbnew.exe`
- `C:/Program Files/KiCad/8.0/bin/pcbnew.exe`

### Launch Process

1. Check if KiCAD is already running
2. If not, find executable path
3. Spawn process with optional project path
4. Wait up to 5 seconds for process to start
5. Verify process is running
6. Return status to MCP client

---

## 💡 Use Cases

### 1. Beginner-Friendly Workflow

User doesn't need to know how to launch KiCAD manually:

```
User: "Help me design a simple LED board"
Claude: [Auto-launches KiCAD, creates project, designs board]
```

### 2. Streamlined Iteration

For rapid prototyping with visual feedback:

```
1. Claude creates board → KiCAD opens
2. User sees board, requests changes
3. Claude modifies → KiCAD reloads
4. Repeat until satisfied
```

### 3. Batch Processing

Process multiple designs without manual intervention:

```python
for design in designs:
    create_project(design)
    # KiCAD auto-launches and loads each one
    add_components(design)
    route_board(design)
    export_gerbers(design)
```

---

## 🐛 Troubleshooting

### KiCAD Doesn't Launch

**Check executable path:**

```bash
# Linux/macOS
which pcbnew

# Windows
where pcbnew.exe
```

**Override if needed:**

```json
{
  "env": {
    "KICAD_EXECUTABLE": "/path/to/pcbnew"
  }
}
```

### Process Detection Fails

**Manual check:**

```bash
# Linux/macOS
ps aux | grep kicad

# Windows
tasklist | findstr kicad
```

**Verify permissions:**

- Ensure user can execute `pgrep` (Linux/macOS)
- Ensure user can execute `tasklist` (Windows)

### Auto-Launch Doesn't Work

1. Check `KICAD_AUTO_LAUNCH` is set to `"true"` (string, not boolean)
2. Verify KiCAD is in PATH or set `KICAD_EXECUTABLE`
3. Check MCP server logs for errors
4. Try manual launch first: `launch_kicad_ui`

---

## 📊 Implementation Details

### Files Modified/Created

**New Files:**

- `python/utils/kicad_process.py` - Process management utilities
- `src/tools/ui.ts` - MCP tool definitions
- `docs/UI_AUTO_LAUNCH.md` - This documentation

**Modified Files:**

- `python/kicad_interface.py` - Added UI command handlers
- `src/server.ts` - Registered UI tools

### API Reference

**Python:**

```python
from utils.kicad_process import KiCADProcessManager, check_and_launch_kicad

# Check if running
manager = KiCADProcessManager()
is_running = manager.is_running()

# Launch KiCAD
success = manager.launch(project_path="/path/to/file.kicad_pcb")

# Get process info
processes = manager.get_process_info()

# High-level helper
result = check_and_launch_kicad(
    project_path=Path("/path/to/file.kicad_pcb"),
    auto_launch=True
)
```

**MCP Tools:**

```typescript
// Check status
await callKicadScript("check_kicad_ui", {});

// Launch
await callKicadScript("launch_kicad_ui", {
  projectPath: "/path/to/project.kicad_pcb",
  autoLaunch: true,
});
```

---

## 🔮 Future Enhancements

### Planned Features

- **Window Management:** Bring KiCAD to front, minimize/maximize
- **Multi-Instance:** Handle multiple KiCAD instances
- **Status Notifications:** Push notifications when KiCAD state changes
- **Auto-Close:** Option to close KiCAD after operations complete

### IPC Mode

When KiCAD is running with IPC enabled:

```
KiCAD runs in background → MCP connects or reconnects via IPC → Real-time updates
No file reloading needed! Changes appear instantly.
```

---

## 📝 Summary

**Before this feature:**

```
User manually launches KiCAD
User manually opens project
Claude makes changes
User manually reloads
```

**After this feature:**

```
User: "Design a board"
→ KiCAD auto-launches with project
→ Changes appear (with quick reload)
→ Seamless AI-assisted design!
```

---

**Last Updated:** 2025-10-26
**Version:** 2.0.0-alpha.1
**Status:** ✅ Production Ready