eparts-search-mcp

DigiKey, LCSC, Mouser에서 전자 부품을 검색하는 MCP 서버입니다. 각 유통사는 개별적으로 또는 모두 함께 조회할 수 있으며, 동일한 부품 번호에 대한 오퍼는 단일 항목으로 병합되어 가격을 비교할 수 있습니다.

도구

search_parts는 sources 목록을 받습니다. 생략하면 구성된 모든 유통사를 검색하고, ["mouser"]를 전달하면 해당 유통사만 검색합니다. 결과는 기본적으로 부품 번호별로 병합되며 cheapest_at_quantity 비교가 적용됩니다. merge=false를 전달하면 각 유통사의 결과를 별도 목록으로 유지합니다.

비교는 요청한 수량에서 가격이 있는 오퍼만 고려합니다. LCSC는 많은 부품을 10개 단위로 판매하므로 수량 1에서는 해당 오퍼에 적용 가능한 브레이크가 없어 비교에서 제외되며 무료로 계산되지 않습니다.

한 유통사가 실패하거나, 구성되지 않았거나, 할당량을 소진한 경우에도 다른 유통사는 결과를 반환하며 실패는 errors 아래에 보고됩니다.

Related MCP server: Nexar MCP Server

설치

시스템 어디에서든 서버를 사용하려면 독립 실행형 도구로 설치하세요. 실행 파일은 ~/.local/bin($XDG_BIN_HOME이 설정된 경우 해당 경로)에 설치되며, 의존성은 ~/.local/share/uv/tools 아래의 자체 환경에 설치됩니다:

uv tool install .

mise run install-tool도 동일한 작업을 수행하며, mise run uninstall-tool은 제거합니다. 설치 후 eparts-search-mcp는 어떤 디렉터리에서든 stdio로 서버를 실행하며, 아래 설명된 XDG 구성 파일에서 자격 증명을 읽습니다. ~/.local과 ~/.config 외부의 어떤 것도 건드리지 않으므로 권한 있는 설치 단계가 필요하지 않습니다.

~/.local/bin이 PATH에 있는지 확인하세요:

export PATH="$HOME/.local/bin:$PATH"

개발 설정

서버를 사용하는 대신 개발하려면:

mise install
mise run install
mise run test

자격 증명은 구성 파일 또는 환경 변수에서 가져올 수 있습니다. 파일은 자격 증명을 환경 및 프로세스 목록에서 보호합니다. 기본적으로 ~/.config/eparts-search-mcp/config.toml(또는 $XDG_CONFIG_HOME이 설정된 경우 해당 경로)에서 읽히므로 EPARTS_CONFIG가 필요하지 않습니다:

# ~/.config/eparts-search-mcp/config.toml
[providers.digikey]
# DigiKey: register an app at developer.digikey.com with Product Information enabled
client_id = "..."
client_secret = "..."

[providers.lcsc]
# LCSC: partner credentials issued by an account manager
key = "..."
secret = "..."

[providers.mouser]
# Mouser: request a Search API key from mouser.com/api-hub
api_key = "..."

파일에는 비밀이 포함되어 있으므로 본인만 읽을 수 있게 유지하세요. 서버는 그룹 또는 다른 사용자가 접근할 수 있는 경우 시작 시 경고합니다:

chmod 600 ~/.config/eparts-search-mcp/config.toml

동일한 값은 대신 환경 변수로 제공할 수 있으며, 이는 파일보다 우선합니다:

export DIGIKEY_CLIENT_ID=...
export DIGIKEY_CLIENT_SECRET=...
export LCSC_KEY=...
export LCSC_SECRET=...
export MOUSER_API_KEY=...

실제로 사용하려는 유통사의 자격 증명만 필요합니다. 자격 증명이 없는 소스는 검색을 실패시키지 않고 구성되지 않은 것으로 보고됩니다.

자격 증명 얻기

DigiKey. 개인 개발자 앱은 샌드박스 액세스만 얻을 수 있으며 샌드박스는 합성 데이터를 반환합니다. 실제 재고와 가격을 보려면 Organization 아래에 있는 Production 앱이 필요합니다:

1. developer.digikey.com에 DigiKey 계정으로 로그인합니다.

2. 탐색 모음에서 Organizations를 열고 아직 회원이 아니면 생성합니다.

3. Operations 아래에서 Production Apps를 선택한 다음 Create Production App을 선택합니다.

4. 앱에 Product Information을 활성화합니다.

5. 앱을 열어 Client ID와 Client Secret을 복사합니다.

OAuth 콜백 필드는 3-legged OAuth에서만 사용됩니다. 이 서버는 2-legged 클라이언트 자격 증명 흐름을 사용하므로 콜백으로 리디렉션되지 않습니다. https://localhost는 양식을 충족합니다.

