willys-mcp

<div align="center">

<img src="assets/header.jpg" alt="Ingredienser som flödar genom en beräkningsgraf in i en kundvagn" width="100%">

<h1>willys-mcp</h1>

Ge Claude dina recept. Få rätt varor, i rätt mängd, i din kundvagn.

En MCP-server som gör svensk matplanering till något du delegerar i stället för något du gör.

<br>

</div>

<br>

Vad det här är

Willys har inget publikt API. Den här servern kartlägger deras faktiska endpoints, loggar in som du, och exponerar alltihop som MCP-verktyg — sökning, jämförprisrankning, kundvagn, orderhistorik och butiksregister.

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.

<br>

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.

<br>

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.

Strategi	Antal	Får	Över	Kostnad
6-pack	3×	18 st	5	74,70 kr
10-pack	2×	20 st	7	69,80 kr
24-pack	1×	24 st	11	62,00 kr ✅

_{Konstruerat exempel med satta priser, hämtat ur <a href="tests/coverage.test.ts">testsviten</a>. 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.

<br>

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.

<br>

Verktyg

<table> <tr><th align="left">Planering</th><th align="left"></th></tr> <tr><td><code>willys_plan_add_recipe</code></td><td>Lägg ett recepts ingredienser i registret</td></tr> <tr><td><code>willys_plan_status</code></td><td>Föreslagen korg, kostnad, beslutslägen</td></tr> <tr><td><code>willys_plan_apply</code></td><td>Synka vagnen — <code>dryRun</code> som default</td></tr> <tr><td><code>willys_plan_remove_recipe</code></td><td>Ta bort ett recept, räkna om</td></tr> <tr><td><code>willys_plan_clear</code></td><td>Nollställ planen</td></tr> </table>

<table> <tr><th align="left">Sök & pris</th><th align="left"></th></tr> <tr><td><code>willys_find_cheapest</code></td><td>Rankar på jämförpris över <b>hela</b> träffmängden, serverside</td></tr> <tr><td><code>willys_search</code></td><td>Fritextsök i Willys relevansordning</td></tr> <tr><td><code>willys_search_suggestions</code></td><td>Autocomplete</td></tr> <tr><td><code>willys_get_product_detail</code></td><td>Näringsvärde, ingredienser, ursprung</td></tr> <tr><td><code>willys_get_campaigns</code></td><td>Butiksspecifika erbjudanden</td></tr> </table>

<table> <tr><th align="left">Kundvagn & konto</th><th align="left"></th></tr> <tr><td><code>willys_get_cart</code> · <code>willys_add_to_cart</code> · <code>willys_remove_from_cart</code></td><td>Kundvagn</td></tr> <tr><td><code>willys_get_orders</code> · <code>willys_get_order_details</code></td><td>Orderhistorik</td></tr> <tr><td><code>willys_get_frequent_products</code></td><td>Vanligaste varor, ur faktisk historik</td></tr> <tr><td><code>willys_login</code> · <code>willys_check_auth</code> · <code>willys_logout</code></td><td>Session, 24h</td></tr> </table>

<table> <tr><th align="left">Butik & uppsättning</th><th align="left"></th></tr> <tr><td><code>willys_find_stores</code> · <code>willys_nearest_stores</code> · <code>willys_get_store</code></td><td>254 butiker, lokal cache, ingen session</td></tr> <tr><td><code>willys_setup</code> · <code>willys_setup_init</code></td><td>Guidad förstagångsuppsättning</td></tr> </table>

<br>

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

Sen skriver du bara "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

[!IMPORTANT] Ditt Willys-konto måste ha ett lösenord. BankID går inte att automatisera — servern loggar in genom att fylla i ett formulär. Har du bara använt BankID måste du skapa ett lösenord först, och Claude förklarar hur.

<br>

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
├── domain/           ren matte: volym, täckning, produktmodell, namnmatchning
├── upstream/         HTTP-klienter mot Willys, en fil per resurs
├── auth/             Puppeteer-inloggning, sessionslagring
├── net/              generisk URL-hämtare (fetch_url)
├── core/             http, result, logger, env
└── constants/        endpoints, gränsvärden, instructions

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.

<br>

Designprinciper

Fem beslut som formar resten av kodbasen.

Servern gissar aldrig tyst. Filtreras varor bort står det hur många och varför. 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. willys_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 "Willys ligger nere" från "en människa måste redigera en fil", och agera olika på varje.

<br>

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.

<br>

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.
• Är inte officiell. Endpoints är kartlagda mot produktion och kan sluta fungera utan förvarning.

<br>

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 smoke          # end-to-end över stdio, kräver session

Konventioner och fallgropar för framtida ändringar: CLAUDE.md Endpoint-kartläggning: docs/endpoints.md

<br>

Förbehåll

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

<br>

---

<div align="center">

MIT · LICENSE

</div>