io.github.giuseppesocci-bot/kalicart-global

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "kalicart-global": {
      "url": "https://global.kalicart.com/mcp-public",
      "transport": "streamable-http"
    }
  }
}

Measured tools (9)

• global_search read-only

  Use this when a user wants to find or compare product candidates across participating WooCommerce merchants. Search cards include bounded variants_compact and variant_option_values from the merchant snapshot. Option values are independent and do not prove a purchasable combination. Verify the selected variant, price and stock through its merchant Bridge handoff before confirming an offer. For a request with multiple distinct items, search each item independently (calls may run in parallel), then pass the selected p2209_id values together to verify_basket. Use get_product only when a search card lacks needed indexed details.

  Parameters:

  • q — string — Free-text product query. Each term must match as a whole word in the native merchant catalog text (name, short description, description) or in the canonical category path, so English category terms reach catalogs written in other languages: q="mattress" returns products under home.bedroom.mattress even when their text is Italian. There is no server-side translation of product text; for language-neutral retrieval by category use leaf and the canonical filters.
  • leaf — string — Canonical category node. Accepts a terminal leaf (e.g. beverages.alcohol.sparkling_prosecco) or any parent node (e.g. jewellery, home.bedroom): a parent matches the node and its whole subtree, so you can widen or narrow the search by moving up or down the tree. Use list_categories to browse the tree.
  • brand — string — Brand facet filter (normalized, e.g. "nike")
  • color — string — Bridge color family (e.g. "blue"). Common aliases are resolved to a family available in the active index. A family match does not guarantee an exact shade; read filter_semantics.color and verify the chosen product via handoff.bridge_product_url.
  • limit — integer — Max offers per page (1-25, default 10). Use next_cursor for the next page.
  • cursor — string — Opaque next_cursor from a previous global_search with the SAME arguments; returns the next page. A cursor from a different query is rejected.
  • gender — string — Canonical gender facet. Filtering is discovery-tolerant: untagged and unisex products can remain candidates, so verify the chosen product. Allowed values: female, male, unisex.
  • variant — Constraints that must ALL hold on the SAME variant. Keys and values are the merchant's own, in any language or script (read variant_vocabulary first): {"pa_taglia":"L"}, {"size":["L","Large"]}, {"*":["rouge","rosso"]} (* = any option), or [{"keys":["pa_taglia","size"],"values":["L","Large"]}] across merchants. KaliCart never translates: pass every value you accept. match.kind: exact (ignoring case, Latin accents, separators) or normalized (same number+unit symbol, NxN, size code). Indexed snapshot: verify on the merchant before quoting.
  • in_stock — boolean — true filters product-level stock in the indexed snapshot. Does not verify a selected variant or a booking slot.
  • merchant — string — Restrict to one merchant: merchant_id as returned in result_facets.merchants or offers (e.g. "duinshop-it") or its domain.
  • max_price — number — Upper bound in major currency units (for example 1550 means EUR 1,550 for EUR offers). A matching range may include variants above this bound; verify the chosen variant. Per-offer currency, no FX conversion.
  • min_price — number — Lower bound in major currency units (for example 50 means EUR 50 for EUR offers). Matches overlapping variant price ranges in each offer currency; no FX conversion. Verify the chosen variant.
  • result_facets — boolean — true adds result_facets: counts over ALL matching offers (not just this page) by merchant, category leaf, brand, availability, and price quartiles per currency. Use them to narrow the next call.
  • variant_limit — integer — Max matching variants returned per offer (1-500, default 50); matching_variant_count is always the full count
  • variant_facets — boolean — true adds variant_vocabulary: real option keys and values with variant and in-stock counts, for the offers returned or, with no q, for the merchant (or all merchants). Use it to choose the values to pass in variant.
  • variant_in_stock — boolean — true keeps only variants whose own availability is in_stock
  • variant_price_max — number — Upper bound on the variant price (major units)
  • variant_price_min — number — Lower bound on the variant price (major units)
  • variant_facets_limit — integer — Max values per option key in variant_vocabulary (1-200, default 40); values_total is always the full count
  • variant_price_currency — string — ISO 4217 currency of variant_price_min/max (e.g. EUR). With it, only variants priced in that currency satisfy the bound; no FX conversion. Without it, bounds compare numbers in each variant's own currency.

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_offer_attestation read-only

  Returns a cryptographic proof that this offer's product row is exactly the one the merchant signed in its catalog snapshot: the signed row, its bucket hashes, the Ed25519-signed manifest, the merchant public key and step-by-step verification. Trust is anchored on the merchant domain (key fingerprint published at key_anchor), not on KaliCart. It proves the row as signed at snapshot.generated_at, not the current price or stock: the checkout is authoritative. Independent verifier: https://global.kalicart.com/ucp/tools/verify-offer-attestation.js

  Parameters:

  • p2209_id (required) — string — Offer id from global_search (e.g. prod_duinshop-it_446678).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• estimate_delivered_cost read-only

  Deterministic estimate from the merchant's own data: item price x quantity plus the shipping options the store declares for the destination (flat rate = declared base rate; free shipping with its threshold, whether this quantity reaches it and how much is missing). Lists what is not included (shipping classes, cost formulas, duties, taxes on shipping). Pass variation_id for variable products. Valid within max_age_seconds of the last merchant confirmation; live=true reads the merchant now. The checkout is the only authority.

  Parameters:

  • p2209_id (required) — string
  • destination (required) — string — ISO 3166-1 country, optionally with region: "IT" or "IT:CB".
  • live — boolean
  • quantity — integer
  • variation_id — integer
  • max_age_seconds — integer

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• verify_basket read-only

  For a multi-item request, collect p2209_id and any selected variation_id from global_search results and send all selected items in one call. For every variable product, include a variation_id from its selected variants_compact entry on the first call; without it the price and basket total may be unknown. Never substitute WooCommerce numeric product IDs for p2209_id. Set live=false for a snapshot-only check with no merchant request; live=true reads merchants. Checks a basket of offers (up to 40 lines, any merchants) against the merchants' own data. Per merchant: subtotal, declared shipping options, and checkout handoff. Optional quote=true requires live=true and destination_details; it makes one bounded merchant request per basket and returns a WooCommerce quote when the merchant enabled it, otherwise unknown alongside the estimate. A quote creates no checkout session or order; checkout may still change the total.

  Parameters:

  • items (required) — array
  • live — boolean — false (default) uses saved Global data without contacting merchants; true reads each merchant now (at most 10 lines).
  • quote — boolean — false by default. true requires live=true and destination_details, and may contact up to four merchants for WooCommerce quotes.
  • destination — string — ISO 3166-1 country, optionally with region: "IT" or "IT:CB". Needed for shipping.
  • max_age_seconds — integer
  • destination_details — object — Postal destination for quote=true, e.g. {country:"IT",state:"CB",postcode:"86100",city:"Campobasso"}.

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• verify_offer read-only

  Checks ONE offer (optionally a selected variant) and returns true, false or unknown per constraint with evidence. Pass constraints as an ARRAY, for example [{"field":"available"},{"field":"price","max":300,"currency":"EUR"},{"field":"ships_to","value":"IT:CB"}]. available has no expected key: ask for the fact and read its result. For a merchant-declared variant option use {"field":"option","keys":["pa_color"],"values":["black"]}; use only native merchant values, with variation_id for a specific variant. Nothing is inferred or translated. Results are unknown outside max_age_seconds (default 86400); live=true reads the merchant now. Checkout is the final authority.

  Parameters:

  • p2209_id (required) — string — Offer id from global_search (e.g. prod_duinshop-it_446678).
  • constraints (required) — array — Required array of 1-8 objects. Each object has field and only the keys shown by its schema. Examples: [{"field":"available"}], [{"field":"price","max":50,"currency":"EUR"}].
  • live — boolean — true reads the merchant Bridge now (one request).
  • variation_id — integer — Variant to check (from matching_variants or variants_compact). Without it, variant-dependent constraints may be unknown.
  • max_age_seconds — integer

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• lookup_merchant read-only

  Use this when the user already knows a merchant domain and needs to check whether it publishes a KaliCart Bridge catalog, its latest observed access state, or its federation consent. This tool only reads the Global registry and never probes or modifies the merchant. Do not use it to discover products; use global_search instead.

  Parameters:

  • domain (required) — string — Merchant domain, e.g. shop.example.com

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_product read-only

  Use this after global_search when the selected candidate needs indexed details that are not already on its search card. The p2209_id must come from global_search. Variant options and colors are merchant-declared snapshot evidence matched by variation ID. This remains a snapshot, not live merchant verification; follow the returned handoff before confirming variant, price, or stock. Skip this call when the search card already answers the question.

  Parameters:

  • p2209_id (required) — string — KaliCart product ID (e.g. prod_duinshop-it_432395)

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• list_merchants read-only

  Use this to inspect which WooCommerce merchants currently participate in the searchable KaliCart Global catalog and how much catalog coverage each contributes. It returns stable merchant identifiers, domains, storefront URLs, product counts, and sync time. Do not use it to find products; use global_search instead.

  Parameters:

  • limit — integer — Max merchants to return (default 20, max 50), ordered by product count descending. No pagination

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• list_categories read-only

  Use this to discover the canonical category paths currently represented in KaliCart Global before calling global_search with leaf. An optional parent returns that node and its full subtree. This lists category vocabulary and counts; it does not return products.

  Parameters:

  • parent — string — Optional canonical node to restrict results to that node and its subtree (for example apparel or home.bedroom)

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.