샌드박스와 프로덕션 자격 증명은 서로 교환할 수 없습니다. 샌드박스 자격 증명은 DIGIKEY_SANDBOX=true가 선택하는 sandbox-api.digikey.com에서만 작동합니다.

LCSC. Open API는 셀프 서비스 가입이 아닌 파트너 통합이므로 자격 증명은 호출 IP 주소가 화이트리스트에 등록된 후 LCSC 계정 관리자로부터 받습니다. 온보딩은 시뮬레이션된 카탈로그 데이터로 응답하는 별도 호스트(fatapi.lcsc.com)의 테스트 환경에서 시작됩니다. LCSC_SANDBOX=true가 이를 선택합니다. 프로덕션 자격 증명은 통합이 승인된 후 도착하며 api.lcsc.com에 대해 사용됩니다.

호출은 요청 매개변수, 키, 요청별 nonce 및 타임스탬프에 대한 SHA-256 서명으로 인증됩니다. 비밀은 해당 해시의 입력이며 전송되지 않으므로 URL이나 로그에 나타나지 않습니다. 타임스탬프가 확인되므로 시스템 시계가 크게 잘못된 경우 키 거부가 아닌 만료된 요청으로 읽힙니다.

Mouser. mouser.com/api-hub에서 Search API 키를 요청하세요. 단일 키이며 쿼리 매개변수로 전송되고 이메일로 도착합니다.

MCP 클라이언트 구성

위와 같이 설치하면 명령이 PATH에 있으므로 경로나 환경이 필요하지 않습니다. 자격 증명은 구성 파일에서 오기 때문입니다:

{
  "mcpServers": {
    "eparts-search-mcp": {
      "command": "eparts-search-mcp"
    }
  }
}

일부 클라이언트는 ~/.local/bin을 포함하지 않는 빈 환경으로 서버를 시작합니다. 해당 경우 절대 경로를 대신 지정하세요:

{
  "mcpServers": {
    "eparts-search-mcp": {
      "command": "/home/you/.local/bin/eparts-search-mcp"
    }
  }
}

설치 없이 소스 체크아웃에서 실행하거나 구성 파일 대신 클라이언트를 통해 자격 증명을 전달하려면:

{
  "mcpServers": {
    "eparts-search-mcp": {
      "command": "/path/to/eparts-search-mcp/.venv/bin/python",
      "args": ["-m", "eparts_search_mcp"],
      "env": {
        "DIGIKEY_CLIENT_ID": "...",
        "DIGIKEY_CLIENT_SECRET": "...",
        "MOUSER_API_KEY": "..."
      }
    }
  }
}

속도 제한

각 유통사는 하루에 약 천 번의 호출을 허용하므로 모든 요청에 예산이 적용됩니다. 초당 및 분당 창은 대기로 강제되며, 일일 창은 호출자가 자정에 재설정되는 할당량을 기다릴 수 없으므로 대신 오류를 보고하는 하드 스톱입니다. 일일 카운터는 영속화되므로 서버를 다시 시작해도 재설정되지 않습니다.

기본값:

LCSC는 분당 60회 키워드 검색과 하루 천 번을 문서화하며 성공한 호출만 계산합니다. 분당 기본값은 문서화된 상한보다 낮게 설정되는데, 유통사에 의해 제한되는 것이 로컬에서 대기하는 것보다 비용이 더 들기 때문입니다. LCSC 자체 카운터가 호출을 거부하는 경우에도 로컬 예산과 구별하기 위해 오류에 명시됩니다.

모든 값은 환경 변수 또는 TOML 파일로 공급자별로 구성할 수 있습니다. none, off, unlimited 또는 0을 사용하여 창을 비활성화합니다:

export DIGIKEY_RATE_PER_DAY=250
export DIGIKEY_RATE_PER_MINUTE=30
export LCSC_RATE_PER_MINUTE=20
export MOUSER_RATE_PER_SECOND=none
export MOUSER_RATE_BURST=5
export MOUSER_RATE_MAX_WAIT=30

이 값들은 구성 파일(기본적으로 ~/.config/eparts-search-mcp/config.toml 또는 EPARTS_CONFIG가 가리키는 위치)에도 있으며 config.example.toml을 참조하세요. 환경 변수는 파일보다 우선하므로 클라이언트 실행 명령이 디스크의 구성을 편집하지 않고 제한을 조정할 수 있습니다.

캐시된 응답은 예산을 소비하지 않고 제공됩니다. source_status는 하루 중 남은 예산을 보고합니다.

기타 설정

디스크의 파일

서버가 유지하는 모든 것은 XDG 기본 디렉터리 아래에 있으므로 설치가 홈 디렉터리 외부의 어떤 것도 소유하지 않습니다:

