# EasyEDA Pro MCP Server

AI-powered autonomous hardware design for EasyEDA Pro. Design complete electronic products — from schematic to manufacturing files — using natural language.

## Architecture

```
AI Agent (Claude Code / any MCP client)
    │ MCP (stdio)
    ▼
MCP Server (72 tools)  ──── Claude / Gemini (AI-assisted design)
    │                  ──── JLCPCB/LCSC (component search, no API key needed)
    │ WebSocket :18601
    ▼
Bridge Extension (267 methods)
    │
    ▼
EasyEDA Pro Desktop
```

**Two-component system:**
- **MCP Server** (Node.js) — 72 tools across 3 layers, runs locally
- **Bridge Extension** (.eext) — runs inside EasyEDA Pro, routes commands to the `eda.*` API

## Features

### Layer 1: Granular Tools (48 tools)
Direct, deterministic control over every aspect of EasyEDA Pro:

| Category | Tools | Examples |
|----------|-------|---------|
| **Project** | 5 | `create_project`, `open_project`, `save_document` |
| **Schematic** | 17 | `place_component`, `draw_wire`, `place_net_flag`, `auto_layout` |
| **PCB** | 15 | `draw_trace`, `place_via`, `create_copper_pour`, `manage_pcb_layers` |
| **Library** | 6 | `search_component`, `get_component_by_lcsc`, `search_footprint` |
| **DRC** | 4 | `run_schematic_drc`, `run_pcb_drc`, `configure_drc` |
| **Manufacturing** | 3 | `generate_bom`, `generate_netlist`, `export_document` |
| **LCSC/JLCPCB** | 4 | `lcsc_search`, `lcsc_get_details`, `lcsc_check_stock`, `lcsc_browse_category` |
| **Editor** | 4 | `get_editor_state`, `capture_screenshot`, `zoom_to_region` |

### Layer 2: Workflow Tools (8 tools)
Multi-step operations combined into single calls:

- `create_project_with_board` — project + schematic + PCB + board in one step
- `place_and_connect` — place component and wire pins to nets
- `schematic_to_pcb_flow` — DRC → import changes → setup layers → ratline
- `full_drc` — run both schematic and PCB DRC with unified report
- `export_manufacturing` — BOM + netlist + gerbers in one call
- `setup_power_rails` — place VCC/GND net flags across the schematic
- `component_swap` — replace component preserving position
- `add_decoupling` — add bypass caps near IC power pins

### Layer 3: AI-Assisted Tools (6 tools)
LLM-powered design intelligence (supports Claude and Gemini):

- `design_circuit` — *"5V 3A buck converter from 12V"* → complete schematic
- `select_components` — *"low-noise op-amp, GBW > 10MHz, SOIC-8"* → ranked recommendations
- `review_design` — analyze schematic/PCB for errors, EMC issues, thermal problems
- `layout_pcb_intelligent` — suggest component placement based on signal flow
- `implement_protocol` — *"USB-C with PD sink 20V"* → full implementation
- `design_hardware_ui` — *"OLED display, 3 buttons, rotary encoder"* → driving circuits

### JLCPCB/LCSC Component Search
**No API key required.** Uses the public JLCPCB API (same endpoints used by KiCad plugins and other open-source tools):
- Search by keyword, MPN, or description
- Filter by JLCPCB basic/extended library, manufacturer, package, category
- Get full component details with pricing tiers and stock levels
- Browse component categories
- Batch stock checking

### Engineering Knowledge Base (~350KB)
Dense reference material loaded into AI context for professional-grade design decisions:

- **Analog design** — op-amps, filters, noise analysis, feedback stability
- **Audio engineering** — SNR, THD, dynamic range, SINAD, ENOB, gain staging, DAC/ADC selection
- **Power supply** — buck/boost/LDO design with formulas, loop compensation, inductor sizing
- **PCB layout** — component placement, return current paths, decoupling strategy
- **PCB routing** — trace width rules (IPC-2221), differential pairs, high-speed routing, via rules, power/ground routing, BGA fan-out, EMC routing, common mistakes
- **PCB stackups** — JLCPCB stackup specs (JLC7628/JLC2313), impedance calculations
- **DRC rules** — preset rules for USB, Ethernet, DDR, HDMI, high-voltage
- **Signal integrity** — impedance control, length matching, termination strategies
- **EMC/EMI** — ESD protection, filtering, shielding, conducted emissions
- **Thermal design** — thermal vias, copper spreading, derating rules
- **Protocols** — USB (2.0/3.0/C/PD), Ethernet (10/100/1000), I2S, I2C, SPI, UART/RS485
- **MCUs** — STM32, ESP32, RP2040, nRF52 (minimum circuits, LCSC part numbers)
- **Hardware UI/UX** — displays, buttons, encoders, LEDs, touch, haptic feedback
- **Common components** — 100+ go-to parts with LCSC C-numbers
- **Design patterns** — reusable sub-circuits (USB-C, crystal, reset, LDO, buck, I2C bus, etc.)
- **Standards** — IPC-2221, JLCPCB manufacturing limits, clearance/creepage tables

## Quick Start

### Prerequisites
- Node.js 20+
- EasyEDA Pro desktop app (v2.3.0+)

### Installation

