From 21376cbd35051e8afbb90a16c0ba2c9566dc53a7 Mon Sep 17 00:00:00 2001
From: alvis <allogn@gmail.com>
Date: Fri, 12 Jun 2026 03:24:04 +0000
Subject: [PATCH] Add Marketplace-MCP wiki page; update index

---
 Home.md            |  1 +
 Marketplace-MCP.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 Marketplace-MCP.md

diff --git a/Home.md b/Home.md
index b35dd1a..09c6ccd 100644
--- a/Home.md
+++ b/Home.md
@@ -25,6 +25,7 @@
 - [[Matrix]] — Synapse homeserver, E2EE bot adapter (Adolf + Zabbix)
 - [[Radicale]] — CalDAV/CardDAV (calendar and contacts)
 - [[Kanboard]] — Kanban boards; tasks assignable to Claude via agap-mcp
+- [[Marketplace-MCP]] — MCP shopping tools (Metro, Магнит, ВкусВилл, Ozon, Amazon, …)
 - [[qBittorrent]] — BitTorrent client with web UI
 
 ## Quick Start
diff --git a/Marketplace-MCP.md b/Marketplace-MCP.md
new file mode 100644
index 0000000..9f1498a
--- /dev/null
+++ b/Marketplace-MCP.md
@@ -0,0 +1,92 @@
+# Marketplace MCP
+
+MCP server exposing shopping tools for Russian (and one international) marketplaces. Used by AI assistants (Torgash bot, Claude) to search, compare prices, and add items to cart.
+
+- Container: `marketplace-mcp-marketplace-mcp-1`
+- Port: `3101`
+- Source: `agap_git/marketplace-mcp/`
+- Config: `src/marketplace.js` (handlers), `src/server.js` (MCP tools)
+
+## Supported stores
+
+| Store | Key | Search | Cart/Order | Auth needed |
+|-------|-----|--------|-----------|-------------|
+| Metro Cash & Carry | `metro` | ✅ GraphQL API | ✅ (needs login) | VNC |
+| Магнит | `magnit` | ✅ REST API | ✅ (needs login) | VNC |
+| ВкусВилл | `vkusvill` | ✅ Playwright | ✅ (needs login) | VNC |
+| Ozon | `ozon` | ✅ Playwright | ✅ | VNC |
+| Яндекс.Маркет | `yandex_market` | ✅ Playwright | ✅ | VNC |
+| AliExpress | `aliexpress` | ✅ Playwright | ✅ | VNC |
+| Авито | `avito` | ✅ Playwright | ✅ | VNC |
+| Amazon.de | `amazon` | ✅ Playwright + proxy | ✅ (needs login) | VNC |
+
+### Blocked stores (IP reputation — Qrator/servicepipe protection)
+
+| Store | Blocker | Status |
+|-------|---------|--------|
+| Лента | Qrator hard 403 | ❌ Needs residential IP |
+| Ашан | Qrator hard 403 | ❌ Needs residential IP |
+| Утконос | Qrator hard 403 | ❌ Needs residential IP |
+| Перекрёсток | servicepipe.ru | ❌ Needs residential IP |
+| SberMarket | servicepipe.ru | ❌ Needs residential IP |
+| Самокат | servicepipe.ru | ❌ Needs residential IP |
+| Пятёрочка | servicepipe.ru (server IP blocked) | ❌ See [[project_pyaterochka_api]] |
+
+## MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `marketplace_search` | Free-text search, returns ranked list |
+| `marketplace_find_best` | Search + auto-pick best result |
+| `marketplace_compare_prices` | **Parallel multi-store price comparison** — cheapest-first ranking in one call |
+| `marketplace_get_product` | Details for a known product id/url |
+| `marketplace_get_reviews` | Reviews for a product |
+| `marketplace_get_recommendations` | Similar/related products |
+| `marketplace_add_to_cart` | Add to cart (requires login) |
+| `marketplace_get_cart` | View cart contents |
+| `marketplace_open_vnc` | Open VNC for manual login |
+| `marketplace_save_session` | Save session after VNC login |
+| `marketplace_status` | Check if store has a saved session |
+
+## Technical notes
+
+### Metro
+- GraphQL API: `https://online.metro-cc.ru/api/graphql`
+- No auth needed for search
+- Fields: `search(storeId: 10, text: $q) { products(size: $n) { products { id name url prices { price } } } }`
+
+### Магнит
+- REST API: `POST https://magnit.ru/webgate/v2/goods/search`
+- Prices in kopecks — divide by 100 for rubles
+- Hardcoded `storeCode: 992301` (Moscow dostavka warehouse)
+- No auth for search; cart needs VNC login (Yandex Captcha blocks anon)
+
+### ВкусВилл
+- Search: Playwright renders `https://vkusvill.ru/search/?search_text={query}`, extracts `.js-datalayer-catalog-list` items
+- Product pages use microdata (`itemprop="price"`, `itemprop="name"`) — no JSON-LD
+- Search results mix popular items with query matches; first 6 results may not be query-specific
+- Cart/order: VNC login at `https://vkusvill.ru/personal/`
+
+### Amazon
+- Uses `amazon.de` (EU) — `amazon.com` returns 503 via this proxy
+- Playwright browser context uses system proxy `http://127.0.0.1:56928`
+- Login: VNC at `https://www.amazon.de/ap/signin`
+
+## VNC login flow
+
+```
+marketplace_open_vnc("store")    # opens browser tab at store login page
+# user connects via VNC and logs in
+marketplace_save_session("store")  # saves cookies/session to /sessions/{store}.json
+```
+
+Sessions persist across restarts (stored in container volume).
+
+## Start / stop
+
+```bash
+cd ~/agap_git/marketplace-mcp
+docker compose up -d
+docker compose restart marketplace-mcp
+docker logs marketplace-mcp-marketplace-mcp-1 -f
+```