Frisco MCP

A TypeScript Model Context Protocol (MCP) server that lets AI assistants (Claude, Gemini, etc.) interact with frisco.pl — Poland's online grocery store.

Security First — The server never stores your email or password. You log in manually in a visible browser window; only session cookies are persisted locally.

---

Features

Session

Tool	Description
login	Opens a visible Chromium window at the login page. You log in manually; the server polls for success and saves session cookies.
finish_session	Opens the browser at the checkout page so you can select a delivery slot and pay. No automatic payment.
clear_session	Closes the browser and deletes the saved session file.

Cart

Tool	Description
add_items_to_cart	Accepts a JSON list of products (name, search query, quantity). Searches for each item and clicks "Add to cart". Optionally clears the cart first.
view_cart	Returns the current cart contents and total price.
remove_item_from_cart	Removes a specific product from the cart by name (partial match).

Products

Tool	Description
search_products	Searches frisco.pl and returns top N results with prices.
get_product_info	Returns detailed product info: nutritional values (macros per 100g), weight/grammage, ingredients, and price.

Logs

Tool	Description
get_logs	Returns JSONL log events for the current or a specific session.
tail_logs	Returns the N most recent log events.

---

Architecture

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 & parsing]
    E --> I

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

More diagrams (login flow, cart flow): docs/DIAGRAMS.md

---

Requirements

• Node.js 20 or later
• Chromium for Playwright (installed via the setup command below)

---

Setup

npm install
npx playwright install chromium
npm run build

---

MCP Client Configuration

The server communicates over stdio — point your MCP client at node dist/index.js.

Claude Desktop

Add to claude_desktop_config.json:

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

Gemini (Google AI Studio)

The .gemini/settings.json in this repo already contains the configuration:

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

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):

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

Note: Replace the path with the absolute path to dist/index.js on your machine.

---

Usage

1. Log in

"Log me in to Frisco"

The login tool opens a Chromium window at frisco.pl/login. Log in manually — the server waits up to 5 minutes and saves your session cookies once it detects a successful login.

2. Shop

"Add 2 liters of milk and wheat bread to cart"

The add_items_to_cart tool searches for each product, picks the first match, and clicks "Add to cart" the requested number of times.

"Find me natural yogurt"

The search_products tool returns a list of matching products with prices.

"Remove the butter from my cart"

The remove_item_from_cart tool finds a product in the cart by name and removes it.

3. Checkout

"Finish my Frisco session"

The finish_session tool opens your cart at frisco.pl/stn,cart so you can choose a delivery slot and pay — the server never performs payment automatically.

---

Project Structure

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
│   ├── 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
│       ├── products.ts   # search_products, get_product_info
│       └── helpers.ts    # Navigation, popup dismissal, DOM parsing
│   └── __tests__/        # Unit tests (Vitest)
├── test_data/            # Sample HTML fixtures for tests
├── 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

---

Data Storage

All user data is stored locally in ~/.frisco-mcp/:

File	Purpose
session.json	Saved browser cookies (no credentials)
current-session.json	Pointer to the active log session
logs/<id>.jsonl	Per-session event logs

---

Development

# 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 run automatically on every push and pull request to master via GitHub Actions (.github/workflows/test.yml). The matrix tests against Node.js 20 and 22.

---

Tech Stack

Library	Role
@modelcontextprotocol/sdk	MCP server framework
playwright	Browser automation (Chromium)
cheerio	HTML parsing for product info
zod	Input schema validation
typescript	Language & build
vitest	Unit testing framework

---

License

This project is licensed under the MIT License.