Skip to main content
Glama

Frisco MCP

Ein TypeScript Model Context Protocol (MCP) Server, der es KI-Assistenten (Claude, Gemini usw.) ermöglicht, mit frisco.pl — Polens Online-Supermarkt — zu interagieren.

Sicherheit zuerst — Der Server speichert niemals Ihre E-Mail-Adresse oder Ihr Passwort. Sie melden sich manuell in einem sichtbaren Browserfenster an; nur Sitzungs-Cookies werden lokal gespeichert.

Beispiel: KI fügt Produkte von einer Einkaufsliste zum Frisco-Warenkorb hinzu


Funktionen

Sitzung

Tool

Beschreibung

login

Öffnet ein sichtbares Chromium-Fenster auf der Anmeldeseite. Sie melden sich manuell an; der Server prüft auf Erfolg und speichert Sitzungs-Cookies.

finish_session

Öffnet den Browser auf der Checkout-Seite, damit Sie ein Lieferzeitfenster wählen und bezahlen können. Keine automatische Zahlung.

clear_session

Schließt den Browser und löscht die gespeicherte Sitzungsdatei.

Warenkorb

Tool

Beschreibung

add_items_to_cart

Fügt Produkte zum Warenkorb hinzu. Unterstützt zwei Abläufe: (1) via productUrl — navigiert direkt zur Produktseite und klickt auf "Do koszyka"; (2) von der letzten search_products Ergebnisseite.

view_cart

Gibt den aktuellen Warenkorbinhalt und den Gesamtpreis zurück.

remove_item_from_cart

Entfernt ein bestimmtes Produkt anhand des Namens (teilweise Übereinstimmung) aus dem Warenkorb.

update_item_quantity

Ändert die Menge eines bereits im Warenkorb befindlichen Produkts (teilweise Namensübereinstimmung).

check_cart_issues

Erkennt ausverkaufte oder nicht verfügbare Produkte im Warenkorb und listet verfügbare Ersatzprodukte für jedes auf.

view_promotions

Zeigt aktive Werbeaktionen, Rabatte und Gesamteinsparungen im aktuellen Warenkorb an.

Produkte

Tool

Beschreibung

search_products

Durchsucht frisco.pl, gibt die Top N Ergebnisse mit Preisen/Verfügbarkeit zurück und speichert die Such-URL/den Kontext für das Hinzufügen zum Warenkorb.

get_product_info

Gibt detaillierte Produktinformationen zurück: Nährwerte (Makros pro 100g), Gewicht/Grammatur, Zutaten, Preis (einschließlich Originalpreis und Stückpreis bei Werbeaktionen).

get_product_reviews

Gibt Kundenbewertungen und Ratings (von Trustmate) für ein Produkt zurück.

Protokolle

Tool

Beschreibung

get_logs

Gibt JSONL-Protokollereignisse für die aktuelle oder eine bestimmte Sitzung zurück.

tail_logs

Gibt die N neuesten Protokollereignisse zurück.


Related MCP server: Rohlik MCP Server

Architektur

flowchart LR
    A[MCP Client / AI Assistant] -->|stdio| B[src/index.ts<br/>McpServer]

    B --> C[Session Tools<br/>src/tools/session.ts]
    B --> D[Cart Tools<br/>src/tools/cart.ts]
    B --> E[Product Tools<br/>src/tools/products.ts]

    C --> G[src/browser.ts<br/>Playwright singleton]
    D --> G
    E --> G

    C --> H[src/auth.ts<br/>session cookies]
    D --> H
    E --> H

    D --> I[src/tools/helpers.ts<br/>navigation, HTML parsing & formatters]
    E --> I

    H --> J[(~/.frisco-mcp/session.json)]
    B --> L[src/logger.ts] --> M[(~/.frisco-mcp/logs/)]
    G --> N[(in-memory lastSearchContext)]
    G --> K[frisco.pl 🌐]
    I --> K

Weitere Diagramme (Anmeldeablauf, Warenkorbablauf): docs/DIAGRAMS.md


Anforderungen

  • Node.js 20 oder neuer

  • Chromium für Playwright (installiert über den unten stehenden Setup-Befehl)


Einrichtung

npm install
npx playwright install chromium
npm run build

MCP-Client-Konfiguration

Der Server kommuniziert über stdio — verweisen Sie Ihren MCP-Client auf node dist/index.js.

