eparts-search-mcp

MCP-сервер, который ищет электронные компоненты в DigiKey, LCSC и Mouser. Каждый дистрибьютор может быть запрошен отдельно или все вместе, при этом предложения для одного и того же номера детали объединяются в одну запись, чтобы можно было сравнить цены.

Инструменты

search_parts принимает список sources. Если его опустить, поиск выполняется по всем настроенным дистрибьюторам; передача ["mouser"] ищет только у него. По умолчанию результаты объединяются по номеру детали с сравнением cheapest_at_quantity; передайте merge=false, чтобы сохранить результаты каждого дистрибьютора в отдельном списке.

Сравнение учитывает только предложения, у которых есть цена на запрашиваемое количество. LCSC продает многие детали кратно десяти, поэтому при количестве один такое предложение не имеет применимого диапазона и исключается из сравнения, а не считается бесплатным.

Если один дистрибьютор выходит из строя, не настроен или исчерпал квоту, остальные все равно возвращают результаты, а ошибка сообщается в разделе 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. Личное приложение разработчика получает только доступ к песочнице, а песочница возвращает синтетические данные. Для реальных данных о наличии и ценах нужно Production-приложение, которое находится в организации:

1. Войдите на developer.digikey.com с помощью своей учетной записи DigiKey.

2. Откройте Organizations в навигационной панели и создайте организацию, если вы еще не участник.

3. В разделе Operations выберите Production Apps, затем Create Production App.

4. Включите Product Information для приложения.

5. Откройте приложение, чтобы скопировать его Client ID и Client Secret.

Поле обратного вызова OAuth используется только для трехстороннего OAuth. Этот сервер использует двухсторонний поток учетных данных клиента, поэтому обратный вызов никогда не перенаправляется; https://localhost удовлетворяет форме.

Учетные данные песочницы и продакшена не взаимозаменяемы. Учетные данные песочницы работают только с sandbox-api.digikey.com, что выбирается с помощью DIGIKEY_SANDBOX=true.

LCSC. Open API — это партнерская интеграция, а не самостоятельная регистрация, поэтому учетные данные предоставляются менеджером аккаунта LCSC после того, как вызывающий IP-адрес будет внесен в белый список. Онбординг начинается в тестовой среде на отдельном хосте (fatapi.lcsc.com), который отвечает имитированными данными каталога; LCSC_SANDBOX=true выбирает его. Производственные учетные данные появляются после подписания интеграции и используются с api.lcsc.com.

Вызов аутентифицируется подписью SHA-256 по параметрам запроса, ключу, одноразовому номеру (nonce) и временной метке. Секрет является входом для этого хэша и никогда не передается, поэтому он не появляется ни в URL, ни в журнале; временная метка проверяется, что означает, что сильно неправильные системные часы интерпретируются как истекший запрос, а не как отклоненный ключ.

Mouser. Запросите ключ Search API на mouser.com/api-hub. Это один ключ, передаваемый как параметр запроса, и он приходит по электронной почте.

Конфигурация 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 с учетными данными клиента. Токен действует десять минут и кэшируется в памяти; запросы требуют заголовок с идентификатором клиента вместе с токеном носителя. Фильтры выражаются как непрозрачные идентификаторы, поэтому имя производителя сначала разрешается через конечную точку производителей.

LCSC подписывает каждый запрос вместо токена: ключ, nonce, временная метка и отсортированные параметры запроса хэшируются с секретом, и дайджест передается в заголовке. Как и Mouser, он отвечает HTTP 200 даже при неудачном запросе, помещая реальный результат в поле code тела, которое адаптер считает авторитетным. Нет конечной точки для отдельной детали, поэтому поиск деталей — это поиск по ключевым словам, из которого выбирается точное совпадение; поиск по ключевым словам, возвращающий только близкие совпадения, не дает результата, а не правдоподобного неправильного. Также нет фильтра производителя, поэтому производитель включается в ключевое слово, а результаты фильтруются на обратном пути.

Mouser использует ключ API, передаваемый как параметр запроса, и отвечает HTTP 200 даже при неудачном запросе, помещая ошибку в массив Errors. Адаптер считает этот массив авторитетным. Цены приходят как локализованные строки отображения, а не числа.

Параметрические спецификации не имеют общего словаря между тремя дистрибьюторами, поэтому они передаются как карта имя/значение, а не нормализуются в общую схему. Надбавка за катушку LCSC сообщается так же, поскольку это плата за заказ, которую лестница цен за единицу не может выразить.

При создании этого инструмента использовался Claude Code.