README
¶
parts-finder-mcp
Local Go MCP server for speccing servers from compatible hardware.
Install
Homebrew (macOS + Linux):
brew install stubbedev/parts-finder/parts-finder
Nix flake:
nix run github:stubbedev/parts-finder-mcp
# or
nix profile install github:stubbedev/parts-finder-mcp
From source:
just build # ./bin/parts-finder
# or
go build -o parts-finder .
Register (Claude Code)
claude mcp add parts-finder -- /abs/path/to/parts-finder
DB path defaults to ~/.parts-finder.db; override with PARTS_DB.
Optional env:
SEARXNG_URL— base URL of a SearXNG instance; used as fallback when DuckDuckGo returns nothing (rate-limited).LIGHTPANDA_URL— CDP endpoint of an externally managed lightpanda/Chrome. Optional: without it, parts-finder findslightpandaon PATH, or downloads it to~/.cache/parts-finder/and spawns it on demand. Bot-blocked sites (eBay et al. return 403 to plain HTTP) automatically escalate through the renderer — zero configuration needed.REGION_COUNTRY/REGION_CURRENCY— override the IP-detected region (e.g.DK/DKK). By default the region is auto-detected from your IP (ifconfig.co over https) and cached for the process.
Region & currency
Search is biased to your region: DuckDuckGo kl locale + ranking that floats
local ccTLD domains and known EU server resellers to the top and demotes US-only
shops (nothing is dropped). find_deals / find_substitute accept a country
override and a display/comparison currency (defaults to the region currency);
listing totals in other currencies are converted with indicative ECB rates
(frankfurter.app) so you get one guiding figure. convert_currency exposes the
same conversion directly.
find_deals and shop_spec live-check every listing URL — but nothing is
ever dropped: dead (404/unreachable), unshippable, and stale (>14 days)
listings are flagged and sorted below usable ones, so no deal is hidden by a
filter.
M1 tools
| Tool | Does |
|---|---|
search_parts(query, category?, limit?) |
LIVE keyless region-biased search → result links (web is truth, not training data) |
fetch_content(url, kind?, render?) |
fetch → text (smart-cached by kind); PDF + HTML tables preserved; bot-blocked pages auto-render via lightpanda |
fetch_image(url) |
download + downscale an image (jpeg/png/gif/webp/bmp/tiff) → vision block for reading specs/labels/diagrams off pictures |
export_spec(spec_ids[], path?, append?) |
polished .xlsx: per-spec sheet (parts, live prices, buy links, owned-vs-buy totals) + Compare sheet; append edits an existing workbook in place; prompts for a save location when path is omitted |
save_part(Part) |
persist a part: scalars + provides/requires + free-form attrs |
query_parts(ids? | category?, where[]?) |
query parts by any attribute: cuda_compute >= 8.9, l3_cache_mb >= 256; ops eq/ne/gt/gte/lt/lte/contains/exists |
compose_spec(part_ids[]) |
build report: compat over known data, loud gaps, needs, total TDP |
save_spec(id, name?, part_ids[]) / load_spec(id?) |
persist/recall builds; load_spec without id lists all |
compare_specs(spec_ids[]) |
side-by-side configurations: compat, TDP, live-checked converted totals, buy links, uncovered parts |
save_listing(Listing) |
record a point-in-time price for a part |
find_deals(part_id, search?, country?, display_currency?, ...) |
live-checked, region-filtered deals, cheapest-converted first + staleness |
find_substitute(part_id, budget?, currency?, country?) |
cheaper drop-in replacements within budget (cross-currency aware) |
shop_spec(spec_id | part_ids, ...) |
one-stop purchase plan: per part the best usable link + ALL alternatives (flagged, never dropped), converted total, needs (cables/adapters short), search hits for uncovered parts |
deep_specs(part_id, queries?) |
deep-drill a part: multi-angle search + fetch top sources (tables kept) + checklist of still-empty fields |
convert_currency(amount, from, to) |
indicative ECB currency conversion |
Typical flow: search_parts → fetch_content on a spec page (HTML or PDF) →
extract fields → save_part → compose_spec. For deals: find_deals(search=true)
→ fetch_content a listing → save_listing → find_deals / find_substitute.
Extraction is done by the client model; unknown attributes are left blank and
surface as gaps, never as false incompatibilities.
Test
go test ./...
Compat rules: cpu/mobo socket, ram/mobo mem type, PSU headroom (×1.3), GPU length vs case, motherboard form factor vs case, GPU power connectors vs PSU. Unknown attributes are always treated as gaps, never violations.
Generic resource accounting (any part type)
Beyond the named rules, every part can declare provides / requires maps of
resource tokens ("kind:variant" -> count): a motherboard provides
{"dimm:ddr5":12,"pcie:x16":3,"m2:2280":2}, a RAM stick requires
{"dimm:ddr5":1}, an HBA requires {"pcie:x8":1}, a case provides
{"bay:3.5":8}, a drive requires {"bay:3.5":1}. One engine rule checks
sum(requires) <= sum(provides) per token; wider PCIe slots satisfy narrower
cards. This validates builds across drives, controllers, NICs, risers,
backplanes — any category — without new code per pair.
fetch_content preserves <table> data as markdown (spec sheets are tables),
so the client can extract these tokens reliably.
Already own some parts? List them in a spec's owned_ids — they still count
for compatibility and TDP but are excluded from the purchase total and never
shopped, so a build where you only need 1-2 new parts prices correctly.
Reading images & scanned PDFs: fetch_image downscales any common format
(jpeg/png/gif/webp/bmp/tiff) to a vision-optimal size. fetch_content on a
scanned/image-only PDF (no text layer) automatically returns its page images as
vision blocks so specs can be read straight off the scan.
Quantities: repeat a part id in a spec (["mb","cpu","cpu","psu"] = dual CPU).
Each instance consumes resources and counts toward TDP, so cable/slot shortages
surface per unit. Small stuff (cables, adapters, rails) are just parts too —
compose_spec/shop_spec return structured needs (resource → count short)
telling you exactly what extras to add.
Typical one-stop flow
search_parts(region-biased) →fetch_contentspec pages →save_partwith attributes + provides/requires.deep_specs(part_id)per part → fill every empty field from the fetched sources →save_partagain (accuracy pass).compose_spec→ fix violations/gaps, shop theneeds(cables etc.) →save_spec.shop_spec(spec_id)→ per part: best usable link to click + all flagged alternatives + converted build total. Parts without usable listings come back with buy-page search hits —fetch_content+save_listingthose, re-runshop_spec.- Build 2–3 candidate specs →
compare_specs→ pick by compat, TDP, and live-checked total.
Retrieval hardening
The search/fetch core is the cornerstone — every request goes through one hardened path:
- Per-host throttling — token spacing + concurrency cap + jitter, so we never trip a rate-limit ban (losing a host = losing its deals).
- Retry with backoff — 429/502/503/504 and network errors retry with
exponential backoff + jitter, honouring
Retry-After. - Browser fingerprint rotation — a realistic UA + client-hint + Sec-Fetch header set, chosen per host and kept stable (flipping mid-session is itself a bot tell). Cookie jar carries sessions across the set-cookie→redirect dance.
- https-first, redirect-following, transparent gzip.
- Headless escalation — TLS-fingerprint walls (eBay/Akamai) auto-escalate to lightpanda; same extraction either way.
- Resilient — every goroutine and tool handler recovers from panics, so one bad probe/scrape/request can never crash the server. Listing liveness is pre-warmed in one parallel sweep before pricing a build.
- Vision-tuned images — fetched/scanned images are downscaled to both Anthropic's long-edge (1568px) and megapixel (~1.15MP) caps and grayscaled by default, so we upload exactly the pixels the model uses — smaller, faster, cheaper, no readable detail lost.
- Smart caching — persistent SQLite cache keyed by URL with per-
kindTTL (spec ~30d / page ~1d / listing ~1h). Stale entries revalidate cheaply via ETag / Last-Modified conditional GETs (304 → keep, reset TTL). On any fetch failure the last-known-good content is served rather than nothing.
Freshness guarantees
- Every
shop_spec/find_deals/compare_specscall live-probes listing URLs. - Part data older than 30 days gets a gap: refresh with
deep_specs. - The live web is the source of truth: tool descriptions instruct the client to never deny a model's existence from training data — always search first.
Documentation
¶
There is no documentation for this package.