Claude Desktop

Hinzufügen zu claude_desktop_config.json:

{
  "mcpServers": {
    "frisco": {
      "command": "node",
      "args": ["/absolute/path/to/frisco-mcp/dist/index.js"]
    }
  }
}

Gemini (Google AI Studio)

Die .gemini/settings.json in diesem Repository enthält bereits die Konfiguration:

{
  "mcpServers": {
    "frisco-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/frisco-mcp/dist/index.js"]
    }
  }
}

Cursor

Hinzufügen zu Ihren Cursor-MCP-Einstellungen (~/.cursor/mcp.json oder Workspace .cursor/mcp.json):

{
  "mcpServers": {
    "frisco": {
      "command": "node",
      "args": ["/absolute/path/to/frisco-mcp/dist/index.js"]
    }
  }
}

Hinweis: Ersetzen Sie den Pfad durch den absoluten Pfad zu dist/index.js auf Ihrem Computer.


Verwendung

1. Anmelden

"Melde mich bei Frisco an"

Das login-Tool öffnet ein Chromium-Fenster auf frisco.pl/login. Melden Sie sich manuell an — der Server wartet bis zu 5 Minuten und speichert Ihre Sitzungs-Cookies, sobald er eine erfolgreiche Anmeldung erkennt.

2. Einkaufen

"Finde mir Naturjoghurt"

Das search_products-Tool gibt eine Liste passender Produkte mit Preisen zurück. Nicht verfügbare Produkte sind mit ⚠️ NIEDOSTĘPNY gekennzeichnet. Es speichert auch die aktuelle Such-URL und den Ergebniskontext für nachfolgende Warenkorb-Operationen.

"Erzähl mir mehr über den PIĄTNICA Skyr"

Das get_product_info-Tool navigiert zur Produktseite und extrahiert detaillierte Informationen: Nährwerte (kcal, Protein, Fett, Kohlenhydrate, Zucker, Salz pro 100g), Gewicht/Grammatur, Zutaten, Preis (einschließlich Originalpreis und Stückpreis bei Werbeaktionen) sowie die Produkt-URL.

"In den Warenkorb legen"

Das add_items_to_cart-Tool unterstützt zwei Abläufe: (1) Wenn eine productUrl angegeben ist (z. B. von get_product_info), navigiert es direkt zu dieser Produktseite und klickt auf "Do koszyka" — dies ist der bevorzugte Ablauf; (2) andernfalls verwendet es die letzte search_products-Ergebnisseite, um das Produkt zu finden und hinzuzufügen.

"Entferne die Butter aus meinem Warenkorb"

Das remove_item_from_cart-Tool findet ein Produkt im Warenkorb anhand des Namens und entfernt es.

"Ändere die Milchmenge auf 3"

Das update_item_quantity-Tool findet das Produkt im Warenkorb und aktualisiert dessen Menge.

"Gibt es Probleme mit meinem Warenkorb?"

Das check_cart_issues-Tool durchsucht den Warenkorb nach ausverkauften Produkten und zeigt für jedes verfügbare Ersatzprodukte an.

"Welche Bewertungen hat Skyr Piątnica?"

Das get_product_reviews-Tool ruft Kundenbewertungen und Rezensionen von Trustmate ab.

"Zeige mir aktive Werbeaktionen in meinem Warenkorb"

Das view_promotions-Tool listet alle aktiven Werbeaktionen, Rabatt-Badges und Gesamteinsparungen auf.

3. Checkout

"Beende meine Frisco-Sitzung"

Das finish_session-Tool öffnet Ihren Warenkorb unter frisco.pl/stn,cart, damit Sie ein Lieferzeitfenster wählen und bezahlen können — der Server führt niemals automatisch eine Zahlung durch.


Projektstruktur

