Content
# Tool List
Tools for searching/comparing goods on **Wildberries** (and **Ozon** — in plans) for the agent
[Hermes](https://hermes-agent.nousresearch.com). Connects as an MCP server.
Comparison and recommendations are made by LLM itself — tools only provide normalized data.
Status: **Wildberries and Ozon — both are ready** (search/card/reviews on each).
One request `marketplace="all"` searches on both. See `SPEC.md`.
## Tools
| Tool | What it does |
|---|---|
| `marketplace_search` | Search for goods → normalized output (price, rating, reviews, link, preview) |
| `get_product_card` | Full product card: characteristics, description, image URLs |
| `get_reviews` | Reviews (sorted by usefulness/freshness) |
## Installation
```bash
git clone <repo> hermes-marketplace-tools
cd hermes-marketplace-tools
uv venv && uv pip install -e .
uv run python -m camoufox fetch # Firefox binary for Ozon (~300 MB, one-time)
```
> Ozon uses a headless browser (camoufox). WB works via HTTP and does not require a browser.
> `playwright` is pinned to 1.50.0 — newer versions break the protocol with the firefox build of camoufox.
## Configuration
The proxy (SOCKS5, RU-IP) is set using the environment variable `PROXY_URL`. **Do not commit credentials.**
```bash
export PROXY_URL="socks5h://USER:PASS@pool.proxy.market:10000"
```
## Connecting to Hermes
In `~/.hermes/config.yaml`:
```yaml
mcp_servers:
marketplace:
command: "/path/to/hermes-marketplace-tools/.venv/bin/python"
args: ["-m", "mcp_server.server"]
env:
PROXY_URL: "socks5h://USER:PASS@pool.proxy.market:10000"
```
After editing the config, **restart Hermes** — MCP servers are loaded at startup.
The tools will appear as `mcp_marketplace_marketplace_search`, etc.
## Local Run (without Hermes)
```bash
PROXY_URL="socks5h://..." .venv/bin/python -m mcp_server.server # starts MCP via stdio
```
To check the core logic — see `marketplace_core` (you can import `MarketplaceService` directly; it will also be used by the future Telegram bot).
## Notes on WB (important in case of breakdowns)
- All traffic goes through a proxy (RU-IP); prices come in kopecks.
- `card.wb.ru/v4` returns 403 on Chrome's TLS profile — the client uses `impersonate="safari"`.
- Image URLs are collected according to the scheme `basket-{NN}.wbbasket.ru/...`; the number `NN` is selected
self-healing and cached in `~/.hermes/marketplace_cache.sqlite`.
- WB endpoints are unofficial and sometimes change versions — see `SPEC.md` (Appendix A).
