oskelly-mcp

Servidor MCP para el catálogo público de oskelly.ru. 14 herramientas, solo operaciones anónimas de solo lectura, todas probadas en el sitio en vivo.

Proyecto no oficial, no afiliado con Oskelly. Lee exactamente lo que ve cualquier visitante sin registrarse. Las marcas comerciales pertenecen a sus propietarios.

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), la ruta debe ser absoluta:

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

  • spawn node ENOENT en Windows → reemplace "node" por la salida de where node, las barras se escapan.

  • Después de editar, reinicie completamente la aplicación, incluido el icono en la bandeja.

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

• Depuración — npm run inspector

Tools

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

Scope

No hay ni puede haber inicio de sesión, cookies, carrito, favoritos, mensajes, pedidos. Esto es una propiedad del código:

• credentials: "omit", sin Authorization/Cookie.

• POST solo está permitido en tres endpoints de búsqueda de solo lectura — allow-list assertReadOnlyPost en src/client.ts.

• Todas las tools: readOnlyHint: true, destructiveHint: false.

• La prueba de humo verifica que en la lista de tools no haya nombres con login/cart/favourite/order/checkout/message/account.

Notes

• La ficha del producto se parsea desde __NUXT_DATA__. No hay un endpoint JSON público para un solo producto (GET /api/v2/products/{id} → 404), la página se renderiza con Nuxt 3 en el servidor. El payload se decodifica con el paquete oficial devalue — la misma biblioteca con la que Nuxt lo serializa; los tipos personalizados se conectan a través de los revivers estándar (src/nuxt.ts). No es Playwright: ~150 MB de Chromium y 3–5 s frente a un solo GET en ~150 ms.

• El slug en la URL se ignora — solo importa el id numérico al final, la tool acepta ambos.

• Formato de filtros en el cuerpo de /products/search*: selección múltiple — array de ids ({"brand": [675]}), booleano — boolean puro ({"sale": true}), precio — objeto ({"price": {"lower": 50000}}). {"brand": "675"} y {"sale": [true]} se ignoran silenciosamente, {"price": [a, b]} da success: false.

• El precio se filtra por talla-SKU, no por el precio de la ficha — un producto puede aparecer en los resultados con un precio de ficha inferior al límite, por lo que cada respuesta lleva sizePriceRange: {min, max}.

• Los contadores del upstream se renombraron: totalAmount → totalMatches, itemsCount → itemsOnPage.

• Segmentos (baseCategory) — id de nodos del árbol: Mujer=2, Hombre=105, Infantil=188, Lifestyle=366.

• WAF: la cirílica en la consulta debe estar percent-encoded, si no, 403.

• Contexto: las respuestas crudas son enormes (árbol ~1 MB, marcas ~750 KB), por lo que por defecto se devuelve una proyección compacta; verbose: true devuelve la respuesta sin tocar.

Testing

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

La prueba de humo levanta el servidor compilado como un proceso separado por stdio y ejecuta cada tool contra el sitio en vivo — sin mocks. Los parámetros se encadenan a partir de respuestas anteriores (marca → búsqueda → productId → sellerId → banner), y cada llamada pasa una verificación sustancial: PRICE_DESC realmente da precios descendentes, conditionIds: [1] — realmente solo el estado 1, los filtros reducen los resultados de forma monótona. La última ejecución es — SMOKE-TEST-OUTPUT.txt (23 llamadas, 14/14 tools, 0 fallos).

CI compila el proyecto en Node 22/24/26 y ejecuta npm run verify. La prueba de humo en vivo está en una ejecución manual (Actions → CI → Run workflow → run_smoke_test), para no golpear el sitio ajeno desde los 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

Los PR son bienvenidos. Antes de enviar — npm run build, npm run verify, node smoke-test.mjs.

Los puntos más frágiles, si oskelly se actualiza: el formato __NUXT_DATA__ (fallará con un error explícito, que indica añadir un reviver en src/nuxt.ts), los códigos de facetas, los id de segmentos. El rate-limiting no se ha probado; timeout de 45 s, sin reintentos — deliberadamente.