XDG_CONFIG_HOME과 XDG_STATE_HOME은 설정되지 않은 경우 각각 ~/.config와 ~/.local/state로 기본 설정됩니다. EPARTS_CONFIG와 EPARTS_CACHE_PATH는 마지막 두 항목을 재정의합니다. uv tool uninstall eparts-search-mcp로 제거하면 구성과 캐시가 그대로 유지됩니다. 해당 디렉터리도 삭제하려면 직접 삭제하세요.

아키텍처

classDiagram
    class MCPServer {
        search_parts(keyword, sources, merge)
        part_details(part_number, sources)
        source_status()
        clear_cache(source)
    }
    class SearchService {
        +providers: dict
        +limiters: dict
        +resolve_sources(sources)
        +search(...) SearchResult
        +details(...) list~Part~
    }
    class Provider {
        <<abstract>>
        +name: str
        +configured: bool
        +search(...) list~Part~
        +details(...) Part
        #_cached_request(...)
    }
    class DigiKeyProvider {
        -_token: str
        -_access_token()
        -_manufacturer_filter_id(name)
        -_pick_variation(product)
    }
    class LCSCProvider {
        -_headers(payload)
        -_to_part(entry)
        +sign(payload, key, secret, nonce, timestamp)
    }
    class MouserProvider {
        -_parse_response(response)
        +parse_price(raw)
    }
    class RateLimiter {
        +acquire()
        +remaining_today()
    }
    class Cache {
        +get(key)
        +set(key, provider, value, ttl)
        +get_daily_usage(provider, day)
        +increment_daily_usage(provider, day)
    }
    class Part {
        +source, mpn, manufacturer
        +stock, price_breaks, specs
        +unit_price_at(quantity)
    }
    class MergedPart {
        +mpn
        +offers: list~Part~
        +sources
    }

    MCPServer --> SearchService
    SearchService --> Provider
    SearchService --> RateLimiter
    SearchService --> Cache
    Provider <|-- DigiKeyProvider
    Provider <|-- LCSCProvider
    Provider <|-- MouserProvider
    Provider --> RateLimiter : acquire before call
    Provider --> Cache : read before spending budget
    RateLimiter --> Cache : persist daily counter
    Provider --> Part : produces
    MergedPart o-- Part : groups offers by part number

한 공급자 호출의 요청 흐름:

sequenceDiagram
    participant C as MCP client
    participant S as SearchService
    participant P as Provider
    participant K as Cache
    participant L as RateLimiter
    participant A as Distributor API

    C->>S: search_parts(keyword, sources)
    S->>S: resolve_sources
    par each source
        S->>P: search(keyword)
        P->>K: get(key)
        alt cached
            K-->>P: payload
        else not cached
            P->>L: acquire()
            alt budget available
                L-->>P: ok
                P->>A: HTTP request
                A-->>P: response
                P->>K: set(key, payload)
            else daily quota spent
                L--)P: RateLimitExceeded
            end
        end
        P-->>S: parts or error
    end
    S->>S: merge by part number
    S-->>C: results plus per source errors

세 가지 API에 대한 참고 사항

DigiKey는 OAuth2 클라이언트 자격 증명을 사용합니다. 토큰은 10분 동안 유효하며 메모리에 캐시됩니다. 요청에는 bearer 토큰과 함께 클라이언트 ID 헤더가 필요합니다. 필터는 불투명한 ID로 표현되므로 제조사 이름은 먼저 manufacturers 엔드포인트를 통해 확인됩니다.

LCSC는 토큰 대신 각 요청에 서명합니다. 키, nonce, 타임스탬프 및 정렬된 쿼리 매개변수가 비밀로 해시되고 다이제스트가 헤더로 전송됩니다. Mouser와 마찬가지로 요청이 실패해도 HTTP 200으로 응답하며 실제 결과는 본문의 code 필드에 있으며 어댑터는 이를 권위 있는 것으로 취급합니다. 부품별 엔드포인트가 없으므로 세부 정보 조회는 키워드 검색에서 정확히 일치하는 항목을 선택하는 방식입니다. 근사 일치만 반환하는 키워드 검색은 그럴듯한 잘못된 결과 대신 결과 없음을 산출합니다. 제조사 필터도 없으므로 제조사는 키워드에 포함되고 결과는 반환 시 필터링됩니다.

Mouser는 쿼리 매개변수로 전달되는 API 키를 사용하며 요청이 실패해도 HTTP 200으로 응답하고 실패를 Errors 배열에 넣습니다. 어댑터는 해당 배열을 권위 있는 것으로 취급합니다. 가격은 숫자가 아닌 지역화된 표시 문자열로 도착합니다.

매개변수 사양은 세 유통사 간에 공유 어휘가 없으므로 공통 스키마로 정규화하는 대신 이름/값 맵으로 전달됩니다. LCSC의 릴 할증료도 단위 가격 사다리로 표현할 수 없는 주문당 수수료이므로 동일한 방식으로 보고됩니다.

이 도구는 Claude Code를 사용하여 제작되었습니다.