willys-mcp

Vad det här är

Willys har inget publikt API. Den här servern kartlägger deras faktiskaendpoints, 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 avvad dina recept kräver. Inte som en hög varor någon lagt i en gång.

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å jaghöjer antalet från 4 till 6 förpackningar — 65,28 kr. Äggen är oförändrade ochrörs inte.

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

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 perstyck. Men när mängden är känd är det fel fråga. Det som avgör är vad just dittbehov 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äknarigenom varje täckningsstrategi och rangordnar på total kostnad.

Men den väljer inte åt dig när avvägningen är verklig. Överstiger billigastevä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 gerbara 7 st över. Vill du ha det billigare med överskott?

Det är hushållets avvägning, inte serverns. Rader med obesvarad fråga hamnaraldrig 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öpandesumma 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 somredan 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 tillstaplas på.

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

Verktyg

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. Claudefrågar vilken ort du handlar i, slår upp din butik, skapar konfigurationsfilenoch ö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 iprojektmappen, vilket är bekvämt i en checkout men gör att de följer med ommappen 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 BankIDmåste du skapa ett lösenord först, och Claude förklarar hur.

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 ochbehovsregistret är rena funktioner mot SQLite — vilket är varför de har riktigatester 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 ochvarför. Matchar en kategorifacett ingenting görs om­försök utan den och svaretsäger vilka facetter som faktiskt finns. Ett tyst nollresultat är värre än ettfel — det ser ut som att hyllan är tom.

Beslut med verklig avvägning returneras som frågor. Överskott mot pris ärinte 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 regelmodellen 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 enserver annonserar — det är dokumentation, inte kontroll. Varje anrop parsas föredispatch. Utan det går en påhittad quantity rakt in i kundvagnen, och föradd_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 "Willysligger nere" från "en människa måste redigera en fil", och agera olika på varje.

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ängpå 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.

Vad den inte gör

• Beställer inte. Inget kassaverktyg finns.
• Fungerar inte i claude.ai i webbläsaren. En webbsida kan inte startaprogram på din dator. Claude Desktop eller Claude Code.
• Stödjer inte BankID.
• Är inte officiell. Endpoints är kartlagda mot produktion och kan slutafungera 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 smoke          # end-to-end över stdio, kräver session

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

Förbehåll

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