kicad-mcp-server/docs/ROUTER_QUICK_START.md

Router Quick Start Guide

What is the Router?

The KiCAD MCP Server now includes an intelligent tool router that organizes 59 tools into 7 discoverable categories. This reduces AI context usage by up to 70% while maintaining full access to all functionality.

How It Works

Instead of loading all 59 tool schemas into every conversation, Claude now sees:

• 12 direct tools for high-frequency operations (always visible)
• 4 router tools for discovering and executing the other 47 tools

When you ask Claude to do something (like "export gerber files"), it will:

1. Search for relevant tools using search_tools
2. Find the export_gerber tool in the "export" category
3. Execute it via execute_tool with your parameters
4. Return the results

You don't need to change how you interact with Claude - the discovery happens automatically!

Tool Categories

The 47 routed tools are organized into these categories:

1. board (9 tools)

Board configuration: layers, mounting holes, zones, visualization

• add_layer, set_active_layer, get_layer_list
• add_mounting_hole, add_board_text
• add_zone, get_board_extents, get_board_2d_view
• launch_kicad_ui

2. component (8 tools)

Advanced component operations: edit, delete, search, group, annotate

• rotate_component, delete_component, edit_component
• find_component, get_component_properties
• add_component_annotation, group_components, replace_component

3. export (8 tools)

File export for fabrication and documentation

• export_gerber, export_pdf, export_svg, export_3d
• export_bom, export_netlist, export_position_file, export_vrml

4. drc (8 tools)

Design rule checking and electrical validation

• set_design_rules, get_design_rules, run_drc
• add_net_class, assign_net_to_class, set_layer_constraints
• check_clearance, get_drc_violations

5. schematic (8 tools)

Schematic operations: create, add components, wire connections

• create_schematic, add_schematic_component, add_wire
• add_schematic_connection, add_schematic_net_label
• connect_to_net, get_net_connections, generate_netlist

6. library (4 tools)

Footprint library access and search

• list_libraries, search_footprints
• list_library_footprints, get_footprint_info

7. routing (2 tools)

Advanced routing operations

• add_via, add_copper_pour

Direct Tools (Always Available)

These 12 tools are always visible for common operations:

Project Lifecycle:

• create_project, open_project, save_project, get_project_info

Core PCB Operations:

• place_component, move_component
• add_net, route_trace
• get_board_info, set_board_size
• add_board_outline

UI Management:

• check_kicad_ui

Router Tools

list_tool_categories

Browse all available tool categories.

Example:

Claude, what tool categories are available?

get_category_tools

View all tools in a specific category.

Example:

Show me all export tools available.

search_tools

Find tools by keyword.

Example:

Search for tools related to "gerber" or "mounting holes"

execute_tool

Execute any routed tool with parameters.

Example:

Execute the export_gerber tool with outputDir set to ./fabrication

Usage Examples

Natural Interaction (Recommended)

Just ask Claude what you want - it handles discovery automatically:

"Export gerber files to ./output"
"Add a mounting hole at x=10, y=10"
"Run a design rule check"
"Create a copper pour on the ground layer"

Manual Discovery (Optional)

You can also browse tools explicitly:

"List all tool categories"
"What export tools are available?"
"Search for DRC tools"

Benefits

1. Reduced Context Usage: 70% less AI context consumed per conversation
2. Organized Tools: Logical categorization makes tools easy to find
3. Seamless Experience: Works transparently - no changes to how you interact
4. Extensible: Easy to add new tools and categories
5. Backwards Compatible: All existing tools still work

Technical Details

• Registry: src/tools/registry.ts - Tool categorization and lookup
• Router: src/tools/router.ts - Discovery and execution implementation
• Server Integration: src/server.ts - Router tools registered at startup

For implementation details, see:

• ROUTER_ARCHITECTURE.md - Design specification
• ROUTER_IMPLEMENTATION_STATUS.md - Current status
• TOOL_INVENTORY.md - Complete tool catalog

Token Savings

Before Router:

• 59 tools × ~700 tokens each = ~42K tokens per conversation

After Router (Current - Phase 1):

• 12 direct tools + 4 router tools = 16 tools visible
• Still ~42K tokens (all tools still registered for backwards compatibility)

After Phase 2 (Optional Optimization):

• Only 16 tools visible to Claude
• ~12K tokens per conversation
• 70% reduction in context usage

Phase 1 is complete and functional. Phase 2 (hiding routed tools) is optional and can be implemented when desired.