oskelly-mcp

MCP-сервер для публичного каталога oskelly.ru. 14 инструментов, только анонимные read-only операции, все проверены на живом сайте.

Неофициальный проект, не аффилирован с Oskelly. Читает ровно то, что видит любой посетитель без регистрации. Товарные знаки принадлежат их владельцам.

License

MIT

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), путь обязан быть абсолютным:

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

  • spawn node ENOENT на Windows → замените "node" на вывод where node, слэши экранируются.
  • После правки полностью перезапустите приложение, включая иконку в трее.

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

• Отладка — npm run inspector

Tools

Tool	Что делает
oskelly_describe_filters	Шпаргалка по модели фильтров: коды, форматы, чем резолвить имя в id
oskelly_search_products	Поиск: запрос, фасеты, цена, булевы теги, пагинация, сортировка
oskelly_search_facets	Тот же запрос, но отдаёт счётчик и доступные фасеты вместо товаров
oskelly_filter_values	Значения одного фасета с id (brand, category, size, condition, …)
oskelly_search_suggestions	Автокомплит запроса
oskelly_category_tree	Дерево категорий, обрезка по rootId / depth
oskelly_list_brands	Бренды с id, поиск по подстроке, пагинация
oskelly_list_conditions	Состояния товара с описаниями
oskelly_list_attributes	Словарь атрибутов (материал, цвет, …)
oskelly_get_product	Карточка по id или URL: описание, атрибуты, размеры, фото, продавец
oskelly_seller_products	Товары продавца
oskelly_seller_filters	Что реально есть в ассортименте продавца
oskelly_home_banners	Баннеры главной (FEMALE/MALE/KIDS/LIFESTYLE)
oskelly_banner_catalog	Разворачивает баннер-подборку в пресет фильтров + товары

Поток: describe_filters → list_brands/category_tree/filter_values → search_products → get_product.

Scope

Нет и не может быть логина, кук, корзины, избранного, сообщений, заказов. Это свойство кода:

• credentials: "omit", никаких Authorization/Cookie.
• POST разрешён только на три read-only search-эндпоинта — allow-list assertReadOnlyPost в src/client.ts.
• Все tools: readOnlyHint: true, destructiveHint: false.
• Smoke-тест проверяет, что в списке tools нет имён с login/cart/favourite/order/checkout/message/account.

Notes

• Карточка товара парсится из __NUXT_DATA__. Публичного JSON-эндпоинта для одного товара нет (GET /api/v2/products/{id} → 404), страница рендерится Nuxt 3 на сервере. Payload декодируется официальным пакетом devalue — той же библиотекой, которой Nuxt его и сериализует; кастомные типы подключены через штатные revivers (src/nuxt.ts). Не Playwright: ~150 МБ Chromium и 3–5 с против одного GET за ~150 мс.
• Слаг в URL игнорируется — значение имеет только числовой id в конце, tool принимает и то и другое.
• Формат фильтров в теле /products/search*: мульти-выбор — массив id ({"brand": [675]}), булев — голый boolean ({"sale": true}), цена — объект ({"price": {"lower": 50000}}). {"brand": "675"} и {"sale": [true]} молча игнорируются, {"price": [a, b]} даёт success: false.
• Цена фильтруется по размеру-SKU, не по цене карточки — товар может попасть в выдачу с ценой карточки ниже границы, поэтому каждый ответ несёт sizePriceRange: {min, max}.
• Счётчики апстрима переименованы: totalAmount → totalMatches, itemsCount → itemsOnPage.
• Сегменты (baseCategory) — id узлов дерева: Женское=2, Мужское=105, Детское=188, Лайфстайл=366.
• WAF: кириллица в query обязана быть percent-encoded, иначе 403.
• Контекст: сырые ответы огромные (дерево ~1 МБ, бренды ~750 КБ), поэтому по умолчанию отдаётся компактная проекция; verbose: true возвращает нетронутый ответ.

Testing

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

Smoke-тест поднимает скомпилированный сервер отдельным процессом по stdio и дёргает каждый tool против живого сайта — без моков. Параметры выстроены в цепочку из предыдущих ответов (бренд → поиск → productId → sellerId → баннер), и каждый вызов проходит содержательную проверку: PRICE_DESC действительно даёт убывающие цены, conditionIds: [1] — действительно только состояние 1, фильтры сужают выдачу монотонно. Последний прогон — SMOKE-TEST-OUTPUT.txt (23 вызова, 14/14 tools, 0 падений).

CI собирает проект на Node 22/24/26 и гоняет npm run verify. Живой smoke-тест вынесен в ручной запуск (Actions → CI → Run workflow → run_smoke_test), чтобы не долбить чужой сайт с раннеров.

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

PR приветствуются. Перед отправкой — npm run build, npm run verify, node smoke-test.mjs.

Самые ломкие места, если oskelly обновится: формат __NUXT_DATA__ (упадёт с явной ошибкой, указывающей добавить reviver в src/nuxt.ts), коды фасетов, id сегментов. Rate-limiting не тестировался; таймаут 45 с, ретраев нет — сознательно.