From b98c94be4238f78b90ed75023c4e69f75d848cc9 Mon Sep 17 00:00:00 2001
From: KiCAD MCP Bot <kicad-mcp@example.com>
Date: Fri, 27 Feb 2026 21:33:33 -0500
Subject: [PATCH] docs: Update macOS installation, JLCPCB database size, and
 part counts (#45, #43)

- Add macOS venv setup using KiCAD's bundled Python (fixes #45)
- Update JLCPCB database size from 1-2 GB to 3-5 GB (accurate for 2.5M+ parts)
- Update all "100k+" references to "2.5M+" for consistency
- Update jlcpcb-api.ts tool description (JLCSearch API, no auth required)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 README.md                  | 22 +++++++++++++++++-----
 docs/JLCPCB_USAGE_GUIDE.md |  2 +-
 src/tools/jlcpcb-api.ts    |  4 ++--
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index e76e4ac..8542b79 100644
--- a/README.md
+++ b/README.md
@@ -230,7 +230,7 @@ The server provides 64 tools organized into functional categories. With the new
 
 ### JLCPCB Integration (5 tools)
 - `download_jlcpcb_database` - Download complete JLCPCB parts catalog (one-time setup)
-- `search_jlcpcb_parts` - Search 100k+ parts with parametric filters
+- `search_jlcpcb_parts` - Search 2.5M+ parts with parametric filters
 - `get_jlcpcb_part` - Get detailed part info with pricing and footprints
 - `get_jlcpcb_database_stats` - View database statistics and coverage
 - `suggest_jlcpcb_alternatives` - Find cheaper or more available alternatives
@@ -372,20 +372,32 @@ See [Windows Installation Guide](docs/WINDOWS_SETUP.md) for detailed instruction
 
 ### macOS
 
+**Important:** On macOS, use KiCAD's bundled Python to ensure proper access to pcbnew module.
+
 ```bash
 # Install KiCAD 9.0 from kicad.org/download/macos
 
 # Install Node.js
 brew install node@20
 
-# Clone and build
+# Clone repository
 git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
 cd KiCAD-MCP-Server
+
+# Create virtual environment using KiCAD's bundled Python
+/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Install dependencies
 npm install
-pip3 install -r requirements.txt
+pip install -r requirements.txt
 npm run build
 ```
 
+**Note:** The `--system-site-packages` flag is required to access KiCAD's pcbnew module from the virtual environment.
+
 ## Configuration
 
 ### Claude Desktop
@@ -479,7 +491,7 @@ To download the database:
 Ask Claude: "Download the JLCPCB parts database"
 ```
 
-This creates a local SQLite database at `data/jlcpcb_parts.db` (~1-2 GB for full catalog).
+This creates a local SQLite database at `data/jlcpcb_parts.db` (3-5 GB for full 2.5M+ part catalog).
 
 **Mode 2: Local Symbol Libraries (No Setup Required)**
 
@@ -758,7 +770,7 @@ npm run format
 - UI auto-launch
 - Full MCP protocol compliance
 - JLCPCB parts integration (local libraries + JLCSearch API)
-- Cost optimization and component selection with 100k+ parts catalog
+- Cost optimization and component selection with 2.5M+ parts catalog
 
 **Under Active Development (IPC Backend):**
 - Real-time UI synchronization via KiCAD 9.0 IPC API
diff --git a/docs/JLCPCB_USAGE_GUIDE.md b/docs/JLCPCB_USAGE_GUIDE.md
index 0bc7c33..55bb8ac 100644
--- a/docs/JLCPCB_USAGE_GUIDE.md
+++ b/docs/JLCPCB_USAGE_GUIDE.md
@@ -45,7 +45,7 @@ Downloaded 200 parts...
 Downloaded 2,500,000 parts...
 
 Total parts: 2,500,000+
-Database size: ~1-2 GB
+Database size: 3-5 GB (full catalog)
 ```
 
 ### Usage Examples
diff --git a/src/tools/jlcpcb-api.ts b/src/tools/jlcpcb-api.ts
index 9640676..87f6eeb 100644
--- a/src/tools/jlcpcb-api.ts
+++ b/src/tools/jlcpcb-api.ts
@@ -12,8 +12,8 @@ export function registerJLCPCBApiTools(server: McpServer, callKicadScript: Funct
     "download_jlcpcb_database",
     `Download the complete JLCPCB parts catalog to local database.
 
-This is a one-time setup that downloads ~100k+ parts from JLCPCB API.
-Requires JLCPCB_API_KEY and JLCPCB_API_SECRET environment variables.
+This is a one-time setup that downloads ~2.5M+ parts from JLCSearch API.
+No API credentials required - uses public JLCSearch API.
 
 The download takes 5-10 minutes and creates a local SQLite database
 for fast offline searching.`,