oskelly-mcp

MCP-Server für den öffentlichen Katalog von oskelly.ru. 14 Tools, nur anonyme read-only-Operationen, alle gegen die Live-Website getestet.

Inoffizielles Projekt, nicht mit Oskelly verbunden. Liest genau das, was jeder Besucher ohne Registrierung sieht. Markenrechte liegen bei ihren jeweiligen Inhabern.

Lizenz

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), der Pfad muss absolut sein:

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

  • spawn node ENOENT auf Windows → ersetzen Sie "node" durch die Ausgabe von where node; Backslashes müssen escaped werden.

  • Nach der Änderung starten Sie die Anwendung vollständig neu, einschließlich des Tray-Symbols.

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

• Debugging — npm run inspector

Tools

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

Geltungsbereich

Es gibt und kann es nicht geben: Login, Cookies, Warenkorb, Favoriten, Nachrichten, Bestellungen. Das ist eine Eigenschaft des Codes:

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

• POST ist nur für drei read-only-Such- sowie/Ergänzungsende zulässig — Permission-Array assertReadOnlyPost in src/client.ts.

• Alle Tools: readOnlyHint: true, destructiveHint: false.

• Der Smoke-Test stellt sicher, dass es in der Liste der Tools keine Namen mit login/cart/favourite/order/checkout/message/account gibt.

Hinweise

• Die Produktkarte wird aus __NUXT_DATA__ geparst. Für ein einzelnes Produkt gibt es keinen öffentlichen JSON-Endpunkt (GET /api/v2/products/{id} → 404); die Seite wird serverseitig mit Nuxt 3 gerendert. Der Payload wird mit der offiziellen Paket devalue dekodiert – derselben Bibliothek, mit der Nuxt ihn auch serialisiert; benutzerdefinierte Typen werden über die regulären Reviver eingebunden (src/nuxt.ts). Nicht Playwright: ~150 MB Chromium und 3–5 s gegenüber einem einzelnen GET in ~150 ms.

• Der Slug in der URL wird ignoriert – entscheidend ist nur die numerische ID am Ende; das Tool akzeptiert beides.

• Filterformat im Rumpf von /products/search*: Mehrmöglichkeit – ein Array von IDs ({"brand": [675]}), boolesch – als nackter Boolean ({"sale": true}), Preis – als Objekt ({"price": {"lower": 50000}}). {"brand": "675"} und {"spr": [true]} werden stillschweigend ignoriert, {"price": [a, b]} liefert success: false.

• Der Preis wird nach der Größen-SKU gefiltert, nicht nach dem Kartenpreis – ein Produkt kann also mit einem Kartepreis unter der Grenze in den Ergebnissen auftauchen. Deshalb enthält jede Antwort sizePriceRange: {min, max}.

• Die Upstream-Zähler wurden umgenannt: totalAmount → totalMatches, itemsCount → itemsOnPage.

• Segmente (baseCategory) – IDs der Baumknoten: Damen=2, Herren=105, Kinder=188, Lifestyle=366.

• WAF: kyrillische Zeichen im Query müssen percent-encoded werden, sonst 403.

• Kontext: Rohantworten sind riesig (Baum ~1 MB, Marken ~750 KB); standardmäßig wird daher eine kompakte Projektion ausgegeben. verbose: true gibt die unveränderte Antwort zurück.

Testing

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

Der Smoke-Test startet den kompilierten Server als separaten Prozess über stdio und ruft jedes Tool gegen die Live-Website auf – ganz ohne Mocks. Die Parameter werden aus den vorherigen Antworten zu einer Kette verbunden (Marke → Suche → productId → sellerId → Banner), und jeder Aufruf wird inhaltlich geprüft: PRICE_DESC liefert tatsächlich absteigende Preise, conditionIds: [1] nur den Zustand 1, Filter begrenzen die Trefferliste monoton. Der letzte Lauf ist in SMOKE-TEST-OUTPUT.txt festgehalten (23 Aufrufe, 14/14 Tools, 0 Fehlschläge).

CI baut das Projekt auf Node 22/24/26 und führt npm run verify aus. Der Live-Smoke-Test ist in den manuellen Start ausgelagert (Actions → CI → Run workflow → run_smoke_test), um die fremde Website nicht mit den Runner-Surfen zu belasten.

Struktur

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

Mitwirken

PRs sind herzlich willkommen. Vor dem Einreichen: npm run build, npm run verify, node smoke-test.mjs ausführen.

Die größten Schwachstellen, falls die booten sich ändert: die Format __NUXT_DATA__ (bricht mit einem deutlichen Aktualisierung, der darauf hinweist, einen Reviver in src/nuxt.ts zu ergänzen), die Facet-Codes, die Segment-IDs. Rate-Limiting wurde nicht getestet; Timeout 45 s, keine Retries – absichtlich.