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
{
"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 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 | Variable | Bedeutung |
|---|---|
GARANIFY_API_KEY | Secret Key des Shops. Beginnen Sie mit einem Testschlüssel (gfy_sk_test_…). Publishable Keys lehnt der Server ab. |
GARANIFY_BASE_URL | Standard https://api.garanify.com (in Vorbereitung), lokal http://localhost:8788. |
GARANIFY_SHOP | Shop-ID, optional; sonst aus GET /v1/me. |
GARANIFY_MCP_READONLY | 1 = 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.
| Werkzeug | Art | Beschreibung (englisch, so sieht es der Agent) |
|---|---|---|
garanify_overview | liest | Shop, plan, GARAN allowance and counts of products per status (label, none, hidden, invalid). Call this first. |
garanify_list_products | liest | One page of products (sorted by SKU) with their resolved label and errors. Use nextCursor for the next page. |
garanify_list_invalid_products | liest | All 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_product | liest | A stored product with its resolved label. |
garanify_explain_label | liest | Which 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_label | liest | Resolves product values against the rules of the shop without storing anything. Use it to check values before garanify_upsert_product. |
garanify_upsert_product | schreibt | Stores 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_products | schreibt | Atomic bulk upsert (Pro and Agency). If one item does not match the schema, nothing is written. |
garanify_delete_product | schreibt, löscht | Deletes the product. Its label disappears from the shop. Only on explicit request of the user. |
garanify_list_rules | liest | Ordered rules (brand, category, tag → years). The first matching rule applies; product values always win. |
garanify_replace_rules | schreibt, löscht | Replaces the whole ordered rule list (Pro and Agency). Read the current rules first and send the complete new list. |
garanify_render_label | liest | The official GARAN label as SVG: for a stored product (sku) or for given values (years, brand, model). Invalid values return the reason. |
garanify_export_evidence | liest | Evidence of what the shop shows: notice rows per language and one row per product with GARAN data. Pro and Agency. |
garanify_update_notice_settings | schreibt | Changes 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_status | liest | The webhook endpoint of the shop (URL, events, last outcome) and the latest deliveries (delivered, rejected, unreachable, pending). |
garanify_languages | liest | The 24 EU languages with the official notice title and the GARAN term. |
Fehler und Sicherheit
- API-Fehler kommen als Werkzeugfehler mit dem stabilen
code,errorsundrequestIdzurü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.