Skip to main content
Glama

Frisco MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) en TypeScript que permite a los asistentes de IA (Claude, Gemini, etc.) interactuar con frisco.pl, el supermercado online de Polonia.

La seguridad es lo primero — El servidor nunca almacena tu correo electrónico ni tu contraseña. Inicias sesión manualmente en una ventana de navegador visible; solo las cookies de sesión se guardan localmente.

Ejemplo: IA añadiendo productos de una lista de la compra al carrito de Frisco


Características

Sesión

Herramienta

Descripción

login

Abre una ventana visible de Chromium en la página de inicio de sesión. Inicias sesión manualmente; el servidor comprueba el éxito y guarda las cookies de sesión.

finish_session

Abre el navegador en la página de pago para que puedas seleccionar una franja horaria de entrega y pagar. No hay pago automático.

clear_session

Cierra el navegador y elimina el archivo de sesión guardado.

Carrito

Herramienta

Descripción

add_items_to_cart

Añade productos al carrito. Admite dos flujos: (1) mediante productUrl — navega directamente a la página del producto y hace clic en "Do koszyka"; (2) desde la última página de resultados de search_products.

view_cart

Devuelve el contenido actual del carrito y el precio total.

remove_item_from_cart

Elimina un producto específico del carrito por nombre (coincidencia parcial).

update_item_quantity

Cambia la cantidad de un producto que ya está en el carrito (coincidencia parcial de nombre).

check_cart_issues

Detecta productos agotados o no disponibles en el carrito y enumera sustitutos disponibles para cada uno.

view_promotions

Muestra promociones activas, descuentos y ahorros totales en el carrito actual.

Productos

Herramienta

Descripción

search_products

Busca en frisco.pl, devuelve los N mejores resultados con precios/disponibilidad y guarda la URL de búsqueda/contexto para añadir al carrito.

get_product_info

Devuelve información detallada del producto: valores nutricionales (macros por 100g), peso/gramaje, ingredientes, precio (incluyendo precio original y precio unitario si está en promoción).

get_product_reviews

Devuelve las opiniones y valoraciones de los clientes (de Trustmate) para un producto.

Registros

Herramienta

Descripción

get_logs

Devuelve eventos de registro en formato JSONL para la sesión actual o una específica.

tail_logs

Devuelve los N eventos de registro más recientes.


Related MCP server: Rohlik MCP Server

Arquitectura

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

Más diagramas (flujo de inicio de sesión, flujo del carrito): docs/DIAGRAMS.md


Requisitos

  • Node.js 20 o posterior

  • Chromium para Playwright (instalado mediante el comando de configuración a continuación)


Configuración

npm install
npx playwright install chromium
npm run build

Configuración del cliente MCP

El servidor se comunica a través de stdio — apunta tu cliente MCP a node dist/index.js.

Claude Desktop

Añadir a claude_desktop_config.json:

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

Gemini (Google AI Studio)

El archivo .gemini/settings.json en este repositorio ya contiene la configuración:

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

Cursor

Añadir a tu configuración de MCP de Cursor (~/.cursor/mcp.json o .cursor/mcp.json del espacio de trabajo):

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

Nota: Reemplaza la ruta con la ruta absoluta a dist/index.js en tu máquina.


Uso

1. Iniciar sesión

"Inicia mi sesión en Frisco"

La herramienta login abre una ventana de Chromium en frisco.pl/login. Inicia sesión manualmente: el servidor espera hasta 5 minutos y guarda tus cookies de sesión una vez que detecta un inicio de sesión exitoso.

2. Comprar

"Búscame yogur natural"

La herramienta search_products devuelve una lista de productos coincidentes con sus precios. Los productos no disponibles están marcados con ⚠️ NIEDOSTĘPNY. También guarda la URL de búsqueda actual y el contexto de resultados para operaciones posteriores en el carrito.

"Cuéntame más sobre el PIĄTNICA Skyr"

La herramienta get_product_info navega a la página del producto y extrae información detallada: valores nutricionales (kcal, proteínas, grasas, carbohidratos, azúcares, sal por 100g), peso/gramaje, ingredientes, precio (incluyendo precio original y precio unitario para productos en promoción) y la URL del producto.

"Añádelo al carrito"

La herramienta add_items_to_cart admite dos flujos: (1) si se proporciona una productUrl (por ejemplo, desde get_product_info), navega directamente a esa página del producto y hace clic en "Do koszyka"; este es el flujo preferido; (2) de lo contrario, utiliza la última página de resultados de search_products para encontrar y añadir el producto.

"Elimina la mantequilla de mi carrito"

La herramienta remove_item_from_cart encuentra un producto en el carrito por su nombre y lo elimina.

"Cambia la cantidad de leche a 3"

La herramienta update_item_quantity encuentra el producto en el carrito y actualiza su cantidad.

"¿Hay algún problema con mi carrito?"

La herramienta check_cart_issues escanea el carrito en busca de productos agotados y muestra sustitutos disponibles para cada uno.

"¿Qué opiniones tiene el Skyr Piątnica?"

La herramienta get_product_reviews obtiene las valoraciones y opiniones de los clientes de Trustmate.

"Muéstrame las promociones activas en mi carrito"

La herramienta view_promotions enumera todas las promociones activas, insignias de descuento y ahorros totales.

3. Pago

"Finaliza mi sesión de Frisco"

La herramienta finish_session abre tu carrito en frisco.pl/stn,cart para que puedas elegir una franja horaria de entrega y pagar; el servidor nunca realiza el pago automáticamente.


Estructura del proyecto

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

Almacenamiento de datos

Todos los datos del usuario se almacenan localmente en ~/.frisco-mcp/:

Archivo

Propósito

session.json

Cookies del navegador guardadas (sin credenciales)

current-session.json

Puntero a la sesión de registro activa

logs/<id>.jsonl

Registros de eventos por sesión


Desarrollo

# 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

Las pruebas se ejecutan automáticamente en cada push y pull request a master a través de GitHub Actions (.github/workflows/test.yml). La matriz realiza pruebas contra Node.js 20 y 22.


Stack tecnológico

Biblioteca

Rol

@modelcontextprotocol/sdk

Marco de trabajo del servidor MCP

playwright

Automatización del navegador (Chromium)

cheerio

Análisis HTML para información de productos

zod

Validación de esquema de entrada

typescript

Lenguaje y compilación

vitest

Marco de pruebas unitarias


Licencia

Este proyecto está bajo la Licencia MIT.

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