catalog-mcp

Un servidor MCP que convierte cualquier catálogo JSON en herramientas de consulta para agentes de IA.

Apúntalo a una URL o archivo de catálogo — un feed de inventario, una lista de productos, el catalog.json que publica feedmerge — y cualquier cliente MCP (Claude Desktop, Claude Code, cualquier cosa que hable el protocolo) obtiene filtrado estructurado, agrupación, clasificación y descubrimiento de esquemas sobre tus registros.

Node 18+. Dos dependencias de ejecución: el SDK de MCP y zod.

Por qué

Los agentes son malos con archivos JSON grandes y buenos con herramientas. Dale a un agente un catálogo de 2 MB y truncará, hojeará o alucinará registros; dale catalog_query con una gramática de filtros y responderá "el registro más barato por debajo de $30k con estas dos características" correctamente cada vez, leyendo solo los registros que coinciden.

Este repositorio es la versión generalizada de un servidor MCP que ejecuto en producción: un asistente de IA en el piso de ventas consulta un catálogo de inventario en vivo exactamente a través de estas herramientas (misma semántica de filtros, misma regla de precio nulo, misma caché TTL) cientos de veces al día. El pipeline al que pertenece:

vendor feed  ->  feedmerge  ->  catalog.json  ->  catalog-mcp  ->  any agent
             (guarded sync)   (versioned)      (query tools)

Ejecuto esto contra mi propio feed de inventario público; el ejemplo a continuación usa un catálogo neutral para que el repositorio sea independiente.

Inicio rápido

git clone https://github.com/stevyf93II/catalog-mcp.git
cd catalog-mcp
npm install
npm test                                          # engine, loader, and stdio end-to-end tests

# serve the example catalog
node src/server.js --file examples/telescopes.json --key sku

Conéctalo a Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "my-catalog": {
      "command": "node",
      "args": ["/path/to/catalog-mcp/src/server.js"],
      "env": {
        "CATALOG_URL": "https://example.com/catalog.json",
        "CATALOG_KEY": "sku"
      }
    }
  }
}

Luego pregúntale al agente cosas como "qué tipos hay en el catálogo y cuánto cuesta cada uno en el extremo inferior?" y observa cómo compone catalog_schema, catalog_count_by y catalog_top por sí mismo.

Herramientas

Todas las herramientas son de solo lectura e idempotentes, y lo indican en sus anotaciones MCP.

La gramática de filtros

Una pequeña especificación, utilizada por query, count_by y top:

{
  "eq":       { "type": "reflector", "goto": true },
  "min":      { "aperture_mm": 150 },
  "max":      { "price": 1000 },
  "has":      { "features": ["Parabolic Mirror", "Cooling Fan"] },
  "contains": { "name": "dobsonian" }
}

• eq — igualdad estricta en cualquier valor, incluidos booleanos y null.

• min / max — límites numéricos. Un registro sin un número real en un campo acotado es excluido. Esta regla es fundamental: en el catálogo de producción, un precio faltante significa "llamar para precio", y "muéstrame unidades por debajo de $30k" nunca debe mostrar una unidad cuyo precio se desconoce.

• has — pertenencia a un array; cada valor listado debe estar presente.

• contains — subcadena sin distinción de mayúsculas/minúsculas en un campo de cadena; el campo "*" busca en todos los campos de cadena del registro.

Las condiciones se combinan con AND. Una clave de nivel superior desconocida es un error que nombra las claves válidas, porque un filtro ignorado silenciosamente es cómo un agente reporta con confianza respuestas incorrectas.

La ordenación empuja los registros que carecen del campo de ordenación al final, en ambas direcciones — "ordenar por precio" muestra primero los registros con precio, no un muro de nulos.

Configuración

Cuando no se establece CATALOG_RECORDS_PATH, el cargador usa la raíz del documento si es un array, o el único array de nivel superior de objetos si hay exactamente uno ({ "meta": ..., "items": [...] } funciona). Si el documento es ambiguo, se niega y nombra las claves candidatas.

En una actualización fallida, el servidor sirve los últimos datos buenos en lugar de dar error — un agente en medio de una tarea está mejor con registros de hace cinco minutos que con una excepción — y catalog_stats reporta la antigüedad de la caché para que la obsolescencia nunca esté oculta.

No objetivos

• No es una base de datos. El catálogo es de solo lectura y reside en memoria; si tus datos no caben cómodamente en un archivo JSON, necesitas un almacén real.

• Sin escrituras. Nada aquí muta el catálogo — ese es el trabajo del pipeline de sincronización (ver feedmerge).

• Sin lenguaje de consulta. Cinco claves de filtro cubren lo que los agentes realmente preguntan; cualquier cosa más sofisticada pertenece al código, no a un esquema de herramienta.

Licencia

MIT