digi-mouse-search

Un servidor MCP que busca componentes electrónicos en DigiKey y Mouser. Se puede consultar cada distribuidor por separado o ambos a la vez, con las ofertas del mismo número de pieza fusionadas en una sola entrada para poder comparar precios.

Herramientas

search_parts acepta una lista sources. Si se omite, busca en todos los distribuidores configurados; si se pasa ["mouser"], busca solo en ese. Por defecto, los resultados se fusionan por número de pieza, con una comparación cheapest_at_quantity; pasa merge=false para mantener los resultados de cada distribuidor en una lista separada.

Si un distribuidor falla, no está configurado o se ha quedado sin cuota, los demás siguen devolviendo resultados y el fallo se notifica en errors.

Configuración

mise install
mise run install
mise run test

Las credenciales se obtienen del entorno:

# 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=...

Solo se necesitan las credenciales de los distribuidores que realmente quieras usar. Una fuente sin credenciales se notifica como no configurada en lugar de hacer fallar la búsqueda.

Cómo obtener las credenciales

DigiKey. Una aplicación de desarrollador personal solo obtiene acceso al sandbox, y el sandbox devuelve datos sintéticos. Para stock y precios reales necesitas una aplicación de producción, que se encuentra dentro de una organización:

1. Inicia sesión en developer.digikey.com con tu cuenta de DigiKey.

2. Abre Organizaciones en la barra de navegación y crea una si aún no eres miembro.

3. En Operaciones, elige Aplicaciones de producción y, a continuación, Crear aplicación de producción.

4. Habilita Información de producto para la aplicación.

5. Abre la aplicación para copiar su ID de cliente y Secreto de cliente.

El campo de callback de OAuth solo se utiliza en el flujo OAuth de tres patas. Este servidor utiliza el flujo de credenciales de cliente de dos patas, por lo que nunca se redirige al callback; https://localhost es suficiente para el formulario.

Las credenciales de sandbox y de producción no son intercambiables. Las de sandbox solo funcionan contra sandbox-api.digikey.com, que es lo que selecciona DIGIKEY_SANDBOX=true.

Mouser. Solicita una clave de Search API en mouser.com/api-hub. Es una clave única, se envía como parámetro de consulta y llega por correo electrónico.

Configuración del cliente 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": "..."
      }
    }
  }
}

Límites de tasa

Ambos distribuidores conceden aproximadamente mil llamadas al día, por lo que cada solicitud tiene un presupuesto. Las ventanas por segundo y por minuto se gestionan mediante esperas; la ventana diaria es un tope firme que, en su lugar, notifica un error, ya que quien llama no puede esperar de forma útil a que se restablezca una cuota que se reinicia a medianoche. El contador diario se guarda de forma persistente, por lo que reiniciar el servidor no lo restablece.

Valores por defecto:

Cada valor es configurable por proveedor, ya sea mediante una variable de entorno o mediante un archivo TOML. Usa none, off, unlimited o 0 para desactivar una ventana:

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

O apunta DMS_CONFIG a un archivo; consulta config.example.toml. Las variables de entorno anulan el archivo, de modo que el comando de lanzamiento de un cliente puede ajustar un límite sin editar la configuración en disco.

Las respuestas en caché se sirven sin gastar presupuesto. source_status informa de lo que queda para el día.

Otros ajustes

Arquitectura

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

Flujo de la solicitud para una llamada a un proveedor:

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

Notas sobre las dos APIs

DigiKey usa credenciales de cliente OAuth2. El token dura diez minutos y se almacena en caché en memoria; las solicitudes necesitan la cabecera de id de cliente junto con el token de portador. Los filtros se expresan como identificadores opacos, por lo que un nombre de fabricante se resuelve primero a través del endpoint de fabricantes.

Mouser usa una clave de API que se pasa como parámetro de consulta y responde con HTTP 200 incluso cuando la solicitud falla, colocando el fallo en un array Errors. El adaptador considera ese array como la fuente autoritativa. Los precios llegan como cadenas de visualización localizadas en lugar de números.

Las especificaciones paramétricas no tienen un vocabulario compartido entre los dos distribuidores, por lo que se pasan como un mapa de nombre/valor en lugar de normalizarse a un esquema común.

Claude Code se utilizó en la creación de esta herramienta.