```bash
git clone https://github.com/teileelektronik/easyeda-mcp.git
cd easyeda-mcp
npm install
npm run build
```

### Install Bridge Extension

Build the bridge:
```bash
cd src/bridge
npm install
npm run build
cd ../..
```

Install in EasyEDA Pro:
1. **V2:** Top Menu → Settings → Extensions → Extension Manager → Import Extensions
2. **V3 (Beta):** Top Menu → Advanced → Extension Manager → Import
3. Select the `src/bridge/` directory
4. Click **AI Bridge: Connect** in the top menu bar

### Configure MCP Server

Create `.mcp.json` in your project directory (or add to Claude Code settings):

```json
{
  "mcpServers": {
    "easyeda": {
      "command": "node",
      "args": ["/path/to/easyeda-mcp/dist/server/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `EASYEDA_BRIDGE_PORT` | No | WebSocket port (default: 18601) |
| `ANTHROPIC_API_KEY` | For Layer 3 | Use Claude for AI-assisted tools |
| `GEMINI_API_KEY` | For Layer 3 | Use Gemini for AI-assisted tools (alternative to Claude) |

**No LCSC/JLCPCB API key needed** — component search uses public endpoints.

If both `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` are set, Claude is used (takes priority).

## Usage Examples

### Create a project and place components
```
> Create a new project called "Sensor Board" with a schematic and PCB

> Search for STM32F411 on JLCPCB and place it at the center of the schematic

> Add 100nF decoupling caps on every power pin, connect to GND
```

### Design a complete circuit
```
> Design a USB-C powered ESP32-S3 board with:
> - USB-C with PD sink (5V/9V)
> - 3.3V LDO from VBUS
> - SPI TFT display connector
> - I2S DAC (PCM5102A) for audio output
> - 3 tactile buttons with debouncing
> - WS2812B RGB LED
```

### Component search
```
> Search JLCPCB for "low noise LDO 3.3V" basic parts only

> Get details and pricing for C51118

> Check stock for C8734, C14663, C1525, C25744
```

### Review and export
```
> Run full DRC on both schematic and PCB

> Review the design for EMC and signal integrity issues

> Review the PCB routing — check trace widths, impedance, return current paths

> Export manufacturing files (gerbers, BOM, pick-and-place)
```

## Project Structure

```
easyeda-mcp/
├── src/
│   ├── server/              # MCP Server
│   │   ├── index.ts         # Entry point
│   │   ├── bridge.ts        # WebSocket connection manager
│   │   ├── tools/           # 72 MCP tool definitions
│   │   │   ├── project.ts        # Project management
│   │   │   ├── schematic.ts      # Schematic management
│   │   │   ├── schematic-draw.ts # Component placement, wiring
│   │   │   ├── pcb.ts            # PCB management
│   │   │   ├── pcb-draw.ts       # Traces, vias, pours
│   │   │   ├── library.ts        # Component library search
│   │   │   ├── drc.ts            # Design rule checks
│   │   │   ├── manufacturing.ts  # BOM, netlist, export
│   │   │   ├── editor.ts         # View control, screenshots
│   │   │   ├── lcsc.ts           # JLCPCB/LCSC search (no auth)
│   │   │   ├── workflows.ts      # Layer 2 compound tools
│   │   │   └── ai-assisted.ts    # Layer 3 LLM tools
│   │   ├── lcsc/            # JLCPCB/LCSC API client
│   │   └── llm/             # Claude + Gemini integration
│   ├── bridge/              # EasyEDA Pro extension
│   │   ├── src/index.ts     # 267-method bridge
│   │   └── extension.json
│   └── shared/              # JSON-RPC protocol types
├── knowledge/               # Engineering knowledge base (~350KB)
│   ├── analog-design.md
│   ├── audio-engineering.md
│   ├── power-supply.md
│   ├── pcb-layout.md
│   ├── pcb-routing.md       # Comprehensive routing reference
│   ├── pcb-stackups.md      # JLCPCB stackup specs
│   ├── pcb-drc-rules.md     # Protocol-specific DRC presets
│   ├── signal-integrity.md
│   ├── emc-emi.md
│   ├── thermal-design.md
│   ├── common-components.md # 100+ parts with LCSC C-numbers
│   ├── design-patterns.md   # Reusable sub-circuits
│   ├── hardware-ui-ux.md
│   ├── standards-safety.md
│   ├── protocols/           # USB, Ethernet, I2S, I2C, SPI, UART
│   └── mcus/                # STM32, ESP32, RP2040, nRF52
├── .mcp.json                # Claude Code MCP configuration
└── .env.example
```

## How It Works

1. **MCP Server** starts a WebSocket server on `localhost:18601`
2. **Bridge Extension** inside EasyEDA Pro connects to it via `eda.sys_WebSocket`
3. AI agent calls MCP tools (e.g., `place_component`)
4. MCP Server sends JSON-RPC request over WebSocket → Bridge
5. Bridge routes to the corresponding `eda.*` API call (267 methods registered)
6. Result flows back: Bridge → WebSocket → MCP Server → AI agent

Layer 3 tools add an intelligence layer: they send the task + relevant engineering knowledge to Claude/Gemini, which plans a sequence of Layer 1/2 tool calls, executes each step with verification, and recovers from errors.

## License

Apache 2.0