Przejdź do treści
Garanify

MCP server for AI agents

With the Garanify MCP server, Claude, Cursor and other MCP clients work with your shop directly: find invalid products, explain why a label is missing, test values in a preview and fix them.

The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.

The server runs locally over stdio (JSON-RPC 2.0, MCP versions 2025-06-18, 2025-03-26, 2024-11-05) and only calls documented API endpoints through the Node.js SDK. It is built and tested but not published on npm yet; until then you start it from the repository.

Configure

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
VariableMeaning
GARANIFY_API_KEYSecret key of the shop. Start with a test key (gfy_sk_test_…). The server refuses publishable keys.
GARANIFY_BASE_URLDefault https://api.garanify.com (in preparation), local http://localhost:8788.
GARANIFY_SHOPShop ID, optional; otherwise from GET /v1/me.
GARANIFY_MCP_READONLY1 = only reading tools. Recommended for assistants that should not change data.

Tools

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so the client can ask before writing. This list is built from the server code.

ToolKindDescription (as the agent sees it)
garanify_overviewreadShop, plan, GARAN allowance and counts of products per status (label, none, hidden, invalid). Call this first.
garanify_list_productsreadOne page of products (sorted by SKU) with their resolved label and errors. Use nextCursor for the next page.
garanify_list_invalid_productsreadAll 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_productreadA stored product with its resolved label.
garanify_explain_labelreadWhich 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_labelreadResolves product values against the rules of the shop without storing anything. Use it to check values before garanify_upsert_product.
garanify_upsert_productwriteStores 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_productswriteAtomic bulk upsert (Pro and Agency). If one item does not match the schema, nothing is written.
garanify_delete_productwrite, destructiveDeletes the product. Its label disappears from the shop. Only on explicit request of the user.
garanify_list_rulesreadOrdered rules (brand, category, tag → years). The first matching rule applies; product values always win.
garanify_replace_ruleswrite, destructiveReplaces the whole ordered rule list (Pro and Agency). Read the current rules first and send the complete new list.
garanify_render_labelreadThe official GARAN label as SVG: for a stored product (sku) or for given values (years, brand, model). Invalid values return the reason.
garanify_export_evidencereadEvidence of what the shop shows: notice rows per language and one row per product with GARAN data. Pro and Agency.
garanify_update_notice_settingswriteChanges 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_statusreadThe webhook endpoint of the shop (URL, events, last outcome) and the latest deliveries (delivered, rejected, unreachable, pending).
garanify_languagesreadThe 24 EU languages with the official notice title and the GARAN term.

Errors and safety

  • API errors come back as tool errors with the stable code, errors and requestId, so the agent can correct its input (errors and codes).
  • Arguments are checked against the input schema before the call; the server rejects unknown fields.
  • Give the agent a test key and GARANIFY_MCP_READONLY=1 first. The key stays on your machine; the server only sends it to the base URL.

Instructions for the agent

On connect, the server sends these instructions:

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.