KiCAD-MCP-Server

# Router Architecture Design

> **⚠ Historical design document.** The gating half of this design was
> deliberately rolled back in 2026-03 and `execute_tool` was deleted in
> 2026-05. Nothing is hidden from the client today and no context is saved.
> What remains is a search/browse catalogue. Read
> [Status: discovery only](#status-discovery-only-no-context-reduction)
> below before treating anything here as current behaviour.

## Overview

This document describes the router pattern as originally designed for the
KiCAD MCP Server: organize the tools into discoverable categories, keep only
the most frequently used ones directly visible, and reduce context window
consumption by hiding the rest behind `execute_tool`.

Sections below describe that design. The **Status** section records which
parts are live.

## Architecture Layers

```
┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (Claude)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      KiCAD MCP Server                        │
│  ┌─────────────────────────────────────────────────────────┐│
│  │           DIRECT TOOLS (Always Visible - 12)            ││
│  │  • create_project    • open_project    • save_project   ││
│  │  • get_project_info  • place_component • move_component ││
│  │  • add_net           • route_trace     • get_board_info ││
│  │  • set_board_size    • add_board_outline • check_kicad_ui││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │               ROUTER TOOLS (Discovery - 4)              ││
│  │  • list_tool_categories   • get_category_tools          ││
│  │  • execute_tool           • search_tools                ││
│  └─────────────────────────────────────────────────────────┘│
│                              │                               │
│                              ▼                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │            ROUTED TOOLS (Hidden - 110+)                 ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   ││
│  │  │  board   │ │component │ │  export  │ │   drc    │   ││
│  │  │   tools  │ │  tools   │ │  tools   │ │  tools   │   ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘   ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   ││
│  │  │schematic │ │ library  │ │ routing  │ │footprint │   ││
│  │  │  tools   │ │  tools   │ │  tools   │ │  tools   │   ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

## Tool Categories

### Direct Tools (12 tools - always visible)

These cover the primary workflow (80%+ of use cases):

1. **Project Lifecycle** (4):
   - `create_project` - Create new KiCAD project
   - `open_project` - Open existing project
   - `save_project` - Save current project
   - `get_project_info` - Get project information

2. **Core PCB Operations** (6):
   - `place_component` - Place component on board
   - `move_component` - Move component to new position
   - `add_net` - Create a new net
   - `route_trace` - Route trace between points
   - `get_board_info` - Get board information
   - `set_board_size` - Set board dimensions

3. **Board Setup** (1):
   - `add_board_outline` - Add board outline

4. **UI Management** (1):
   - `check_kicad_ui` - Check if KiCAD UI is running

### Routed Categories (8+ categories, 110+ tools)

#### 1. `board` - Board Configuration & Layout (9 tools)

Setup and configuration operations.

**Tools:**

- `add_layer` - Add PCB layer
- `set_active_layer` - Set active layer
- `get_layer_list` - List all layers
- `add_mounting_hole` - Add mounting hole
- `add_board_text` - Add text to board
- `add_zone` - Add copper zone/pour
- `get_board_extents` - Get board boundaries
- `get_board_2d_view` - Get 2D visualization
- `launch_kicad_ui` - Launch KiCAD UI

#### 2. `component` - Advanced Component Operations (8 tools)

Beyond basic placement.

**Tools:**

- `rotate_component` - Rotate component
- `delete_component` - Delete component
- `edit_component` - Edit component properties
- `find_component` - Find component by reference/value
- `get_component_properties` - Get component properties
- `add_component_annotation` - Add component annotation
- `group_components` - Group components together
- `replace_component` - Replace component with another

#### 3. `export` - File Export & Manufacturing (8 tools)

Generate output files for fabrication and documentation.

**Tools:**

- `export_gerber` - Export Gerber files
- `export_pdf` - Export PDF
- `export_svg` - Export SVG
- `export_3d` - Export 3D model (STEP/STL/VRML/OBJ)
- `export_bom` - Export bill of materials
- `export_netlist` - Export netlist
- `export_position_file` - Export component positions
- `export_vrml` - Export VRML 3D model

#### 4. `drc` - Design Rules & Validation (9 tools)

Design rule checking and electrical validation.

**Tools:**

- `set_design_rules` - Configure design rules
- `get_design_rules` - Get current rules
- `run_drc` - Run design rule check
- `create_netclass` - Create a net class
- `assign_net_to_class` - Assign net to class
- `set_layer_constraints` - Set layer constraints
- `check_clearance` - Check clearance between items
- `get_drc_violations` - Get DRC violations

#### 5. `schematic` - Schematic Operations (9 tools)

Schematic editor operations.

**Tools:**

- `create_schematic` - Create new schematic
- `add_schematic_component` - Add component to schematic
- `add_wire` - Add wire connection
- `add_schematic_connection` - Connect component pins
- `add_schematic_net_label` - Add net label
- `connect_to_net` - Connect pin to net
- `get_net_connections` - Get net connections
- `generate_netlist` - Generate netlist

#### 6. `library` - Footprint Library Access (4 tools)

Search and browse footprint libraries.

**Tools:**

- `list_libraries` - List available libraries
- `search_footprints` - Search footprints
- `list_library_footprints` - List library footprints
- `get_footprint_info` - Get footprint details

#### 7. `routing` - Advanced Routing (3 tools)

Advanced routing operations beyond basic trace routing.

**Tools:**

- `add_via` - Add via
- `add_copper_pour` - Add copper pour

**Note:** `add_net` and `route_trace` are direct tools as they're core operations.

## Router Tools

### 1. `list_tool_categories`

**Description:** List all available tool categories with descriptions and tool counts.

**Parameters:** None

**Returns:**

```json
{
  "total_categories": 7,
  "total_tools": 47,
  "categories": [
    {
      "name": "board",
      "description": "Board configuration: layers, mounting holes, zones, visualization",
      "tool_count": 9
    }
    // ... more categories
  ]
}
```

### 2. `get_category_tools`

**Description:** Get detailed information about all tools in a specific category.

**Parameters:**

- `category` (string) - Category name from `list_tool_categories`

**Returns:**

```json
{
  "category": "export",
  "description": "File export for fabrication and documentation: Gerber, PDF, BOM, 3D models",
  "tools": [
    {
      "name": "export_gerber",
      "description": "Export Gerber files for PCB fabrication",
      "parameters": {
        /* zod schema */
      }
    }
    // ... more tools
  ]
}
```

### 3. `execute_tool`

**Description:** Execute a tool from any category.

**Parameters:**

- `tool_name` (string) - Tool name from `get_category_tools`
- `params` (object, optional) - Tool parameters

**Returns:** Tool execution result

### 4. `search_tools`

**Description:** Search for tools by keyword across all categories.

**Parameters:**

- `query` (string) - Search term (e.g., "gerber", "zone", "export")

**Returns:**

```json
{
  "query": "export",
  "count": 8,
  "matches": [
    {
      "category": "export",
      "tool": "export_gerber",
      "description": "Export Gerber files for PCB fabrication"
    }
    // ... more matches
  ]
}
```

## Implementation Files

### New Files to Create

1. **`src/tools/registry.ts`**
   - Tool category definitions
   - Tool metadata storage
   - Lookup maps (by name, by category)
   - Search functionality

2. **`src/tools/router.ts`**
   - Router tool implementations
   - `list_tool_categories` handler
   - `get_category_tools` handler
   - `execute_tool` handler
   - `search_tools` handler

3. **`src/tools/direct.ts`**
   - Export direct tool definitions
   - Keep existing tool implementations but organized

### Modified Files

1. **`src/server.ts`** or **`src/kicad-server.ts`**
   - Register only direct tools + router tools
   - Remove registration of routed tools
   - Tools still callable via `execute_tool`

## Migration Strategy

### Phase 1: Create Infrastructure

1. Create `registry.ts` with all tool definitions
2. Create `router.ts` with router tools
3. Create `direct.ts` with direct tool list

### Phase 2: Update Server

1. Modify server registration to use direct + router only
2. Keep all existing tool handlers intact
3. Route through `execute_tool`

### Phase 3: Testing

1. Test direct tools work as before
2. Test router tools (list/get/execute/search)
3. Test routed tools via `execute_tool`

### Phase 4: Optimization (Optional)

1. Add caching for tool lookups
2. Add tool usage analytics
3. Implement intelligent tool suggestions

## Status: discovery only (no context reduction)

> **This document describes the original design. Part of it was deliberately
> abandoned — read this section before relying on the claims above.**
>
> The router no longer gates which tools reach the client, and there is no
> `execute_tool`. Every tool is registered directly in `registerAll()`
> (`src/server.ts`) and appears in `tools/list`, so **no context reduction
> happens**. What survives is a browse/search catalogue over the registry:
> `list_tool_categories`, `get_category_tools`, `search_tools`.
>
> History:
>
> - `c656000` implemented the full pattern, `search_tools` + `execute_tool`.
> - `3d9497e` (2026-03-11) disabled it, with the reason recorded in the code:
>   _"causes Claude to hallucinate tool schemas via search_tools/execute_tool.
>   All tools are registered directly below and are immediately visible."_
> - `963a39c` (2026-05-03) deleted `execute_tool` and re-enabled the three
>   remaining read-only discovery tools.
>
> So this is a considered trade — correctness over token savings — not an
> unfinished feature or a regression. Indirect execution made the model
> invent schemas it had not been shown; direct registration does not.

## Benefits of the discovery catalogue

1. **Better Organization**: Tools grouped by function
2. **Discoverability**: `search_tools` finds a tool by keyword without
   scanning the full list by hand
3. **Backwards Compatible**: Existing Python commands still work

## Benefits of the original gated design (not currently realised)

1. **Context Efficiency**: ~70% reduction in tokens (~28K saved)
2. **Scalability**: Add unlimited tools without bloating context

Reinstating these means solving the schema-hallucination problem that caused
the rollback. Anyone attempting it should start from `3d9497e`.

## Usage Examples

### Example 1: User Wants to Export Gerbers

```
User: "Export gerbers for this board"

Claude's workflow:
1. Sees "export" keyword
2. Calls search_tools({ query: "gerber" })
   → Returns: { category: "export", tool: "export_gerber", ... }
3. Calls execute_tool({
     tool_name: "export_gerber",
     params: { outputDir: "./gerbers" }
   })
   → Returns: { success: true, files: [...] }

Claude: "I've exported the Gerber files to ./gerbers/"
```

### Example 2: User Wants to Place Component

```
User: "Add a 0805 resistor at position 10,20"

Claude's workflow:
1. Sees place_component in direct tools
2. Calls place_component({
     componentId: "R_0805",
     position: { x: 10, y: 20, unit: "mm" }
   })
   → Returns: { success: true, reference: "R1" }

Claude: "Added R1 (0805 resistor) at position (10, 20) mm"
```

### Example 3: User Wants Unknown Operation

```
User: "Check the board for design rule violations"

Claude's workflow:
1. Uncertain which tool to use
2. Calls search_tools({ query: "design rule violations" })
   → Returns: { category: "drc", tool: "run_drc", ...}
3. Calls get_category_tools({ category: "drc" })
   → Returns full DRC category tools with parameters
4. Calls execute_tool({
     tool_name: "run_drc",
     params: {}
   })
   → Returns: DRC results

Claude: "I ran the design rule check. Found 3 violations: ..."
```

## Success Metrics

- ✅ Token usage: ~12K (vs 40K before)
- ✅ Tool discovery time: <2 calls (search → execute)
- ✅ User experience: Unchanged (seamless)
- ✅ Maintainability: Improved (organized categories)
- ✅ Scalability: Can add 100+ more tools easily