Grips Intelligence MCP-Server (v2)

Ein Model Context Protocol (MCP)-Server, der die E-Commerce-Daten-API von Grips Intelligence für jeden MCP-Client verfügbar macht — Claude Desktop, Cowork, Claude Code usw.

v2 ist eine saubere Neuentwicklung von v1, bei der von Anfang an eine defensive Datenverarbeitung integriert wurde. Sie behebt die Klasse von Fehlern wie ".map is not a function", für die v1.x einen Laufzeit-Patch benötigte — bei dünnen oder unbekannten Domains erfolgt nun eine saubere "Keine Daten"-Antwort, anstatt dass der Tool-Aufruf abstürzt.

Was ist enthalten

Alle Tools geben standardmäßig Markdown für bessere Lesbarkeit aus. Übergeben Sie format: "json" für eine maschinenlesbare Ausgabe.

Installation

npm install

Das prepare-Skript erstellt automatisch dist/, wenn Sie npm install ausführen.

Konfiguration

Setzen Sie Ihren Grips-API-Schlüssel in der Serverkonfiguration des MCP-Clients. Für Claude Desktop ist das ~/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"
      }
    }
  }
}

Erforderliche Umgebungsvariable:

• GRIPS_API_KEY — Ihr Grips-API-Token (wird als grips-api-key-Header gesendet).

Optionale Umgebungsvariable:

• GRIPS_DEFAULT_COUNTRY — US, GB oder DE. Standardmäßig US, falls nicht gesetzt oder ungültig.

Starten Sie nach dem Bearbeiten der Konfiguration Claude Desktop vollständig neu (Cmd+Q — nicht nur das Fenster schließen).

Was ist anders als bei v1

v1 stürzte bei einer bestimmten API-Antwortform ab: Wenn Grips eine dünn abgedeckte oder unbekannte Domain zurückgab, kam das timeseries-Feld als {} zurück anstatt als null, undefined oder []. Der Code verwendete (data.timeseries ?? []).map(...), was nur gegen null/undefined absichert — nicht gegen {}. Ergebnis: "data.timeseries ?? []).map is not a function".

v2 leitet jedes Payload-Feld vor der Verwendung durch toArray<T>() (für Arrays) oder toObject<T>() (für dict-artige Antworten wie den Geräte-Endpunkt). Jeder Wert, der kein Array/Objekt ist, fällt auf einen sicheren leeren Standardwert zurück, und das Tool gibt eine saubere "Keine Daten"-Antwort zurück, anstatt einen Fehler auszulösen.

Weitere Änderungen:

• Datumsnormalisierung ist konsistent (jedes Datum wird zu YYYY-MM-DD in UTC) über alle Tools hinweg, sodass Zeilen in Zeitzonen außerhalb von UTC nicht über Tagesgrenzen hinweg verrutschen.

• Währungs- / Ganzzahl- / Prozentformatierer rendern — für fehlende Werte anstelle von $NaN oder 0.00%.

• Fehlermeldungen enthalten jetzt hilfreiche Hinweise — 401 → "Überprüfen Sie Ihren API-Schlüssel", 429 → "Ratenbegrenzung erreicht, Zeitraum einschränken" usw.

• Fehlerisolierung pro Domain in grips_compare_domains — eine dünne Domain in einem Vergleich von 8 Domains bringt die anderen sieben nicht mehr zum Absturz.

• Zeichenbegrenzung — Antworten werden bei ca. 200 KB mit einem sichtbaren Hinweis gekappt, damit Abrufe über mehrere Domains das Kontextfenster nicht sprengen.

Entwicklung

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

Testen über die Befehlszeile

Testen Sie, ob der Server ohne Fehler startet (er beendet sich bei EOF von stdin):

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

Sie sollten [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). auf stderr sehen und keinen Absturz.

Für interaktive Tests verwenden Sie @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node dist/index.js

API-Referenz

Grips dokumentiert sein öffentliches Schema unter https://gripsintelligence.com/knowledge-base/api. Die Abfragen, die dieser Server verwendet, sind wortwörtlich von dieser Seite kopiert.

Unterstützte Länder aktuell: US, GB, DE. Alles andere führt zu einem Fehler bei der API.

Lizenz

Privat — nicht für die externe Verbreitung bestimmt.