Servidor MCP de Grips Intelligence (v2)

Un servidor de Protocolo de Contexto de Modelo (MCP) que expone la API de datos de comercio electrónico de Grips Intelligence a cualquier cliente MCP: Claude Desktop, Cowork, Claude Code, etc.

v2 es una reconstrucción limpia de la v1 con manejo defensivo de datos integrado desde el primer día. Corrige la clase de errores ".map is not a function" que la v1.x necesitaba un parche en tiempo de ejecución para solucionar: los dominios con poca información o desconocidos ahora se degradan a una respuesta limpia de "sin datos" en lugar de bloquear la llamada a la herramienta.

Qué incluye

Todas las herramientas utilizan por defecto la salida en markdown para facilitar la lectura. Pase format: "json" para obtener una salida legible por máquina.

Instalación

npm install

El script prepare compila automáticamente dist/ cuando ejecutas npm install.

Configuración

Establece tu clave de API de Grips en la configuración del servidor del cliente MCP. Para Claude Desktop, es ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "grips": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
      ],
      "env": {
        "GRIPS_API_KEY": "your-api-key-here",
        "GRIPS_DEFAULT_COUNTRY": "US"
      }
    }
  }
}

Entorno requerido:

• GRIPS_API_KEY: tu token de API de Grips (enviado como el encabezado grips-api-key).

Entorno opcional:

• GRIPS_DEFAULT_COUNTRY: US, GB o DE. Por defecto es US si no se establece o no es válido.

Después de editar la configuración, cierra completamente Claude Desktop (Cmd+Q, no solo cerrando la ventana) y vuelve a abrirlo.

Qué es diferente de la v1

La v1 fallaba con una forma de respuesta de API específica: cuando Grips devolvía un dominio con poca cobertura o desconocido, el campo timeseries devolvía {} en lugar de null, undefined o []. El código usaba (data.timeseries ?? []).map(...), que solo protege contra null/undefined, no contra {}. Resultado: "data.timeseries ?? []).map is not a function".

La v2 enruta cada campo de carga útil a través de toArray<T>() (para matrices) o toObject<T>() (para respuestas con forma de diccionario como el endpoint de dispositivos) antes de su uso. Cualquier valor que no sea una matriz o un objeto pasa a un valor predeterminado vacío seguro, y la herramienta devuelve una respuesta limpia de "sin datos" en lugar de lanzar un error.

Otros cambios:

• La normalización de fechas es consistente (cada fecha se convierte a YYYY-MM-DD en UTC) en todas las herramientas, por lo que las filas no se desplazan entre los límites de los días en zonas horarias que no son UTC.

• Los formateadores de moneda / enteros / porcentajes muestran — para los valores faltantes en lugar de $NaN o 0.00%.

• Los mensajes de error ahora incluyen sugerencias procesables: 401 → "comprueba tu clave de API", 429 → "límite de tasa alcanzado, reduce tu ventana", etc.

• Aislamiento de errores por dominio en grips_compare_domains: un dominio con poca información en una comparación de 8 dominios ya no rompe los otros siete.

• Truncamiento del presupuesto de caracteres: las respuestas se limitan a ~200 KB con un aviso visible para que las extracciones de múltiples dominios no saturen la ventana de contexto.

Desarrollo

npm run dev    # watch mode, rebuilds on change
npm run build  # one-shot build to dist/

Pruebas desde la línea de comandos

Prueba que el servidor arranca sin errores (se cerrará al recibir EOF desde stdin):

GRIPS_API_KEY=your-key node dist/index.js < /dev/null

Deberías ver [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). en stderr y ningún bloqueo.

Para pruebas interactivas, utiliza @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Referencia de la API

Grips documenta su esquema público en https://gripsintelligence.com/knowledge-base/api. Las consultas que utiliza este servidor están copiadas literalmente de esa página.

Países admitidos actualmente: US, GB, DE. Cualquier otro dará error en la API.

Licencia

Privada: no apta para distribución externa.