---
name: jlcpcb
description: Search JLCPCB's in-stock component catalog for parts, pricing, images, and LCSC part numbers. Use when the user asks to find JLCPCB parts, check JLCPCB pricing/stock, look up an LCSC number, find basic/preferred parts, do parametric component searches, or compare alternatives for JLCPCB assembly. Results auto-display in the Gallia Viewer with rich component cards.
---

# JLCPCB Component Search

Search JLCPCB's 437K+ in-stock component catalog. Backed by a shared service running on a dedicated container — individual user containers don't need the 1.3GB SQLite database.

Results are sorted by stock (highest first), which is a strong proxy for popularity.

## Architecture

The JLCPCB service runs as a **shared remote service** on a dedicated container. All other Gallia containers query it over HTTP via the MCP tools — no local database needed.

```
Dedicated Service Container (john/service-jlcpcb)
  SQLite DB (1.3GB, 437K+ components, daily auto-update)
    ↓
  JLCPCB HTTP Server (port 8774, GET + POST, CORS enabled)
    ↓ (proxied via Coder)
  https://coder.john-service-jlcpcb-9a8b6c0328533a9b.containers.adom.inc/proxy/8774

User Containers (any Gallia-enabled container)
  MCP Tools (adom-jlcpcb) ──→ HTTP fetch to shared service URL
    ↓
  pushToViewer() ──→ Viewer API (port 8771) ──→ WebSocket ──→ Gallia Viewer
```

The shared service URL is hardcoded in `jlcpcb/mcp/tools.js` — no `JLCPCB_API` env var needed. Override with `JLCPCB_API` env var only for local development on the service container itself.

### Service container details

- **Container**: `john/service-jlcpcb` on Adom
- **Port**: 8774
- **Database**: `~/gallia/services/jlcpcb/jlcpcb-components.sqlite3` (~1.3GB)
- **Auto-start**: Hooked into `code-server-entrypoint.sh` — starts automatically on container boot
- **Daily updates**: Cron job (`/etc/cron.daily/update-jlcpcb-db`) checks upstream via ETag, downloads only if changed, rebuilds FTS, atomic swap + SIGHUP reload
- **Notifications**: Google Chat webhook on each daily update (reports component count and whether DB changed)
- **Landing page**: Visit the service URL in a browser for API docs, curl examples, and health stats
- **Bootstrap:** `bash <(curl -fsSL https://coder.john-gallia-f280e93ffec7e79d.containers.adom.inc/proxy/9999/bootstrap.sh) --service jlcpcb`
- **Update:** `cd ~/gallia && git pull && pkill -f 'node.*services/jlcpcb/server.js'; bash services/jlcpcb/start-jlcpcb.sh`

## Gallia Viewer Integration

All search results automatically appear in the Gallia Viewer as rich interactive cards. This works two ways:

- **From the GV search bar** — select "JLCPCB Search" from the dropdown, type a query, and results render directly in the viewer.
- **From any Claude Code channel** — when you call `jlcpcb_search`, `jlcpcb_category_search`, or `jlcpcb_list`, results are pushed to the Gallia Viewer via WebSocket. The viewer auto-switches to the JLCPCB view and shows the same rich cards.

Each card shows:
- **Component image** (front view from LCSC, 900x900) — click to open a lightbox with all available views (front, back, blank). Navigate with arrow keys or thumbnail clicks.
- **MPN, LCSC number, Basic/Preferred badges**
- **Package, stock (color-coded), pricing with expandable tier table**
- **Key attributes** (up to 4)
- **Links**: Datasheet (PDF), JLCPCB parts page (shows EDA symbol/footprint/3D model), LCSC product page

## Available MCP Tools

### `jlcpcb_search` — Keyword / Part Number Search

Search by keyword, MPN, description, or LCSC part number.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Part number, keyword, or LCSC code (e.g. "STM32F103", "USB-C connector", "C8734") |
| `limit` | number | 10 | Max results (1–100) |
| `package` | string | — | Filter by package (e.g. "LQFP-48", "SOT-23-5", "0402") |
| `is_basic` | boolean | — | Filter to JLCPCB basic parts only (cheaper assembly fee) |
| `is_preferred` | boolean | — | Filter to JLCPCB preferred parts only |

### `jlcpcb_category_search` — Parametric Search

Search within a specific component category with category-specific filters.

| Parameter | Type | Description |
|-----------|------|-------------|
| `category` | string | Component category (e.g. "resistors", "capacitors", "microcontrollers", "ldos", "mosfets") |
| `filters` | object | Category-specific filters (e.g. `{"resistance": "10000", "package": "0402"}`) |
| `limit` | number | Max results (1–100) |

**Common filter keys by category:**
- **resistors:** `resistance`, `package`, `tolerance_fraction`, `power_watts`
- **capacitors:** `capacitance_farads`, `voltage_rating`, `package`, `temperature_coefficient`
- **microcontrollers:** `cpu_core`, `flash_size_bytes`, `ram_size_bytes`, `gpio_count`, `package`
- **ldos:** `output_voltage_min`, `output_voltage_max`, `output_current_max`, `dropout_voltage`
- **mosfets:** `drain_source_voltage`, `continuous_drain_current`, `package`

