This server is a read-only MCP tool for working with public Kupi.cz discount offers: searching deals, comparing offers for a product, and optimizing a shopping list across stores.
search_products: search current or date-specific sale products on Kupi.cz with filters for stores, sale-only items, excluded words, membership-only offers, location, sorting (relevance, price, unit price, discount), and a result limit (1–50). Each match includes a confidence score and quality rating.
get_product_offers: fetch and compare all offers for a specific product by slug or HTTPS product URL, sorted by price and unit price, with optional store, location, validity-date, and membership filters.
compare_shopping_list: optimize 1–20 shopping-list items across up to 8 stores, respecting quantities (amount + unit), preferred/required package sizes, allowed/excluded stores, available memberships, and optimization goals (lowest price, fewest stores, balanced). Reports complete/partial coverage, resolved/unresolved items, and package vs. purchase prices.
Location handling: supports preconfigured localities, shows actual location used, warns on mismatch, and never guesses unconfigured locations.
Offer validity checking: filters offers by validity date, never presents future offers as currently valid.
Branch/radius support: can restrict stores to verified branches within a radius, returning branch details and straight-line distance, with clear caveats about assumed applicability.
Package intelligence: parses quantities like "2 kg" or multipacks such as "6 × 0.5 l", computes needed packages, and supports any/preferred/required package-size modes.
Price sanity checks: flags unusually high unit prices relative to comparable candidates (normal/high/extreme) without hard-blocking.
Debug diagnostics: optional structured reason codes, rejected matches/offers, and HTTP request details for transparency.
Safety/limitations awareness: read-only, no login, respects robots.txt, returns structured errors on blocking, and explicitly marks results as approximate rather than confirming stock availability.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kupi-mcp Porovnej ceny mléka a másla v aktuálních akcích"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Neoficiální MCP server nad veřejnými slevovými stránkami Kupi.cz. Pouze čte: vyhledá akční produkty, porovná nabídky jednoho produktu a sestaví z akcí nákupní seznam.
Není spojený s provozovatelem Kupi.cz ani jím schválený.
Nástroj | K čemu je |
| Najde akční produkty. Každý výsledek nese |
| Nabídky jednoho produktu z jeho detailu — víc obchodů než výsledek hledání. |
| Hlavní nástroj: z celého seznamu sestaví proveditelný nákup přes několik obchodů. |
Volitelný parametr radiusKm u prvního a třetího omezí výsledek na řetězce s ověřenou
pobočkou v okolí. Stojí další HTTP požadavky; bez něj server vzdálenost obchodů nezná.
Related MCP server: coffee-price-mcp
Leták není sklad. Cena z akce neznamená, že produkt na pobočce je.
Vzdálenost je vzdušná čára ze souřadnic pobočky, ne délka jízdy.
Otevírací doba je běžná týdenní; svátky a jednorázová zavření zdroj neuvádí.
Platnost akce na konkrétní pobočce se nedá z veřejných stránek ověřit, proto je
označená jako assumed.
Neúplný košík má totalPrice: null. Cena vyřešené části je v resolvedPrice.
Produkt, který dotazu neodpovídá dost jistě, se nepoužije; položka zůstane nevyřešená.
Kupi.cz drží lokalitu v cookies. Endpoint, který překládá název města na interní ID, je
zakázaný v robots.txt, takže se ID nikdy neodhaduje. Buď ho předáte v
KUPI_LOCALITIES, nebo se použije anonymní výchozí lokalita podle IP — a výsledek
vždy uvádí, pro kterou lokalitu data skutečně jsou.
ID si zjistíte ve vlastním prohlížeči z cookies user_locality a user_slocality po
nastavení města na Kupi.cz. Jsou to provozní data; do repozitáře nepatří.
Proměnná | Výchozí | Význam |
| prázdné |
|
| obecný | User-Agent, kterým se server představuje |
|
| Rozestup mezi požadavky na zdroj |
|
| Souběžné požadavky |
|
| Platnost cache staženého HTML |
|
| Timeout jednoho požadavku |
|
| Opakování po dočasné chybě |
|
| Strop velikosti odpovědi |
Pro HTTP nasazení navíc:
Proměnná | Význam |
| Token, který klient posílá v |
|
|
| Povolené |
| Strop velikosti požadavku (výchozí 1 MiB) |
Bez MCP_HTTP_BEARER_TOKEN a bez výslovného povolení anonymního přístupu endpoint
odpovídá 503. Nezabezpečený server nikdy nevznikne omylem.
npm ci
npm run build
npm startPřes stdio, například v Claude Desktop:
{
"mcpServers": {
"kupi": {
"command": "node",
"args": ["/cesta/ke/kupi-mcp/dist/index.js"],
"env": { "KUPI_LOCALITIES": "Mesto:localityId:sublocalityId" }
}
}
}Repozitář je připravený jako drop-in projekt: api/mcp.ts je MCP endpoint,
api/health.ts odpovídá na kořenové cestě. Nastavte MCP_HTTP_BEARER_TOKEN mezi
proměnnými prostředí projektu a nasaďte. npm run package vyrobí ZIP, který se dá na
Vercel přetáhnout beze změn.
Klient se pak připojí na https://vase-nasazeni.vercel.app/api/mcp s hlavičkou
Authorization: Bearer <token>; klienti, které vlastní hlavička Authorization
nepustí, mohou poslat X-Api-Key.
Vyhledávání s radiusKm jinak stahuje stránky poboček za běhu, což je po studeném startu
pomalé. Předgenerovaný snapshot to odstraní:
npm run branches:refresh -- --location Mesto --radius 50Zapíše data/store-branches.json. Opakované běhy pro různá města se slučují. Soubor je
volitelný — bez něj se pobočky dohledávají živě.
npm run typecheck
npm run lint
npm testnpm run privacy:check hlídá, aby se do repozitáře nedostaly e-maily, absolutní cesty
z domovského adresáře ani konkrétní ID lokalit.
Co jsme o zdroji zjistili a proč je kód místy opatrnější, než by se zdálo nutné, je v docs/kupi-facts.md.
Požadavky jsou sériové s rozestupem, odpovědi se cachují a odpovědi 429/403 se
nepřekračují — server se je nesnaží obejít, vrátí strukturovanou chybu. Skupina
User-agent: AI má v robots.txt Kupi.cz úplný zákaz; pro veřejné nebo objemné nasazení
si vyžádejte souhlas provozovatele.
MIT, viz LICENSE.
Porovná letákové nabídky pro více položek, respektuje obchody, dostupná členství a maximální počet obchodů. Ve výchozím stavu používá jen akce platné dnes. Množství zadávejte přes amount + unit („2 kg“); počet balení se dopočítá podle skutečné velikosti balení (2 kg z balení po 600 g = 4 balení). Produkty s nízkou jistotou shody se nepoužijí a skončí v unresolvedItems. Pokud není pokryt celý košík, je status „partial“ a totalPrice je null — cena vyřešené části je v resolvedPrice. Výsledek je přibližný a neřeší vzdálenost ani sklad.
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | Přidá strukturovanou diagnostiku odmítnutých kandidátů a reason codes. Výchozí je vypnuto. | |
| items | Yes | ||
| validOn | No | Datum, ke kterému musí akce platit (YYYY-MM-DD). Výchozí je dnešek v Praze. | |
| location | No | ||
| maxStores | No | ||
| optimization | No | balanced | |
| allowedStores | No | ||
| excludedStores | No | ||
| availableMemberships | No | ||
| requireCompleteBasket | No | Upřednostní kombinaci obchodů pokrývající celý košík před nižší cenou. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| stores | No | |
| success | Yes | |
| validOn | No | |
| complete | No | |
| coverage | No | |
| location | No | |
| warnings | No | |
| sourceUrls | No | |
| totalItems | No | |
| totalPrice | No | |
| approximate | No | |
| diagnostics | No | |
| explanation | No | |
| retrievedAt | No | |
| optimization | No | |
| resolvedItems | No | |
| resolvedPrice | No | |
| unresolvedItems | No | |
| requestedLocation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, openWorld=true, idempotent=true, and destructive=false. The description adds substantial behavioral detail: default date scope, package-count rounding, low-confidence products going to unresolvedItems, partial status with null totalPrice and resolvedPrice, and the approximation/distance/stock limitation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the tool's purpose and then delivers compact behavioral rules: date default, quantity semantics, unresolved items, partial results, and limitations. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with an output schema and strong annotations, the description covers the most important behaviors and caveats clearly. It still leaves some optional parameters like optimization modes, allowedStores/excludedStores, and requireCompleteBasket to schema-only documentation, and it does not explicitly route between this tool and its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 30%, so the description must compensate. It meaningfully explains the critical amount+unit semantics with a concrete example and package-count recalculation, and it steers away from deprecated quantity/preferredPackage. It does not cover optimization, requireCompleteBasket, or store-filter parameters, but those are at least present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: comparing leaflet offers for multiple items while respecting stores, memberships, and maxStores. This clearly differentiates it from the sibling tools search_products and get_product_offers, which are individual product/offer lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is for multi-item basket optimization, defaults to today's valid actions, and explains quantity input via amount+unit. It does not explicitly name alternatives or say when not to use it, but the intended use case is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Načte veřejný detail /sleva/{slug}, deduplikuje doporučené nabídky a nabídky dle ceny a označí klubové, aplikační a množstevní podmínky.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| stores | No | ||
| validOn | No | Datum, ke kterému musí akce platit (YYYY-MM-DD). Výchozí je dnešek v Praze. | |
| location | No | ||
| productUrl | No | ||
| excludeMembershipOnly | No |
| Name | Required | Description |
|---|---|---|
| error | No | |
| success | Yes | |
| validOn | No | |
| location | No | |
| products | No | |
| warnings | No | |
| sourceUrl | No | |
| retrievedAt | No | |
| searchQuery | No | |
| rejectedOffers | No | |
| rejectedMatches | No | |
| requestedLocation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description focuses on additional behavior: it loads a public endpoint, deduplicates recommended and price-based offers, and labels club/application/quantity conditions. It adds meaningful processing context beyond the structured annotations, though it does not discuss edge cases or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one dense sentence that front-loads the action and resource, then adds two valuable behavioral notes about deduplication and condition marking. There is no filler, repetition, or unnecessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and annotations cover return structure and safety, but with six parameters, zero required fields, and very low schema coverage, the description leaves significant ambiguity about invocation. In particular, it presents slug as part of the endpoint while the schema marks no parameters as required, which could confuse an agent about what must be supplied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, with only validOn having a real description in the schema. The description hints at slug via the endpoint template and at condition labeling, but it does not explain stores, location, productUrl, excludeMembershipOnly, or how they affect results. It fails to compensate for the otherwise low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Načte' / loads), the resource ('veřejný detail /sleva/{slug}'), and the distinguishing post-processing behaviors: deduplicating offers and marking club, application, and quantity conditions. This makes it clearly distinct from siblings like search_products or compare_shopping_list, which are about discovery and comparison across products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific product slug is available and the agent needs its offers, but it does not explicitly state when to prefer this tool over search_products or compare_shopping_list. There is no mention of exclusions, prerequisites, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vyhledá nabídky ve veřejném server-renderovaném HTML Kupi.cz. Ve výchozím stavu vrací jen akce platné dnes; budoucí akce nejsou vydávány za aktuálně platné. Údaje o balení v dotazu („hermelín 100 g“) se automaticky oddělí, aby nekazily hledání. Každý produkt nese match.confidence (0–1) a match.quality (high/medium/low) vyjadřující, jak dobře odpovídá dotazu. Výsledek uvádí skutečnou lokalitu dat; nejde o potvrzení skladové dostupnosti.
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | Přidá strukturovanou diagnostiku odmítnutých kandidátů a reason codes. Výchozí je vypnuto. | |
| limit | No | ||
| query | Yes | ||
| sortBy | No | relevance | |
| stores | No | ||
| exclude | No | Slova, která produkt diskvalifikují, například ["uzená"]. | |
| validOn | No | Datum, ke kterému musí akce platit (YYYY-MM-DD). Výchozí je dnešek v Praze. | |
| location | No | ||
| onlyOnSale | No | ||
| excludeMembershipOnly | No |
| Name | Required | Description |
|---|---|---|
| error | No | |
| success | Yes | |
| validOn | No | |
| location | No | |
| products | No | |
| warnings | No | |
| sourceUrl | No | |
| retrievedAt | No | |
| searchQuery | No | |
| rejectedOffers | No | |
| rejectedMatches | No | |
| requestedLocation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: it discloses the source type (public server-rendered HTML), default date semantics, automatic packaging-term separation, match.confidence/match.quality output fields, and the important caveat that results reflect data location, not stock availability. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five dense sentences are ordered well: search source, default date behavior, query handling, match metadata, and the key limitation. Each sentence earns its place and there is no repeated schema information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 10 parameters and only 30% schema coverage, the description explains the tool's core behavior, defaults, query nuance, output metadata, and a crucial non-goal (stock confirmation); an output schema exists for return semantics. It falls short only on full parameter guidance and explicit sibling routing, but it is still largely complete for correct high-level use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 30%, so the description carries a heavy burden for parameter meaning. It adds some value by explaining that packaging details in the query are separated automatically, but it does not address limit, sortBy, stores, location, onlyOnSale, excludeMembershipOnly, or other parameters. Most parameter semantics remain undocumented in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete action ('Vyhledá nabídky') and a precise target ('veřejném server-renderovaném HTML Kupi.cz'), with the title further scoping it to 'akční produkty na Kupi.cz'. This clearly differentiates the tool from offer-lookup and shopping-list comparison siblings even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful behavioral caveats: it defaults to today's deals, does not present future deals as current, and is not a stock-availability confirmation. However, it never explicitly tells the agent when to choose search_products over get_product_offers or compare_shopping_list; usage is only implied through purpose and caveats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0compare_shopping_listget_product_offerssearch_productsScored across 3 tools
Each tool has a clearly distinct purpose: search products, fetch detailed offers for a specific product, and compare a whole shopping list. There is no meaningful overlap between any pair, and the descriptions emphasize their different inputs and outputs.
All tool names follow a consistent verb_noun pattern in snake_case: search_products, get_product_offers, compare_shopping_list. The verbs clearly indicate the action and the object indicates the resource.
Three tools is a compact but well-scoped set for a narrow domain. Each tool earns its place: search handles discovery, get_product_offers handles per-product detail, and compare_shopping_list handles batch comparison.
The core workflow of searching products, viewing offer details, and comparing a shopping list is covered with no dead ends. Minor gaps exist, such as no explicit store listing or category browsing tool, but these do not undermine the server's stated purpose.
Danish grocery catalog as MCP tools: live offers across all major chains, stores, EAN lookup, stock.
Google Shopping products, prices, sellers, and deals as structured data via a hosted MCP server.
Live prices, deals & optimal multi-stop shopping routes for German grocery & drug stores.
Read-only shopping decisions, product search, offers, and price history for Greece.
