willys-mcp

Ge Claude dina recept. Få rätt varor, i rätt mängd, i din kundvagn — och veta var det är billigast.

En MCP-server för Willys, Hemköp, Coop, City Gross och Mathem som gör svensk matplanering till något du delegerar i stället för något du gör.

Vad det här är

Ingen av de svenska matkedjorna har ett publikt API. Den här servern kartlägger deras faktiska endpoints och exponerar dem som MCP-verktyg — sökning, jämförprisrankning, prisjämförelse mellan kedjor, butiksregister, och för Willys även inloggning, kundvagn och orderhistorik.

Men det intressanta ligger ovanpå: kundvagnen behandlas som en projektion av vad dina recept kräver. Inte som en hög varor någon lagt i en gång. Och samma plan kan prissättas i alla fem kedjor.

ICA stöds inte: deras API ligger bakom ett botskydd som tillåter ungefär fem anrop per fem minuter, för lite för att planera en korg. Detaljer per kedja: docs/kedjor.md.

Related MCP server: Willys MCP Server

Se den göra något

Du: Här är tre recept för veckan — pannkakor, omelett och äggröra.

Claude: (lägger till recepten, räknar om korgen) Du behöver 13 ägg totalt. Billigast blir ett 15-pack för 36,81 kr — 2 ägg över. Jag har också hittat vispgrädde: 4× 2,5 dl för 43,52 kr täcker dina 8 dl.

Summa 80,33 kr. Vill du att jag lägger det i vagnen?

Du: Ja. Och lägg till en gratäng som behöver 5 dl grädde.

Claude: (behovet ändras, korgen räknas om) Grädden går från 8 till 13 dl. Samma produkt är fortfarande billigast, så jag höjer antalet från 4 till 6 förpackningar — 65,28 kr. Äggen är oförändrade och rörs inte.

Servern har inget kassaverktyg. Den kan fylla kundvagnen men aldrig lägga en order. Det sista klicket är alltid ditt.

Du: Vad kostar pastan i de andra kedjorna?

Claude: (samma plan prissatt i fem kedjor, inget ändras) Willys 61,30 kr · Coop Bäckebol 64,40 kr · Hemköp 69,35 kr · Mathem 70,10 kr · City Gross 89,85 kr. Willys är billigast med 3,10 kr till Coop.

Riktiga priser från 2026-10-14: 500 g köttfärs, 400 g krossade tomater och 500 g spaghetti.

Det svåra problemet: du kan inte köpa 13 ägg

Bara förpackningar av dem. Det låter trivialt och är det inte.

En vanlig prissökning rankar på jämförpris — kr per kilo, kr per liter, kr per styck. Men när mängden är känd är det fel fråga. Det som avgör är vad just ditt behov kostar när du bara kan köpa hela förpackningar.

Konstruerat exempel med satta priser, hämtat ur testsviten. I Willys faktiska sortiment löses 13 ägg av ett 15-pack med bara 2 över — men principen är densamma.

24-packet vinner på riktiga pengar trots sämst antal spillda ägg. Servern räknar igenom varje täckningsstrategi och rangordnar på total kostnad.

Men den väljer inte åt dig när avvägningen är verklig. Överstiger billigaste vägen behovet med mer än 50 %, och finns ett märkbart tätare alternativ, returneras en fråga i stället för ett beslut:

Ägg 24-pack är 7,80 kr billigare men ger 11 st över behovet. Ägg 10-pack ger bara 7 st över. Vill du ha det billigare med överskott?

Det är hushållets avvägning, inte serverns. Rader med obesvarad fråga hamnar aldrig i vagnen av misstag.

Hur behoven hålls ihop

flowchart LR
    R1["Recept: Pannkakor<br/>6 ägg"] --> L
    R2["Recept: Omelett<br/>4 ägg"] --> L
    R3["Recept: Äggröra<br/>3 ägg"] --> L
    L["Behovsregister<br/><b>13 ägg</b>"] --> C
    C["Täckningsmatte<br/>1× 15-pack"] --> D
    D{"Diff mot<br/>kundvagnen"} --> A["Byt 6-pack<br/>→ 15-pack"]

Varje recepts bidrag lagras separat. Det ger tre egenskaper som en löpande summa inte kan ge:

