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.

Example: AI adding products from a shopping list to the Frisco cart

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.

MCP Servers