Skip to main content
Glama
oskelly-mcp

oskelly-mcp

oskelly-mcp

CI License: MIT

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

Tool

What it does

oskelly_describe_filters

Cheat sheet for the filter model: codes, formats, how to resolve a name into an id

oskelly_search_products

Search: query, facets, price, boolean tags, pagination, sorting

oskelly_search_facets

Same query, but returns counts and available facets instead of products

oskelly_filter_values

Values of a single facet with ids (brand, category, size, condition, …)

oskelly_search_suggestions

Query autocomplete

oskelly_category_tree

Category tree, trimmed by rootId / depth

oskelly_list_brands

Brands with ids, substring search, pagination

oskelly_list_conditions

Product conditions with descriptions

oskelly_list_attributes

Attribute dictionary (material, color, …)

oskelly_get_product

Product card by id or URL: description, attributes, sizes, photos, seller

oskelly_seller_products

Seller's products

oskelly_seller_filters

What actually exists in the seller's assortment

oskelly_home_banners

Homepage banners (FEMALE/MALE/KIDS/LIFESTYLE)

oskelly_banner_catalog

Expands a banner collection into a filter preset + products

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.

Available Tools

14 tools
oskelly_banner_catalogResolve a banner/curated selection to productsA
Read-onlyIdempotent

Open an oskelly.ru curated-selection page (a banner's catalogLink, e.g. https://oskelly.ru/catalog/bannerV2/) and return its title, the filter preset it encodes (for example a specific seller's wardrobe), the total item count and the first page of products. Curated pages are rendered server-side, so this reads the page's Nuxt payload rather than an API endpoint.

Inputs: catalogLink (required), verbose.

oskelly_category_treeCategory treeA
Read-onlyIdempotent

Return the oskelly.ru category tree. The root (id 1, 'Каталог') has the four top-level segments as children — their ids are real tree node ids read from the live tree, not a fixed enum. Use rootId to zoom into a subtree and depth to control how many levels come back (the full tree is ~618 nodes / 1 MB, so keep depth small). Category ids from here feed oskelly_search_products categoryIds and baseCategory.

Inputs: depth, rootId, verbose.

oskelly_describe_filtersExplain the filter modelA
Read-onlyIdempotent

Return a cheat-sheet of every filter code this server understands, how values are encoded, and which tool resolves names to ids. Call this once at the start of a browsing session instead of guessing filter names.

Inputs: no named parameters.

oskelly_filter_valuesList values of one facetA
Read-onlyIdempotent

List the selectable values (with their ids) of a single facet, scoped to the same search context. This is how you resolve a human name to the numeric id that oskelly_search_products expects — e.g. code='brand' to find the id of GUCCI, code='size' to find size value ids for the current category. Accepts every search parameter so the returned values reflect the narrowed result set.

Inputs: code (required), page, limit, price, +17 more.

oskelly_get_productGet product detailA
Read-onlyIdempotent

Fetch the full detail of a single oskelly.ru product by numeric id or product URL: description, condition, all attributes (material/colour/...), full size chart with per-size stock and pricing, breadcrumbs, every image, tags, and the seller's public profile. NOTE: oskelly.ru has no public JSON endpoint for a single product (/api/v2/products/{id} returns 404), so this reads the server-rendered Nuxt payload embedded in the product page and decodes it with the official devalue library.

Inputs: product (required), verbose.

oskelly_home_bannersHomepage bannersA
Read-onlyIdempotent

Return the promotional banners / curated selections shown on the oskelly.ru homepage for a given audience segment: title, description, image, and the catalog link that opens the underlying selection. Feed a banner's catalogLink into oskelly_banner_catalog to see what products it actually resolves to.

Inputs: category.

oskelly_list_attributesList product attributesA
Read-onlyIdempotent

List the product attribute dictionary (material, colour, style, ... ) with every possible value and its id. These are the attributes shown on a product card as 'Материал', 'Цвет' etc. Filter by name/code to keep the response small.

Inputs: limit, nameContains, includeValues.

oskelly_list_brandsList brandsA
Read-onlyIdempotent

List brands available on oskelly.ru with their numeric ids (needed for the brandIds search filter), url slugs and transliterated Russian names. The full list is ~7000 brands, so filter with nameContains or page through with limit/offset.

Inputs: limit, offset, nameContains, includeHidden.

oskelly_list_conditionsList product conditionsA
Read-onlyIdempotent

List the product condition grades used on oskelly.ru (id, name and the full Russian explanation of what each grade guarantees). Condition ids feed the conditionIds filter.

Inputs: no named parameters.

oskelly_search_facetsGet result count and available facetsA
Read-onlyIdempotent

Run the same search as oskelly_search_products but return the total result count plus the list of facets available for that result set (their codes, names, types, hot values and the price range present) instead of the products. Use this to discover which filters make sense before drilling down, or to count matches cheaply without fetching items.

Inputs: page, price, query, sizeIds, +14 more.

oskelly_search_productsSearch productsA
Read-onlyIdempotent

Search the oskelly.ru luxury marketplace catalog and return matching product cards (id, brand, category, price, discount, condition, in-stock sizes, seller, image, URL). Supports full-text query, faceted filtering (brand, category, size, condition, collection, model, seller type, boutique, price range, boolean tags such as sale/vintage/outlet), pagination and sorting. Use oskelly_search_facets first when you need to know which filter values are available, and oskelly_filter_values to resolve names to ids.

Inputs: page, price, query, sizeIds, +14 more.

oskelly_search_suggestionsSearch autocompleteA
Read-onlyIdempotent

Get search-query autocomplete suggestions from oskelly.ru for a partial user query. Useful for discovering how the marketplace phrases things (brand + item combinations) before running a full search.

Inputs: userQuery (required), size.

oskelly_seller_filtersGet a seller's available filtersA
Read-onlyIdempotent

Return the sets of ids that actually occur in one seller's inventory — which attribute values, categories, brands, sizes and conditions they carry. Use it to understand a seller's assortment before filtering their catalog.

Inputs: sellerId (required), verbose.

oskelly_seller_productsList a seller's productsA
Read-onlyIdempotent

List the products currently offered by a specific oskelly.ru seller (boutique, brand or private seller), with pagination and sorting. Seller ids come from the seller block of any product card or from oskelly_get_product.

Inputs: sellerId (required), page, sorting, verbose, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: search, facet discovery, filter value resolution, autocomplete, category tree, dictionary lookups, product detail, seller queries, and banner catalogs. Even the two facet-related tools are explicitly differentiated by what they return.

    Naming Consistency4/5

    The dominant pattern is oskelly_<verb>_<object> (search_products, list_brands, get_product, describe_filters). A few names omit the verb (seller_products, home_banners, banner_catalog), but they are still predictable and readable.

    Tool Count5/5

    14 tools is within the well-scoped range and each one covers a meaningful browsing need, from category and dictionary lookups to search, product detail, seller inventory, and curated banners. No tool feels redundant.

    Completeness5/5

    The read-only marketplace browsing surface is well covered: discovery via suggestions/categories/brands/conditions/attributes, faceted search, product detail, seller-focused queries, and banner-driven curated catalogs. The filter cheat-sheet and facet/filter value tools close the gap between filter names and the ids that search_products expects.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      MCP server for MoySklad (МойСклад) warehouse and CRM management API. 21 tools covering the full order lifecycle: products, stock, counterparties, customer orders, shipments, supplies, warehouses, organizations, reports, and webhooks.
      60
      70 npm
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A UCP-compliant MCP storefront server that exposes product catalog operations (search, cart, checkout) as MCP tools, following UCP schema version 2026-04-08.
      5
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.
      -