• Härkomst gratis. 13 ägg är inte ett tal utan Pannkakor:6 + Omelett:4 + Äggröra:3. Claude kan förklara en ändring, inte bara meddela den.

• Borttagning är en radering, inte ett försök att subtrahera mängder som redan rundats upp till förpackningar.

• Omräkning, inte lappning. Hela korgen härleds ur registret varje gång. Det är därför 6-packet byts ut när behovet växer, i stället för att ett till staplas på.

plan_apply skickar bara differensen. Rätt vara i rätt antal ger inget anrop alls, så det är gratis att köra om efter varje nytt recept.

Verktyg

Nästan alla verktyg tar chain. Claude frågar vilken kedja du handlar i om du inte sagt det — servern väljer aldrig åt dig.

Installation

npm install
npm run build

Koppla in i Claude Code:

claude mcp add willys --env WILLYS_HOME=$HOME/.willys-mcp -- node /absolut/sökväg/willys-mcp/dist/index.js

…eller i Claude Desktop:

{
  "mcpServers": {
    "willys": {
      "command": "node",
      "args": ["/absolut/sökväg/till/willys-mcp/dist/index.js"],
      "env": { "WILLYS_HOME": "/Users/dittnamn/.willys-mcp" }
    }
  }
}

Sök, priser och jämförelser fungerar direkt, utan konto. För kundvagn och orderhistorik hos Willys skriver du "hjälp mig komma igång med Willys" i en chatt. Claude frågar vilken ort du handlar i, slår upp din butik, skapar konfigurationsfilen och öppnar den åt dig. Det enda du gör själv är att fylla i två rader.

WILLYS_HOME styr var .env och sessionsdatabasen hamnar. Utan den ligger de i projektmappen, vilket är bekvämt i en checkout men gör att de följer med om mappen någon gång byts ut.

Fullständig guide: INSTALL.md

Arkitektur

src/
├── index.ts          MCP-entrypoint: transport + wiring (tunn)
├── setup.ts          förstagångsdiagnostik
├── tools/            ett verktyg = ett objekt, grupperat per domän
│   ├── registry.ts   samlar grupperna, äger dispatch (validering, auth, felgräns)
│   ├── kit.ts        Tool-kontrakt, Ctx, defineTool, svarshjälpare
│   ├── session.ts · search-tools.ts · cart-tools.ts · orders-tools.ts
│   ├── stores-tools.ts · setup-tools.ts · planner-tools.ts
│   ├── schema-parts.ts  delade Zod-fragment
│   └── json-schema.ts   Zod → JSON Schema för manifestet
├── planner/
│   ├── ledger.ts     behovsregister med härkomst per recept
│   └── reconcile.ts  bygger korgen, diffar mot vagnen
├── chains/           ChainAdapter-kontraktet, registret, delad rangordning och butiksregister
├── domain/           ren matte: volym, täckning, produktmodell, namnmatchning, jämförpris
├── upstream/         HTTP-klienter, en mapp per plattform, en fil per resurs
│   ├── axfood/       Willys + Hemköp (samma API, två värdar)
│   ├── coop/         API-nycklarna läses ur coop.se vid första anropet
│   ├── citygross/
│   └── mathem/
├── auth/             Puppeteer-inloggning, sessionslagring
├── net/              generisk URL-hämtare (fetch_url)
├── core/             http, result, logger, env
└── constants/        endpoints, gränsvärden, instructions

En adapter per plattform, inte per butik: Willys och Hemköp är samma Axfood-API, och skillnaden mellan dem är en bas-URL. Rangordning och filter ligger i chains/ och gäller alla kedjor lika.

domain/ och planner/ledger.ts rör aldrig nätverket. Täckningsmatten och behovsregistret är rena funktioner mot SQLite — vilket är varför de har riktiga tester som kör på under en sekund utan att logga in någonstans.

Designprinciper

Fem beslut som formar resten av kodbasen.

Servern gissar aldrig tyst. Filtreras varor bort står det hur många och varför — djurmat, fel namn, ej köpbara. Matchar en kategorifacett ingenting görs om­försök utan den och svaret säger vilka facetter som faktiskt finns. Ett tyst nollresultat är värre än ett fel — det ser ut som att hyllan är tom.

Beslut med verklig avvägning returneras som frågor. Överskott mot pris är inte serverns val. Samma sak när två recept vill ha 2 st tomat och 400 g tomat: det blir en konflikt att lösa, inte en påhittad omräkning.

