Update repository with project files and documentation
- Added comprehensive documentation (BUILD_AND_TEST, CLIENT_CONFIG, KNOWN_ISSUES, ROADMAP, etc.) - Updated core functionality for board outline, size, and utilities - Added new tools for project, routing, schematic, and UI management - Included TypeScript SDK with full MCP implementation - Updated configuration examples for all platforms - Added changelog and status tracking - Improved Python utilities with KiCAD process management - Enhanced resource helpers and server capabilities 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
KiCAD MCP Bot
399
docs/UI_AUTO_LAUNCH.md
Normal file
399
docs/UI_AUTO_LAUNCH.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# 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"
|
||||
}
|
||||
```
|
||||
|
||||
### 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": [...]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 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
|
||||
- **IPC Integration:** Seamless integration with IPC backend
|
||||
- **Status Notifications:** Push notifications when KiCAD state changes
|
||||
- **Auto-Close:** Option to close KiCAD after operations complete
|
||||
|
||||
### IPC Mode (Coming Weeks 2-3)
|
||||
|
||||
When IPC backend is fully implemented:
|
||||
```
|
||||
KiCAD runs in background → MCP connects 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
|
||||
Reference in New Issue
Block a user