Zum Inhalt springen
Garanify

MCP-Server für KI-Agenten

Mit dem Garanify-MCP-Server arbeiten Claude, Cursor und andere MCP-Clients direkt mit Ihrem Shop: ungültige Produkte finden, erklären, warum ein Etikett fehlt, Werte in der Vorschau testen und korrigieren.

Die API ist gebaut und getestet. Das Hosting unter api.garanify.com ist in Vorbereitung; bis dahin läuft sie lokal. Schlüssel gibt es auf Anfrage.

Der Server läuft lokal über stdio (JSON-RPC 2.0, MCP-Versionen 2025-06-18, 2025-03-26, 2024-11-05) und ruft nur dokumentierte API-Endpunkte über das Node.js-SDK auf. Er ist fertig und getestet, aber noch nicht auf npm veröffentlicht; bis dahin starten Sie ihn aus dem Repository.

Einrichten

claude_desktop_config.json / .cursor/mcp.json
{
  "mcpServers": {
    "garanify": {
      "command": "node",
      "args": ["/path/to/gewaehrleistung/packages/mcp/src/cli.js"],
      "env": {
        "GARANIFY_API_KEY": "gfy_sk_test_…",
        "GARANIFY_BASE_URL": "http://localhost:8788",
        "GARANIFY_MCP_READONLY": "1"
      }
    }
  }
}
Claude Code
claude mcp add garanify \
  --env GARANIFY_API_KEY=gfy_sk_test_… \
  --env GARANIFY_BASE_URL=http://localhost:8788 \
  -- node /path/to/gewaehrleistung/packages/mcp/src/cli.js
VariableBedeutung
GARANIFY_API_KEYSecret Key des Shops. Beginnen Sie mit einem Testschlüssel (gfy_sk_test_…). Publishable Keys lehnt der Server ab.
GARANIFY_BASE_URLStandard https://api.garanify.com (in Vorbereitung), lokal http://localhost:8788.
GARANIFY_SHOPShop-ID, optional; sonst aus GET /v1/me.
GARANIFY_MCP_READONLY1 = nur lesende Werkzeuge. Empfohlen für Assistenten, die nichts ändern sollen.

Werkzeuge

Jedes Werkzeug hat MCP-Annotationen (readOnlyHint, destructiveHint, idempotentHint), damit der Client vor dem Schreiben nachfragen kann. Diese Liste entsteht beim Build aus dem Code des Servers.

WerkzeugArtBeschreibung (englisch, so sieht es der Agent)
garanify_overviewliestShop, plan, GARAN allowance and counts of products per status (label, none, hidden, invalid). Call this first.
garanify_list_productsliestOne page of products (sorted by SKU) with their resolved label and errors. Use nextCursor for the next page.
garanify_list_invalid_productsliestAll products with status "invalid" and the reasons (years_too_low, years_not_half, brand_missing, model_missing, …). These are compliance gaps to fix.
garanify_get_productliestA stored product with its resolved label.
garanify_explain_labelliestWhich GARAN label a stored product shows and why (own value, main product, rule number, hidden, invalid, no years), with the alternative text in the given language.
garanify_preview_labelliestResolves product values against the rules of the shop without storing anything. Use it to check values before garanify_upsert_product.
garanify_upsert_productschreibtStores the product under its SKU (replaces all fields). Invalid guarantee data is stored with status "invalid" and shows no label. On Free, adding a label beyond the allowance fails with garan_limit_reached.
garanify_bulk_upsert_productsschreibtAtomic bulk upsert (Pro and Agency). If one item does not match the schema, nothing is written.
garanify_delete_productschreibt, löschtDeletes the product. Its label disappears from the shop. Only on explicit request of the user.
garanify_list_rulesliestOrdered rules (brand, category, tag → years). The first matching rule applies; product values always win.
garanify_replace_rulesschreibt, löschtReplaces the whole ordered rule list (Pro and Agency). Read the current rules first and send the complete new list.
garanify_render_labelliestThe official GARAN label as SVG: for a stored product (sku) or for given values (years, brand, model). Invalid values return the reason.
garanify_export_evidenceliestEvidence of what the shop shows: notice rows per language and one row per product with GARAN data. Pro and Agency.
garanify_update_notice_settingsschreibtChanges where the notice appears (product, cart, checkout, footer, email), its width and the product label display (full or nested). The notice is a legal duty: do not disable it unless the shop shows it another way.
garanify_webhook_statusliestThe webhook endpoint of the shop (URL, events, last outcome) and the latest deliveries (delivered, rejected, unreachable, pending).
garanify_languagesliestThe 24 EU languages with the official notice title and the GARAN term.

Fehler und Sicherheit

  • API-Fehler kommen als Werkzeugfehler mit dem stabilen code, errors und requestId zurück, damit der Agent seine Eingabe korrigieren kann (Fehler und Codes).
  • Argumente werden vor dem Aufruf gegen das Eingabeschema geprüft; unbekannte Felder lehnt der Server ab.
  • Geben Sie dem Agenten zuerst einen Testschlüssel und GARANIFY_MCP_READONLY=1. Der Schlüssel bleibt auf Ihrem Rechner; der Server sendet ihn nur an die Base-URL.

Anweisungen an den Agenten

Beim Verbinden schickt der Server diese Hinweise mit:

Garanify shows the EU notice on the legal guarantee and the GARAN label (Implementing Regulation (EU) 2025/1960) in online shops.
- The GARAN label appears only for a free producer guarantee of MORE than 2 years, in whole or half years, with brand and model identifier.
- The model identifier is garan.model, otherwise the MPN, otherwise the SKU. Never use a GTIN/EAN as model.
- Product values win over rules; variants inherit from their main product (parentSku); the first matching rule applies.
- Start with garanify_overview. Use garanify_explain_label before changing data, and garanify_preview_label to test values without saving.
- Products with status "invalid" show no label: fix them with garanify_list_invalid_products and garanify_upsert_product.
Not legal advice.