Farliga tillstånd görs omöjliga i protokollet. Det finns inget kassaverktyg, så servern kan inte beställa. plan_apply har dryRun: true som default. setup_init tar inte emot lösenord som argument — inte som en regel modellen ska följa, utan för att schemat vägrar. Det är starkare än att skriva "gör inte så".

Zod validerar på riktigt. MCP-SDK:n validerar inte argument mot schemat en server annonserar — det är dokumentation, inte kontroll. Varje anrop parsas före dispatch. Utan det går en påhittad quantity rakt in i kundvagnen, och för add_to_cart betyder det riktiga varor.

Fel bär en klass hela vägen ut. AUTH_EXPIRED, SHAPE, NOT_FOUND, SETUP_REQUIRED, UPSTREAM. Modellen kan skilja "sessionen dog" från "kedjan ligger nere" från "en människa måste redigera en fil", och agera olika på varje.

Servern rangordnar själv. Bara Axfood sorterar rätt på jämförpris. City Gross ignorerar kampanjpris, Mathem kan inte sortera alls, och Coop har jämförpriser som är fel med en faktor tusen. Servern hämtar hela träffmängden, kontrollerar jämförpriset mot pris ÷ förpackning och sorterar.

Fällor som redan kostat tid

Dokumenterade i koden, med datum, så ingen återinför dem.

• sort=price:asc rankar en portionsrätt på 16 kr över ett kilo köttfärs på 69 kr. Sortera på compareprice:asc.

• Facettfilter ligger i q, inte i en egen parameter: q=köttfärs:category:Kött. Utan kategorin är billigaste träffen på "köttfärs" en Findus köttfärssås.

• Fritextsök utan mustContain ger självsäkert nonsens. "torkad dragon" matchade ett torkat grisöra sålt som hundtugg — det var billigast med ordet "torkad".

• Näringsvärden ligger i nutritionsFactList, inte nutritionFacts (tom sträng på varje produkt som inspekterats).

• Willys svarar 400, inte 404, för en produktkod som inte finns.

• Kundvagnen har ingen delete-endpoint. Borttagning är en add med quantity: 0.

• Varje endpoint som innehåller ett Next.js build-id är en tidsinställd bomb. Tre är redan döda och ligger kvar i DEAD_ENDPOINTS som varning.

• "köttfärs" hos Coop rankade kattmat först. Den var billigast av allt med kött.

• City Gross totalCount räknar recept som träffar: "köttfärs" ger 101 träffar och 9 produkter.

• Coop-sök mot en butik utan e-handel ger noll träffar, inte ett fel.

• City Gross produktkoder är Axfoods: samma kod är samma vara hos Willys, Hemköp och City Gross.

Vad den inte gör

• Beställer inte. Inget kassaverktyg finns.

• Fungerar inte i claude.ai i webbläsaren. En webbsida kan inte starta program på din dator. Claude Desktop eller Claude Code.

• Stödjer inte BankID.

• Stödjer inte ICA.

• Har ingen kundvagn för Hemköp, Coop, City Gross eller Mathem än.

• Är inte officiell. Endpoints är kartlagda mot produktion och kan sluta fungera utan förvarning.

Utveckling

npm run typecheck      # enda verkliga porten före commit
npm run test:coverage  # täckningsmatte, inget nätverk
npm run test:planner   # behovsregister, inget nätverk
npm run test:volume    # 44 verkliga förpackningsformat
npm run test:chains    # mappning per kedja, rangordning, djurmat, jämförpriskontroll
npm run test:coop      # Coops nyckelhämtning och rotation, med stubbad fetch
npm run test:releases  # release notes och tombstones för gamla verktygsnamn
npm run smoke          # end-to-end över stdio, kräver session

Konventioner och fallgropar för framtida ändringar: CLAUDE.md Endpoint-kartläggning: docs/kedjor.md · Willys i detalj: docs/endpoints.md Ändringar per version: docs/CHANGELOG.md — AI-klienter läser samma fil via release_notes.

Förbehåll

Ett privat verktyg som automatiserar ett konto du själv äger och läser publika priser. Respektera kedjornas användarvillkor, kör det inte mot konton du inte förfogar över, och undvik anropsvolymer som liknar skrapning.

MIT · LICENSE