Skip to main content
Glama

Frisco MCP

AI 어시스턴트(Claude, Gemini 등)가 폴란드의 온라인 식료품점인 frisco.pl과 상호 작용할 수 있게 해주는 TypeScript Model Context Protocol (MCP) 서버입니다.

보안 우선 — 이 서버는 귀하의 이메일이나 비밀번호를 절대 저장하지 않습니다. 사용자는 표시되는 브라우저 창에서 수동으로 로그인하며, 세션 쿠키만 로컬에 유지됩니다.

예시: AI가 쇼핑 목록의 상품을 Frisco 장바구니에 추가하는 모습


기능

세션

도구

설명

login

로그인 페이지에서 표시되는 Chromium 창을 엽니다. 사용자가 수동으로 로그인하면 서버가 성공 여부를 확인하고 세션 쿠키를 저장합니다.

finish_session

결제 페이지에서 브라우저를 열어 배송 시간대를 선택하고 결제할 수 있도록 합니다. 자동 결제는 지원하지 않습니다.

clear_session

브라우저를 닫고 저장된 세션 파일을 삭제합니다.

장바구니

도구

설명

add_items_to_cart

장바구니에 상품을 추가합니다. 두 가지 흐름을 지원합니다: (1) productUrl을 통한 방법 — 상품 페이지로 직접 이동하여 "Do koszyka"를 클릭합니다; (2) 최신 search_products 결과 페이지에서 추가합니다.

view_cart

현재 장바구니 내용과 총 가격을 반환합니다.

remove_item_from_cart

이름(부분 일치)으로 장바구니에서 특정 상품을 제거합니다.

update_item_quantity

장바구니에 이미 있는 상품의 수량을 변경합니다(이름 부분 일치).

check_cart_issues

장바구니에서 품절되거나 사용할 수 없는 상품을 감지하고 각 상품에 대한 대체 상품 목록을 제공합니다.

view_promotions

현재 장바구니의 활성 프로모션, 할인 및 총 절약 금액을 보여줍니다.

상품

도구

설명

search_products

frisco.pl을 검색하여 가격/재고 상태가 포함된 상위 N개의 결과를 반환하고, 장바구니 추가를 위해 검색 URL/컨텍스트를 저장합니다.

get_product_info

상세 상품 정보를 반환합니다: 영양 성분(100g당 매크로), 중량/용량, 성분, 가격(프로모션 시 원래 가격 및 단위 가격 포함).

get_product_reviews

상품에 대한 고객 리뷰 및 평점(Trustmate 제공)을 반환합니다.

로그

도구

설명

get_logs

현재 또는 특정 세션에 대한 JSONL 로그 이벤트를 반환합니다.

tail_logs

가장 최근의 N개 로그 이벤트를 반환합니다.


Related MCP server: Rohlik MCP Server

아키텍처

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

더 많은 다이어그램(로그인 흐름, 장바구니 흐름): docs/DIAGRAMS.md


요구 사항

  • Node.js 20 이상

  • Chromium (Playwright용, 아래 설정 명령을 통해 설치)


설정

npm install
npx playwright install chromium
npm run build

MCP 클라이언트 구성

이 서버는 stdio를 통해 통신합니다. MCP 클라이언트가 node dist/index.js를 가리키도록 설정하세요.

Claude Desktop

claude_desktop_config.json에 추가하세요:

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

Gemini (Google AI Studio)

이 저장소의 .gemini/settings.json에 이미 구성이 포함되어 있습니다:

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

Cursor

Cursor MCP 설정(~/.cursor/mcp.json 또는 워크스페이스 .cursor/mcp.json)에 추가하세요:

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

참고: 경로를 사용 중인 컴퓨터의 dist/index.js 절대 경로로 바꾸세요.


사용법

1. 로그인

"Frisco에 로그인해줘"

login 도구는 frisco.pl/login에서 Chromium 창을 엽니다. 수동으로 로그인하세요. 서버는 최대 5분 동안 대기하며 성공적인 로그인이 감지되면 세션 쿠키를 저장합니다.

2. 쇼핑

"플레인 요거트 찾아줘"

search_products 도구는 가격이 포함된 일치하는 상품 목록을 반환합니다. 사용할 수 없는 상품은 ⚠️ NIEDOSTĘPNY로 표시됩니다. 또한 후속 장바구니 작업을 위해 현재 검색 URL과 결과 컨텍스트를 저장합니다.

"PIĄTNICA Skyr에 대해 더 알려줘"

get_product_info 도구는 상품 페이지로 이동하여 상세 정보를 추출합니다: 영양 성분(100g당 kcal, 단백질, 지방, 탄수화물, 당류, 염분), 중량/용량, 성분, 가격(프로모션 상품의 경우 원래 가격 및 단위 가격 포함) 및 상품 URL.

"장바구니에 추가해줘"

add_items_to_cart 도구는 두 가지 흐름을 지원합니다: (1) productUrl이 제공된 경우(예: get_product_info에서 가져온 경우), 해당 상품 페이지로 직접 이동하여 "Do koszyka"를 클릭합니다(권장 흐름); (2) 그렇지 않은 경우, 최신 search_products 결과 페이지를 사용하여 상품을 찾아 추가합니다.

"장바구니에서 버터 제거해줘"

remove_item_from_cart 도구는 이름으로 장바구니에서 상품을 찾아 제거합니다.

"우유 수량을 3개로 변경해줘"

update_item_quantity 도구는 장바구니에서 상품을 찾아 수량을 업데이트합니다.

"장바구니에 문제 있니?"

check_cart_issues 도구는 장바구니에서 품절된 상품을 스캔하고 각 상품에 대한 대체 상품을 보여줍니다.

"Skyr Piątnica 리뷰는 어때?"

get_product_reviews 도구는 Trustmate에서 고객 평점과 리뷰를 가져옵니다.

"장바구니의 활성 프로모션 보여줘"

view_promotions 도구는 모든 활성 프로모션, 할인 배지 및 총 절약 금액을 나열합니다.

3. 결제

"Frisco 세션 종료해줘"

finish_session 도구는 frisco.pl/stn,cart에서 장바구니를 열어 배송 시간대를 선택하고 결제할 수 있도록 합니다. 서버는 자동으로 결제를 수행하지 않습니다.


프로젝트 구조

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

데이터 저장

모든 사용자 데이터는 로컬 ~/.frisco-mcp/에 저장됩니다:

파일

용도

session.json

저장된 브라우저 쿠키 (자격 증명 없음)

current-session.json

활성 로그 세션에 대한 포인터

logs/<id>.jsonl

세션별 이벤트 로그


개발

# 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

테스트는 GitHub Actions(.github/workflows/test.yml)를 통해 master 브랜치에 대한 모든 push 및 pull request 시 자동으로 실행됩니다. 매트릭스 테스트는 Node.js 20 및 22를 대상으로 합니다.


기술 스택

라이브러리

역할

@modelcontextprotocol/sdk

MCP 서버 프레임워크

playwright

브라우저 자동화 (Chromium)

cheerio

상품 정보용 HTML 파싱

zod

입력 스키마 검증

typescript

언어 및 빌드

vitest

단위 테스트 프레임워크


라이선스

이 프로젝트는 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