KiCAD-MCP-Server

# JLCPCB Parts Integration Plan **Goal:** Enable AI-driven component selection using JLCPCB's assembly parts library with real pricing and availability **Status:** Planning Phase **Estimated Effort:** 3-4 days **Priority:** Week 2 Priority 3 (after Component Libraries + Routing) --- ## Overview Integrate JLCPCB's SMT assembly parts library (~100k+ parts) into the KiCAD MCP server, enabling: - Component search by specifications (e.g., "10k resistor 0603 1%") - Automatic part selection optimized for cost (prefer Basic parts) - Real stock and pricing information - Mapping JLCPCB parts to KiCAD footprints --- ## Architecture ### Data Flow ``` ┌──────────────────────────────────────────────────┐ │ JLCPCB API (https://jlcpcb.com/external/...) │ │ - Requires API key/secret │ │ - Returns: ~100k parts with specs/pricing │ └───────────────────┬──────────────────────────────┘ │ Download (once, then updates) ▼ ┌──────────────────────────────────────────────────┐ │ SQLite Database (local cache) │ │ - components table │ │ - manufacturers table │ │ - categories table │ │ - Fast parametric search │ └───────────────────┬──────────────────────────────┘ │ Search/query ▼ ┌──────────────────────────────────────────────────┐ │ JLCPCB Parts Manager (Python) │ │ - search_parts(specs) │ │ - get_part_info(lcsc_number) │ │ - map_to_footprint(package) │ │ - suggest_alternatives(part) │ └───────────────────┬──────────────────────────────┘ │ MCP Tools ▼ ┌──────────────────────────────────────────────────┐ │ MCP Tools (TypeScript) │ │ - search_jlcpcb_parts │ │ - get_jlcpcb_part │ │ - place_component (enhanced) │ └──────────────────────────────────────────────────┘ ``` ### File Structure ``` python/commands/ ├── jlcpcb.py # JLCPCB API client └── jlcpcb_parts.py # Parts database manager data/ ├── jlcpcb_parts.db # SQLite cache (gitignored) └── footprint_mappings.json # Package → KiCAD footprint mapping src/tools/ └── jlcpcb.ts # MCP tool definitions docs/ └── JLCPCB_INTEGRATION.md # User documentation ``` --- ## Implementation Phases ### Phase 1: JLCPCB API Client (Day 1) **File:** `python/commands/jlcpcb.py` **Features:** - Authenticate with JLCPCB API (requires user-provided key/secret) - Download parts database (paginated, ~100k parts) - Handle rate limiting and retries - Save to SQLite database **API Endpoints:** ```python # Get auth token POST https://jlcpcb.com/external/genToken { "appKey": "YOUR_KEY", "appSecret": "YOUR_SECRET" } # Fetch parts (paginated) POST https://jlcpcb.com/external/component/getComponentInfos Headers: { "externalApiToken": "TOKEN" } Body: { "lastKey": "PAGINATION_KEY" } # Optional, for next page ``` **Database Schema:** ```sql CREATE TABLE components ( lcsc TEXT PRIMARY KEY, -- "C12345" category TEXT, -- "Resistors" subcategory TEXT, -- "Chip Resistor - Surface Mount" mfr_part TEXT, -- "RC0603FR-0710KL" package TEXT, -- "0603" solder_joints INTEGER, -- 2 manufacturer TEXT, -- "YAGEO" library_type TEXT, -- "Basic" or "Extended" description TEXT, -- "10kΩ ±1% 0.1W" datasheet TEXT, -- URL stock INTEGER, -- 15000 price_json TEXT, -- JSON array of price breaks last_updated INTEGER -- Unix timestamp ); CREATE INDEX idx_category ON components(category, subcategory); CREATE INDEX idx_package ON components(package); CREATE INDEX idx_manufacturer ON components(manufacturer); CREATE INDEX idx_library_type ON components(library_type); ``` **Environment Variables:** ```bash # ~/.bashrc or .env export JLCPCB_API_KEY="your_key_here" export JLCPCB_API_SECRET="your_secret_here" ``` **Python Implementation Outline:** ```python class JLCPCBClient: def __init__(self, api_key: str, api_secret: str): self.api_key = api_key self.api_secret = api_secret self.token = None def authenticate(self) -> str: """Get auth token from JLCPCB API""" def fetch_parts_page(self, last_key: Optional[str] = None) -> dict: """Fetch one page of parts (paginated)""" def download_full_database(self, db_path: str, progress_callback=None): """Download entire parts library to SQLite""" def update_database(self, db_path: str): """Incremental update (fetch only new/changed parts)""" ``` --- ### Phase 2: Parts Database Manager (Day 2) **File:** `python/commands/jlcpcb_parts.py` **Features:** - Initialize/load SQLite database - Parametric search (resistance, capacitance, voltage, etc.) - Filter by library type (Basic/Extended) - Sort by price, stock, or popularity - Map package names to KiCAD footprints **Python Implementation Outline:** ```python class JLCPCBPartsManager: def __init__(self, db_path: str = "data/jlcpcb_parts.db"): self.conn = sqlite3.connect(db_path) def search_parts( self, query: str = None, # Free-text search category: str = None, # "Resistors" package: str = None, # "0603" library_type: str = None, # "Basic" only manufacturer: str = None, # "YAGEO" in_stock: bool = True, # Only parts with stock > 0 limit: int = 20 ) -> List[dict]: """Search parts with filters""" def get_part_info(self, lcsc_number: str) -> dict: """Get detailed info for specific part""" def map_package_to_footprint(self, package: str) -> List[str]: """Map JLCPCB package name to KiCAD footprint(s)""" # Example: "0603" → ["Resistor_SMD:R_0603_1608Metric", # "Capacitor_SMD:C_0603_1608Metric"] def parse_description(self, description: str, category: str) -> dict: """Extract parameters from description text""" # Example: "10kΩ ±1% 0.1W" → {resistance: "10k", tolerance: "1%", power: "0.1W"} def suggest_alternatives(self, lcsc_number: str, limit: int = 5) -> List[dict]: """Find similar parts (cheaper, more stock, Basic instead of Extended)""" ``` **Package to Footprint Mapping:** ```json { "0402": [ "Resistor_SMD:R_0402_1005Metric", "Capacitor_SMD:C_0402_1005Metric", "LED_SMD:LED_0402_1005Metric" ], "0603": [ "Resistor_SMD:R_0603_1608Metric", "Capacitor_SMD:C_0603_1608Metric", "LED_SMD:LED_0603_1608Metric" ], "0805": [ "Resistor_SMD:R_0805_2012Metric", "Capacitor_SMD:C_0805_2012Metric" ], "SOT-23": [ "Package_TO_SOT_SMD:SOT-23", "Package_TO_SOT_SMD:SOT-23-3" ], "SOIC-8": [ "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm" ] } ``` --- ### Phase 3: MCP Tools Integration (Day 3) **File:** `src/tools/jlcpcb.ts` **New MCP Tools:** #### 1. `search_jlcpcb_parts` Search JLCPCB parts library by specifications. ```typescript { name: "search_jlcpcb_parts", description: "Search JLCPCB assembly parts by specifications", inputSchema: { type: "object", properties: { query: { type: "string", description: "Free-text search (e.g., '10k resistor 0603')" }, category: { type: "string", description: "Category filter (e.g., 'Resistors', 'Capacitors')" }, package: { type: "string", description: "Package filter (e.g., '0603', 'SOT-23')" }, library_type: { type: "string", enum: ["Basic", "Extended", "All"], description: "Filter by library type (Basic = free assembly)" }, in_stock: { type: "boolean", default: true, description: "Only show parts with available stock" }, limit: { type: "number", default: 20, description: "Maximum results to return" } } } } ``` **Example Usage:** ``` User: "Find me a 10k resistor, 0603 package, JLCPCB basic part" Claude: [uses search_jlcpcb_parts] Found 15 parts: 1. C25804 - YAGEO RC0603FR-0710KL - 10kΩ ±1% 0.1W - Basic - $0.002 (15k in stock) 2. C58972 - UNI-ROYAL 0603WAF1002T5E - 10kΩ ±1% 0.1W - Basic - $0.001 (50k in stock) ... Recommended: C58972 (cheapest Basic part with high stock) ``` #### 2. `get_jlcpcb_part` Get detailed information about a specific JLCPCB part. ```typescript { name: "get_jlcpcb_part", description: "Get detailed info for a specific JLCPCB part", inputSchema: { type: "object", properties: { lcsc_number: { type: "string", description: "LCSC part number (e.g., 'C25804')" } }, required: ["lcsc_number"] } } ``` **Returns:** ```json { "lcsc": "C25804", "mfr_part": "RC0603FR-0710KL", "manufacturer": "YAGEO", "category": "Resistors / Chip Resistor - Surface Mount", "package": "0603", "description": "10kΩ ±1% 0.1W Thick Film Resistors", "library_type": "Basic", "stock": 15000, "price_breaks": [ {"qty": 1, "price": "$0.002"}, {"qty": 10, "price": "$0.0018"}, {"qty": 100, "price": "$0.0015"} ], "datasheet": "https://datasheet.lcsc.com/...", "kicad_footprints": [ "Resistor_SMD:R_0603_1608Metric" ] } ``` #### 3. Enhanced `place_component` Add JLCPCB integration to existing component placement. ```typescript // Add new optional parameter to place_component: { jlcpcb_part: { type: "string", description: "JLCPCB LCSC part number (e.g., 'C25804'). If provided, will use JLCPCB specs." } } ``` **Example:** ``` User: "Place a 10k resistor at 50, 40mm using JLCPCB part C25804" Claude: [uses place_component with jlcpcb_part="C25804"] - Looks up C25804 → finds package "0603" - Maps "0603" → "Resistor_SMD:R_0603_1608Metric" - Places component with: - Reference: R1 - Value: 10k (C25804) - Footprint: Resistor_SMD:R_0603_1608Metric - Attribute: LCSC part C25804 stored in component properties ``` --- ### Phase 4: Testing & Documentation (Day 4) **Testing:** 1. Download JLCPCB database (verify ~100k parts loaded) 2. Test parametric search (resistors, capacitors, ICs) 3. Test package mapping (0603 → correct footprints) 4. Test component placement with JLCPCB parts 5. Verify BOM export includes LCSC part numbers **Documentation:** - User guide: How to get JLCPCB API key - Usage examples for each MCP tool - Best practices (prefer Basic parts, check stock) - BOM generation for JLCPCB assembly --- ## User Workflow Examples ### Example 1: Find and Place a Resistor ``` User: "I need a 10k pull-up resistor, 0603 size, cheapest JLCPCB basic part" Claude: [uses search_jlcpcb_parts] query: "10k resistor" package: "0603" library_type: "Basic" Found: C58972 - UNI-ROYAL 0603WAF1002T5E - 10kΩ ±1% 0.1W - Basic part (free assembly!) - $0.001 each - 50,000 in stock User: "Perfect, place it at position 45, 30mm" Claude: [uses place_component] componentId: "Resistor_SMD:R_0603_1608Metric" position: {x: 45, y: 30} reference: "R1" value: "10k (C58972)" jlcpcb_part: "C58972" ✅ Placed R1: 10k at (45, 30) mm JLCPCB: C58972 (Basic part, $0.001) ``` ### Example 2: Design a Cost-Optimized LED Circuit ``` User: "Design an LED circuit with current-limiting resistor, use only JLCPCB basic parts" Claude: [searches for LED] Found: C2286 - Everlight 19-217/BHC-ZL1M2RY/3T (Red LED, 0603) - Basic - $0.015 [searches for resistor] Calculated: 330Ω for 5V → 20mA Found: C23138 - UNI-ROYAL 0603WAF3300T5E (330Ω, 0603) - Basic - $0.001 [places components] R1: 330Ω (C23138) at (40, 30) mm D1: Red LED (C2286) at (50, 30) mm Total BOM cost: $0.016 Both are Basic parts → Free assembly! 🎉 ``` ### Example 3: Check Stock Before Ordering ``` User: "I need 100 of part C25804, is there enough stock?" Claude: [uses get_jlcpcb_part lcsc_number="C25804"] Stock: 15,000 units ✅ Plenty of stock for 100 units Price for 100: $0.0015 each = $0.15 total ``` --- ## API Key Setup **How to Get JLCPCB API Key:** 1. Visit JLCPCB website: https://jlcpcb.com/ 2. Log in to your account 3. Go to: Account → API Management 4. Click "Create API Key" 5. Save your `appKey` and `appSecret` **Configure in MCP:** Option A: Environment variables (recommended) ```bash export JLCPCB_API_KEY="your_app_key" export JLCPCB_API_SECRET="your_app_secret" ``` Option B: Config file ```json { "jlcpcb": { "api_key": "your_app_key", "api_secret": "your_app_secret", "cache_db": "~/.kicad-mcp/jlcpcb_parts.db" } } ``` **Initial Setup:** ``` User: "Download the JLCPCB parts database" Claude: [runs JLCPCB database download] Authenticating... ✅ Fetching parts... (page 1/500) Fetching parts... (page 2/500) ... ✅ Downloaded 108,523 parts ✅ Saved to ~/.kicad-mcp/jlcpcb_parts.db (42 MB) Database ready! You can now search JLCPCB parts. ``` --- ## Cost Optimization Features ### Prefer Basic Parts ```python def search_parts_optimized(self, specs: dict) -> List[dict]: """ Search with automatic Basic part preference. Returns Basic parts first, Extended parts only if no Basic match. """ basic_parts = self.search_parts(**specs, library_type="Basic") if basic_parts: return basic_parts return self.search_parts(**specs, library_type="Extended") ``` ### Calculate BOM Cost ```python def calculate_bom_cost(self, board: pcbnew.BOARD) -> dict: """ Calculate total cost for JLCPCB assembly. Returns: { "total_parts_cost": 12.50, "basic_parts_count": 15, "extended_parts_count": 2, "extended_setup_fee": 6.00, # $3 per unique extended part "total_assembly_cost": 18.50 } """ ``` --- ## Integration with Existing Features ### BOM Export Enhancement Update `export_bom` to include JLCPCB columns: ```csv Reference,Value,Footprint,LCSC Part,Library Type,Manufacturer,MFR Part,Stock R1,10k,Resistor_SMD:R_0603_1608Metric,C58972,Basic,UNI-ROYAL,0603WAF1002T5E,50000 D1,Red,LED_SMD:LED_0603_1608Metric,C2286,Basic,Everlight,19-217/BHC-ZL1M2RY/3T,8000 ``` This BOM can be directly uploaded to JLCPCB for assembly! --- ## Database Update Strategy **Initial Download:** ~5-10 minutes (108k parts) **Incremental Updates:** - Run daily via cron/scheduled task - Only fetch parts modified since last update - Much faster (~30 seconds) **Update Command:** ```python # In Python jlcpcb_client.update_database(db_path) # Via MCP tool update_jlcpcb_database(force=False) # Incremental update_jlcpcb_database(force=True) # Full re-download ``` --- ## Success Metrics **Implementation Complete When:** - ✅ Can download/cache full JLCPCB parts database - ✅ Parametric search works (resistors, capacitors, ICs) - ✅ Package → footprint mapping covers 90%+ of common parts - ✅ MCP tools integrated and tested end-to-end - ✅ BOM export includes LCSC part numbers - ✅ Documentation complete with examples **User Experience Goal:** ``` User: "Design a board with an ESP32, USB-C connector, and LED, use only JLCPCB basic parts under $10 BOM" Claude: [searches JLCPCB database] [places all components with real parts] [exports BOM ready for manufacturing] ✅ Board designed with 23 components 💰 Total cost: $8.45 🎉 All Basic parts (free assembly!) ``` --- ## Future Enhancements **Post-MVP (v2.1+):** - LCSC API integration for extended parametric data - Digikey/Mouser fallback for non-JLCPCB parts - Part substitution suggestions (out of stock → alternatives) - Price history and trend analysis - Community-contributed package mappings - Visual part selection UI (if web interface added) --- ## Related Documentation - [LIBRARY_INTEGRATION.md](./LIBRARY_INTEGRATION.md) - KiCAD footprint libraries - [REALTIME_WORKFLOW.md](./REALTIME_WORKFLOW.md) - MCP ↔ UI collaboration - [ROADMAP.md](./ROADMAP.md) - Overall project plan - [API.md](./API.md) - MCP API reference --- **Status:** Ready to implement! 🚀 **Next Step:** Get JLCPCB API credentials and start Phase 1