eparts-search-mcp

Un servidor MCP que busca componentes electrónicos en DigiKey, LCSC y Mouser. Cada distribuidor se puede consultar por separado o todos juntos, fusionando las ofertas del mismo número de pieza 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. Los resultados se fusionan por número de pieza por defecto, con una comparación cheapest_at_quantity; pasa merge=false para mantener los resultados de cada distribuidor en una lista separada.

La comparación solo considera ofertas que tienen un precio en la cantidad solicitada. LCSC vende muchas piezas en múltiplos de diez, por lo que a una cantidad de uno, una oferta así no tiene un tramo aplicable y se excluye de la comparación en lugar de contarse como gratuita.

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

Related MCP server: Nexar MCP Server

Instalación

Para usar el servidor desde cualquier lugar del sistema, instálalo como una herramienta independiente. El ejecutable se coloca en ~/.local/bin ($XDG_BIN_HOME si está definido), con sus dependencias en su propio entorno bajo ~/.local/share/uv/tools:

uv tool install .

mise run install-tool hace lo mismo, y mise run uninstall-tool lo elimina. Después de instalar, eparts-search-mcp ejecuta el servidor en stdio desde cualquier directorio, leyendo las credenciales del archivo de configuración XDG descrito a continuación. No se toca nada fuera de ~/.local y ~/.config, por lo que no se necesita un paso de instalación privilegiado.

Asegúrate de que ~/.local/bin esté en PATH:

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

Configuración de desarrollo

Para trabajar en el servidor en lugar de usarlo:

mise install
mise run install
mise run test

Las credenciales pueden provenir de un archivo de configuración o del entorno. El archivo las mantiene fuera del entorno y de los listados de procesos; se lee por defecto desde ~/.config/eparts-search-mcp/config.toml (o $XDG_CONFIG_HOME si está definido), por lo que no se necesita 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 = "..."

Como el archivo contiene secretos, mantenlo legible solo para ti. El servidor advierte al inicio si es accesible para el grupo u otros:

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

Los mismos valores también pueden suministrarse a través del entorno, que anula el archivo:

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

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

Obtención de credenciales

DigiKey. Una aplicación de desarrollador personal solo obtiene acceso de sandbox, y el sandbox devuelve datos sintéticos. Para stock y precios reales necesitas una aplicación de Producción, que vive bajo una Organización:

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

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

3. En Operations, elige Production Apps y luego Create Production App.

4. Habilita Product Information para la aplicación.

5. Abre la aplicación para copiar su Client ID y Client Secret.

El campo de devolución de llamada OAuth solo se usa en OAuth de tres patas. Este servidor usa el flujo de credenciales de cliente de dos patas, por lo que la devolución de llamada nunca se redirige; https://localhost satisface el formulario.

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

LCSC. La API abierta es una integración de socio en lugar de un registro de autoservicio, por lo que las credenciales provienen de un administrador de cuentas de LCSC después de que la dirección IP de llamada haya sido incluida en la lista blanca. La incorporación comienza en un entorno de prueba en un host separado (fatapi.lcsc.com) que responde con datos de catálogo simulados; LCSC_SANDBOX=true lo selecciona. Las credenciales de producción llegan una vez que la integración está aprobada y se usan contra api.lcsc.com.

Una llamada se autentica mediante una firma SHA-256 sobre los parámetros de la solicitud, la clave, un nonce por solicitud y una marca de tiempo. El secreto es una entrada de ese hash y nunca se transmite, por lo que nunca aparece en una URL o en un registro; la marca de tiempo se verifica, lo que significa que un reloj del sistema muy desajustado se lee como una solicitud caducada en lugar de una clave rechazada.

Mouser. Solicita una clave de API de búsqueda en mouser.com/api-hub. Es una clave única, enviada como parámetro de consulta, y llega por correo electrónico.

Configuración del cliente MCP

Una vez instalado como se indicó arriba, el comando está en PATH y no necesita ruta ni entorno, ya que las credenciales provienen del archivo de configuración:

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

Algunos clientes lanzan servidores con un entorno mínimo que no incluye ~/.local/bin; usa la ruta absoluta allí en su lugar:

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

Para ejecutar desde un checkout de código fuente sin instalar, o para pasar credenciales a través del cliente en lugar del archivo de configuración:

{
  "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": "..."
      }
    }
  }
}

Límites de velocidad

Cada distribuidor otorga aproximadamente mil llamadas por día, por lo que cada solicitud está presupuestada. Las ventanas por segundo y por minuto se aplican esperando; la ventana diaria es una parada dura que informa un error en su lugar, ya que un llamador no puede esperar útilmente una cuota que se restablece a medianoche. El contador diario se persiste, por lo que reiniciar el servidor no lo restablece.

Valores predeterminados:

LCSC documenta 60 búsquedas por palabra clave por minuto y mil por día, y solo cuenta las llamadas que tienen éxito. Su valor predeterminado por minuto se establece por debajo del techo documentado, ya que ser limitado por el distribuidor cuesta más que esperar localmente. Cuando el propio contador de LCSC rechaza una llamada de todos modos, el error lo dice, para distinguirlo del presupuesto local.

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

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

Estos también viven en el archivo de configuración (~/.config/eparts-search-mcp/config.toml por defecto, o donde apunte EPARTS_CONFIG), consulta config.example.toml. Las variables de entorno anulan el archivo, por lo que un comando de lanzamiento del 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 lo que queda para el día.

Otros ajustes

Archivos en disco

Todo lo que el servidor guarda vive bajo los directorios base XDG, por lo que una instalación no posee nada fuera del directorio de inicio:

XDG_CONFIG_HOME y XDG_STATE_HOME se establecen por defecto en ~/.config y ~/.local/state cuando no están definidos. EPARTS_CONFIG y EPARTS_CACHE_PATH anulan los dos últimos. Desinstalar con uv tool uninstall eparts-search-mcp deja la configuración y la caché en su lugar; elimina esos directorios para quitarlos también.

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 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

Flujo de solicitud para una llamada de 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 tres APIs

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

LCSC firma cada solicitud en lugar de llevar un token: la clave, un nonce, una marca de tiempo y los parámetros de consulta ordenados se mezclan con el secreto, y el resumen viaja en un encabezado. Al igual que Mouser, responde con HTTP 200 incluso cuando la solicitud falló, poniendo el resultado real en el campo code del cuerpo, que el adaptador trata como autoritativo. No hay un endpoint por pieza, por lo que una consulta de detalles es una búsqueda por palabra clave de la que se extrae la coincidencia exacta; una búsqueda por palabra clave que devuelve solo coincidencias cercanas no produce ningún resultado en lugar de uno plausible incorrecto. Tampoco hay filtro de fabricante, por lo que un fabricante se incorpora a la palabra clave y los resultados se filtran en el camino de regreso.

Mouser usa una clave de API pasada como parámetro de consulta y responde con HTTP 200 incluso cuando la solicitud falló, poniendo el fallo en un array Errors. El adaptador trata ese array como autoritativo. 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 tres distribuidores, por lo que se pasan como un mapa de nombre/valor en lugar de normalizarse en un esquema común. El recargo por bobina de LCSC se informa de la misma manera, ya que es una tarifa por pedido que la escalera de precios por unidad no puede expresar.

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