MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

F
Frisco MCP
by @mkidawa
GitHub Repo(2 stars)

MCP server that lets AI assistants (Claude, Gemini, Cursor) shop on frisco.pl - search products, manage cart, view nutritional info, all via natural language.

Created 4/5/2026
Updated about 20 hours ago
README
View Source
Repository documentation and setup instructions

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 | Adds products to cart. Supports two flows: (1) via productUrl — navigates directly to the product page and clicks "Do koszyka"; (2) from the latest search_products result page. | | 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). | | update_item_quantity | Changes the quantity of a product already in the cart (partial name match). | | check_cart_issues | Detects sold-out or unavailable products in the cart and lists available substitutes for each. | | view_promotions | Shows active promotions, discounts, and total savings in the current cart. |

Products

| Tool | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | search_products | Searches frisco.pl, returns top N results with prices/availability, and saves search URL/context for cart add. | | get_product_info | Returns detailed product info: nutritional values (macros per 100g), weight/grammage, ingredients, price (including original price and unit price if on promotion). | | get_product_reviews | Returns customer reviews and ratings (from Trustmate) for a product. |

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, 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

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

"Find me natural yogurt"

The search_products tool returns a list of matching products with prices. Unavailable products are marked with ⚠️ NIEDOSTĘPNY. It also saves the current search URL and result context for subsequent cart operations.

"Tell me more about the PIĄTNICA Skyr"

The get_product_info tool navigates to the product page and extracts detailed information: nutritional values (kcal, protein, fat, carbohydrates, sugars, salt per 100g), weight/grammage, ingredients, price (including original price and unit price for promotional products), and the product URL.

"Add it to cart"

The add_items_to_cart tool supports two flows: (1) if a productUrl is provided (e.g. from get_product_info), it navigates directly to that product page and clicks "Do koszyka" — this is the preferred flow; (2) otherwise, it uses the latest search_products results page to find and add the product.

"Remove the butter from my cart"

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

"Change the milk quantity to 3"

The update_item_quantity tool finds the product in the cart and updates its quantity.

"Are there any issues with my cart?"

The check_cart_issues tool scans the cart for sold-out products and shows available substitutes for each.

"What reviews does Skyr Piątnica have?"

The get_product_reviews tool fetches customer ratings and reviews from Trustmate.

"Show me active promotions in my cart"

The view_promotions tool lists all active promotions, discount badges, and total savings.

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, 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

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.

Quick Setup
Installation guide for this server

Installation Command (package not published)

git clone https://github.com/mkidawa/frisco-mcp
Manual Installation: Please check the README for detailed setup instructions and any additional dependencies required.

Cursor configuration (mcp.json)

{ "mcpServers": { "mkidawa-frisco-mcp": { "command": "git", "args": [ "clone", "https://github.com/mkidawa/frisco-mcp" ] } } }