oskelly-mcp

MCP server for the public catalog of oskelly.ru. 14 tools, anonymous read-only operations only, all verified against the live site.

Unofficial project, not affiliated with Oskelly. Reads exactly what any visitor without registration sees. Trademarks belong to their respective owners.

License

MIT

Related MCP server: VkusVill MCP Server

Installation

Node.js 22+.

git clone https://github.com/ihavealotofguap/oskelly-mcp.git
cd oskelly-mcp
npm ci
npm run build
npm run verify

• Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config), the path must be absolute:

  { "mcpServers": { "oskelly": { "command": "node", "args": ["/abs/path/oskelly-mcp/dist/index.js"] } } }

  • spawn node ENOENT on Windows → replace "node" with the output of where node, escape the slashes.

  • After editing, fully restart the app, including the tray icon.

• Claude Code — claude mcp add oskelly -- node /abs/path/oskelly-mcp/dist/index.js

• Debugging — npm run inspector

Tools

Flow: describe_filters → list_brands/category_tree/filter_values → search_products → get_product.

Scope

There is and can be no login, cookies, cart, favorites, messages, or orders. This is a property of the code:

• credentials: "omit", no Authorization/Cookie headers.

• POST is allowed only for three read-only search endpoints — the allow-list assertReadOnlyPost in src/client.ts.

• All tools: readOnlyHint: true, destructiveHint: false.

• A smoke test verifies that the tools list contains no names with login/cart/favourite/order/checkout/message/account.

Notes

• The product card is parsed from __NUXT_DATA__. There is no public JSON endpoint for a single product (GET /api/v2/products/{id} → 404), the page is rendered by Nuxt 3 on the server. The payload is decoded with the official devalue package — the same library Nuxt uses to serialize it; custom types are wired in through the standard revivers (src/nuxt.ts). Not Playwright: ~150 MB of Chromium and 3–5 s versus a single GET in ~150 ms.

• The slug in the URL is ignored — only the numeric id at the end matters, the tool accepts both.

• Filter format in the /products/search* body: multi-select is an array of ids ({"brand": [675]}), boolean is a bare boolean ({"sale": true}), price is an object ({"price": {"lower": 50000}}). {"brand": "675"} and {"sale": [true]} are silently ignored, {"price": [a, b]} yields success: false.

• Price is filtered by the size-SKU, not by the card price — a product can appear in results with a card price below the boundary, so every response carries sizePriceRange: {min, max}.

• Upstream counters are renamed: totalAmount → totalMatches, itemsCount → itemsOnPage.

• Segments (baseCategory) are tree node ids: Women=2, Men=105, Kids=188, Lifestyle=366.

• WAF: Cyrillic in the query must be percent-encoded, otherwise 403.

• Context: raw responses are huge (the tree is ~1 MB, brands ~750 KB), so a compact projection is returned by default; verbose: true returns the untouched response.

Testing

npm run verify        # офлайн: сервер стартует, 14 tools, все read-only
node smoke-test.mjs   # живой end-to-end по MCP против oskelly.ru

The smoke test launches the compiled server as a separate process over stdio and exercises every tool against the live site — no mocks. Parameters are chained from previous responses (brand → search → productId → sellerId → banner), and each call passes a meaningful check: PRICE_DESC really yields descending prices, conditionIds: [1] really yields only condition 1, filters narrow the results monotonically. The latest run is SMOKE-TEST-OUTPUT.txt (23 calls, 14/14 tools, 0 failures).

CI builds the project on Node 22/24/26 and runs npm run verify. The live smoke test is moved to a manual run (Actions → CI → Run workflow → run_smoke_test) so as not to hammer a third-party site from runners.

Structure

src/client.ts             HTTP-клиент, конверт, allow-list на POST
src/nuxt.ts               извлечение и декодирование SSR-payload (devalue)
src/search.ts             схема и сборка тела запроса для /products/search*
src/format.ts             компактные проекции ответов
src/tools.ts              определения 14 инструментов
src/index.ts              точка входа, stdio-транспорт
scripts/verify-server.mjs офлайн-проверка поверхности tools (CI)
smoke-test.mjs            живой end-to-end тест по протоколу MCP

Contributing

PRs are welcome. Before submitting — npm run build, npm run verify, node smoke-test.mjs.

The most fragile spots if oskelly updates: the __NUXT_DATA__ format (it will fail with an explicit error pointing to adding a reviver in src/nuxt.ts), facet codes, segment ids. Rate-limiting has not been tested; 45 s timeout, no retries — deliberately.