digi-mouse-search

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

Инструменты

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

Если один дистрибьютор завершается ошибкой, не настроен или превысил квоту, остальные всё равно возвращают результаты, а ошибка сообщается в errors.

Настройка

mise install
mise run install
mise run test

Учётные данные берутся из переменных окружения:

# DigiKey: register an app at developer.digikey.com with Product Information enabled
export DIGIKEY_CLIENT_ID=...
export DIGIKEY_CLIENT_SECRET=...

# Mouser: request a Search API key from mouser.com/api-hub
export MOUSER_API_KEY=...

Требуются только учётные данные тех дистрибьюторов, которых вы действительно хотите использовать. Источник без учётных данных отмечается как не настроенный, а не приводит к ошибке поиска.

Получение учётных данных

DigiKey. Личное приложение разработчика получает только доступ к песочнице, а песочница возвращает синтетические данные. Для реальных остатков и цен нужно приложение Production, которое находится в организации:

1. Войдите на developer.digikey.com, используя свою учётную запись DigiKey.

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

3. В разделе Операции выберите Production-приложения, затем Создать Production-приложение.

4. Включите Информация о продукте для приложения.

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

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

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

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

Настройка MCP-клиента

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

Лимиты запросов

Оба дистрибьютора предоставляют примерно тысячу вызовов в день, поэтому каждый запрос расходует бюджет. Секундные и минутные окна соблюдаются за счёт ожидания; дневное окно — жёсткое ограничение, которое вместо этого сообщает об ошибке, поскольку ожидать восстановления квоты, сбрасываемой в полночь, бессмысленно. Дневной счётчик сохраняется на диске, поэтому перезапуск сервера не сбрасывает его.

Значения по умолчанию:

Каждое значение настраивается для каждого провайдера — через переменную окружения или TOML-файл. Используйте none, off, unlimited или 0, чтобы отключить окно:

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

Или укажите DMS_CONFIG на файл — см. config.example.toml. Переменные окружения имеют приоритет над файлом, поэтому команда запуска клиента может изменить лимит без правки конфигурации на диске.

Кэшированные ответы выдаются без расхода бюджета. source_status сообщает, сколько осталось на день.

Прочие настройки

Архитектура

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

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

Параметрические характеристики не имеют общего словаря между двумя дистрибьюторами, поэтому они передаются как карта «имя/значение», а не нормализуются в общую схему.

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