kicad-mcp-server/docs/ROUTER_ARCHITECTURE.md

Router Architecture Design

Overview

This document describes the router pattern implementation for the KiCAD MCP Server. The router reduces context window consumption by organizing 122+ tools into 8 discoverable categories, keeping only the most frequently used tools directly visible.

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
• add_net_class - Add 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:

{
  "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:

{
  "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:

{
  "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

Benefits

1. Context Efficiency: 70% reduction in tokens (~28K saved)
2. Better Organization: Tools grouped by function
3. Discoverability: Easy to find the right tool
4. Scalability: Can add unlimited tools without bloating context
5. Backwards Compatible: Existing Python commands still work

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