kupi-mcp

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ástroje

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

Čemu výstup věří a čemu ne

• 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á.

Lokalita

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ří.

Konfigurace

Pro HTTP nasazení navíc:

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.

Spuštění

npm ci
npm run build
npm start

Př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" }
    }
  }
}

Nasazení na Vercel

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.

Snapshot poboček

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 50

Zapíš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ě.

Vývoj

npm run typecheck
npm run lint
npm test

npm 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.

Ohleduplnost ke zdroji

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.

Licence

MIT, viz LICENSE.