style: apply Prettier formatting to TS/JS/JSON/MD files
Add Prettier as a dev dependency with .prettierrc.json config and .prettierignore. Hook added via mirrors-prettier in pre-commit config. All TypeScript, JSON, Markdown, and YAML files auto-formatted. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Eugene Mikhantyev
@@ -1,353 +1,383 @@
|
||||
# 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:**
|
||||
```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
|
||||
|
||||
## 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
|
||||
# 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:**
|
||||
|
||||
```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
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user