Frisco MCP
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.

Características
Sesión
Herramienta | Descripción |
| 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. |
| 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. |
| Cierra el navegador y elimina el archivo de sesión guardado. |
Carrito
Herramienta | Descripción |
| Añade productos al carrito. Admite dos flujos: (1) mediante |
| Devuelve el contenido actual del carrito y el precio total. |
| Elimina un producto específico del carrito por nombre (coincidencia parcial). |
| Cambia la cantidad de un producto que ya está en el carrito (coincidencia parcial de nombre). |
| Detecta productos agotados o no disponibles en el carrito y enumera sustitutos disponibles para cada uno. |
| Muestra promociones activas, descuentos y ahorros totales en el carrito actual. |
Productos
Herramienta | Descripción |
| 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. |
| 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). |
| Devuelve las opiniones y valoraciones de los clientes (de Trustmate) para un producto. |
Registros
Herramienta | Descripción |
| Devuelve eventos de registro en formato JSONL para la sesión actual o una específica. |
| 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 --> KMá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 buildConfiguració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.jsen 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
└── .gitignoreAlmacenamiento de datos
Todos los datos del usuario se almacenan localmente en ~/.frisco-mcp/:
Archivo | Propósito |
| Cookies del navegador guardadas (sin credenciales) |
| Puntero a la sesión de registro activa |
| 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:watchCI
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 |
Marco de trabajo del servidor MCP | |
Automatización del navegador (Chromium) | |
Análisis HTML para información de productos | |
Validación de esquema de entrada | |
Lenguaje y compilación | |
Marco de pruebas unitarias |
Licencia
Este proyecto está bajo la Licencia MIT.
Available Tools
10 toolsadd_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Let your AI agent operate any website through a real, logged-in browser session.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to search for products, manage shopping carts, and place grocery orders on Instacart using browser automation. It includes comprehensive tools for store discovery, product searching, and secure checkout with explicit user confirmation.1159 npm12MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, and access account, order, delivery, and discount information across multiple European online grocery platforms.MIT