frisco-mcp/
├── src/
│   ├── index.ts          # MCP server setup, tool registration
│   ├── auth.ts           # Session cookie save/restore, login check
│   ├── browser.ts        # Playwright browser singleton, product cache, last search context
│   ├── logger.ts         # JSONL session logging
│   ├── types.ts          # Shared TypeScript types
│   └── tools/
│       ├── session.ts    # login, finish_session, clear_session
│       ├── cart.ts       # add_items_to_cart, view_cart, remove_item_from_cart,
│       │                 #   update_item_quantity, check_cart_issues, view_promotions
│       ├── products.ts   # search_products, get_product_info, get_product_reviews
│       └── helpers.ts    # Navigation, popup dismissal, DOM parsing, formatters
│   └── __tests__/        # Unit tests (Vitest)
├── test_data/            # Sample HTML fixtures for tests
│   └── products/         #   Product page HTMLs (skyr, chicken, bananas, eggs, bag, promotion)
├── docs/
│   └── DIAGRAMS.md       # Mermaid architecture & flow diagrams
├── .github/
│   └── workflows/
│       └── test.yml      # CI — runs tests on push & PR
├── dist/                 # Compiled JS (generated by `npm run build`)
├── vitest.config.ts
├── package.json
├── tsconfig.json
└── .gitignore

Datenspeicherung

Alle Benutzerdaten werden lokal unter ~/.frisco-mcp/ gespeichert:

Datei

Zweck

session.json

Gespeicherte Browser-Cookies (keine Anmeldedaten)

current-session.json

Zeiger auf die aktive Protokollsitzung

logs/<id>.jsonl

Sitzungsbezogene Ereignisprotokolle


Entwicklung

# Run in dev mode (tsx, no separate build step)
npm run dev

# Build
npm run build

# Run built server
npm start

# Run tests
npm test

# Watch mode for tests
npm run test:watch

CI

Tests werden automatisch bei jedem Push und Pull Request auf master über GitHub Actions (.github/workflows/test.yml) ausgeführt. Die Matrix testet gegen Node.js 20 und 22.


Tech-Stack

Bibliothek

Rolle

@modelcontextprotocol/sdk

MCP-Server-Framework

playwright

Browser-Automatisierung (Chromium)

cheerio

HTML-Parsing für Produktinfos

zod

Eingabe-Schema-Validierung

typescript

Sprache & Build

vitest

Unit-Test-Framework


Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Available Tools

10 tools
add_items_to_cartA

Searches for and adds a list of products to the cart. By default appends to current cart, optionally clearing it first.

Inputs: items (required), clearCartFirst.

clear_sessionB

Clears the saved session and closes the browser.

Inputs: no named parameters.

finish_sessionA

Opens the browser at the checkout page so you can select a delivery time and pay.

Inputs: no named parameters.

get_logsB

Returns persisted JSONL log events for the current or selected session.

Inputs: sessionId, limit.

get_product_infoA

Gets detailed info for a product: nutritional values (macros per 100g), weight/grammage, ingredients, and price.

Inputs: query (required).

loginA

Opens a visible Chromium browser to log in to Frisco manually. Run this first to establish a session.

Inputs: no named parameters.

remove_item_from_cartA

Removes a specific product from the Frisco cart by name (partial match supported).

Inputs: productName (required).

search_productsA

Searches frisco.pl for products and returns top matches with prices.

Inputs: query (required), topN.

tail_logsB

Returns the most recent events from persisted session logs.

Inputs: sessionId, lines.

view_cartA

Returns the current contents and total of the Frisco cart.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools are clearly distinct: search_products vs get_product_info, add_items_to_cart vs view_cart vs remove_item_from_cart. The only real overlap is get_logs vs tail_logs, both returning persisted log events, though the descriptions (all events vs most recent) provide some separation.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun snake_case pattern: get_logs, tail_logs, finish_session, clear_session, add_items_to_cart, search_products, get_product_info, remove_item_from_cart, view_cart. Even 'login' fits the simple verb style without breaking the pattern.

    Tool Count5/5

    10 tools is well-scoped for an online grocery automation server. Each tool maps to a clear workflow stage: session management, product discovery, cart manipulation, and checkout handoff. No redundant or superfluous tools.

    Completeness4/5

    The core shopping lifecycle is covered: login, search products, inspect product details, add/remove/view cart, and finish session for checkout. Minor gaps exist, such as no explicit quantity adjustment or standalone clear-cart tool, but add_items_to_cart's optional clearing and the manual checkout flow mitigate most dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, build and manage shopping carts, and access account, order, delivery, and discount information through the Rohlik Group's online grocery delivery platforms. Supports multiple country-specific storefronts by selecting a regional base URL.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to shop groceries across Rohlik Group platforms by searching products, managing carts, analyzing purchase history for personalized suggestions, and accessing account, order, delivery, and discount information.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, and access account, order, delivery, and discount information across multiple European online grocery platforms.
      MIT