**Available categories:** resistors, capacitors, microcontrollers, ldos, voltage_regulators, boost_converters, buck_boost_converters, mosfets, bjt_transistors, diodes, leds, led_drivers, switches, fuses, relays, headers, usb_c_connectors, jst_connectors, wire_to_board_connectors, pcie_m2_connectors, io_expanders, fpgas, arm_processors, risc_v_processors, wifi_modules, accelerometers, gyroscopes, gas_sensors, adcs, dacs, analog_multiplexers, analog_switches, potentiometers, resistor_arrays, battery_holders, lcd_display, oled_display, led_dot_matrix_display, led_segment_display, led_with_ic.

### `jlcpcb_list` — Browse by Subcategory

List components in a subcategory, sorted by stock/popularity.

### `jlcpcb_categories` — List All Categories

Discover available categories and subcategories before doing a parametric search.

### `jlcpcb_health` — Check Service Health

Verify the JLCPCB search server is running and the database is loaded.

## What's in a Result

Each part includes:
- **LCSC part number** — use this in JLCPCB BOM (e.g. C8734)
- **Manufacturer part number (MPN)**
- **Package** and **pin count**
- **Stock** — current inventory (higher = more popular)
- **Pricing** — per-unit cost with full quantity tier breakdown
- **Basic/Preferred status** — basic parts have lower JLCPCB assembly fees
- **Component images** — array of photo URLs (front, back, blank views at 900x900)
- **Attributes** — category-specific specs (e.g. CPU speed, flash size, voltage range)
- **Datasheet URL**
- **JLCPCB parts page** — `jlcpcb.com/parts` link with EDA symbol, footprint, and 3D model downloads
- **LCSC product page** — underlying distributor page

## Workflow

### Finding a part for JLCPCB assembly
1. Use `jlcpcb_search` with keyword + `is_basic: true` for cheapest assembly
2. Note the **LCSC part number** for the BOM
3. Check the JLCPCB parts page link for EDA symbol/footprint/3D model availability
4. Use `jlcpcb_category_search` for parametric filtering when you need specific specs

### Finding popular alternatives
Results are sorted by stock (descending). The highest-stock parts are the most widely used — prefer these for better availability and lower risk of shortages.

## Files

| File | Purpose |
|------|---------|
| `services/jlcpcb/server.js` | HTTP API server (port 8774), SQLite queries, landing page |
| `services/jlcpcb/setup-db.js` | Downloads ~1.3GB database from CDFER, builds FTS index |
| `services/jlcpcb/test.js` | 19-test suite with GV output |
| `services/jlcpcb/start-jlcpcb.sh` | Idempotent start script (used by container boot) |
| `jlcpcb/mcp/server.js` | MCP stdio transport entry point |
| `jlcpcb/mcp/tools.js` | 5 MCP tools + fire-and-forget push to Gallia Viewer (hardcoded service URL) |

## Database Setup (service container only)

```bash
cd ~/gallia/services/jlcpcb && node setup-db.js        # download if not present
cd ~/gallia/services/jlcpcb && node setup-db.js --force # re-download
```

The database is auto-downloaded on first install. The daily cron job handles updates via ETag-based conditional fetching — only re-downloads the 1.3GB file if the upstream has actually changed.

## Implementation Notes

These are patterns established in the JLCPCB service that should be followed when modifying it or building similar services:

1. **FTS5 MATCH sanitization.** User queries can contain characters that crash SQLite FTS5 (`()`, `:`, `"`, `*`). The search handler strips special chars, quotes each token, wraps in try/catch, and falls back to LIKE on mfr if FTS fails or returns nothing.

2. **Substring package matching.** The DB stores packages with qualifiers like `LQFP-48(7x7)`, `SOT-23-5(SOT-353)`. The package filter uses `.includes()` not `===` so users can type "LQFP-48" and match.

3. **Test for vacuous truth.** The test suite asserts `count > 0` before any `.every()` filter check — `[].every(fn)` is always `true`, which silently hides bugs where search returned 0 results.

4. **Test with description keywords, not just MPNs.** The FTS index covers mfr, package, and description. Tests include queries like "capacitor" and "USB-C" to verify the full search pipeline, not just exact part number lookups.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `jlcpcb_search` returns connection error | Shared service container is down or not reachable | Check `jlcpcb_health` or visit the service URL in a browser |
| Results are stale | Daily cron didn't run | SSH to service container, run `/etc/cron.daily/update-jlcpcb-db` manually |
| `fetch failed` from MCP tool | Node resolves `localhost` to IPv6 | Ensure `tools.js` uses `127.0.0.1` or the full Coder proxy URL (not `localhost`) |
| Server won't start (EADDRINUSE) | Previous process still running | `pkill -f 'node.*services/jlcpcb/server.js'` then restart |
| FTS search returns no results | FTS index not built | Run `node setup-db.js --rebuild-fts` on the service container |