oskelly-mcp

公開カタログ oskelly.ru 用のMCPサーバー。14のツール、すべて匿名の読み取り専用操作で、すべて実サイトで検証済みです。

非公式プロジェクトであり、Oskelly とは提携・関係ありません。登録なしの訪問者と同じものだけを読み取ります。商標は各権利者の所有です。

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)、パスは絶対パスである必要があります:

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

  • spawn node ENOENT on Windows → "node" を where node の出力に置き換え、スラッシュはエスケープしてください。

  • 編集後は、トレイアイコンを含めアプリを完全に再起動してください。

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

• デバッグ — npm run inspector

Tools

フロー: describe_filters → list_brands/category_tree/filter_values → search_products → get_product。

Scope

ログイン、クッキー、カート、お気に入り、メッセージ、注文は存在せず、また存在させることもできません。これはコードの性質です:

• credentials: "omit"、Authorization/Cookie は一切使用しません。

• POST は3つの読み取り専用検索エンドポイントにのみ許可されています — src/client.ts の許可リスト assertReadOnlyPost。

• すべてのツール: readOnlyHint: true、destructiveHint: false。

• スモークテストでは、ツールリストに login/cart/favourite/order/checkout/message/account を含む名前がないことを確認します。

Notes

• 商品カードは __NUXT_DATA__ からパースされます。 単一商品の公開JSONエンドポイントは存在せず (GET /api/v2/products/{id} → 404)、ページはサーバー側で Nuxt 3 によってレンダリングされます。ペイロードは、Nuxt がシリアライズするのと同じ公式パッケージ devalue でデコードされます。カスタム型は標準のリバイバー (src/nuxt.ts) で接続されています。Playwright ではありません: ~150 MB の Chromium と 3〜5 秒かかる代わりに、1回のGETで ~150 ミリ秒です。

• URLのスラッグは無視されます — 末尾の数値IDのみが意味を持ち、ツールは両方を受け付けます。

• フィルター形式 /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: クエリ内のキリル文字はパーセントエンコードされている必要があります。そうでないと 403 になります。

• コンテキスト: 生のレスポンスは巨大なため (ツリー ~1 MB、ブランド ~750 KB)、デフォルトではコンパクトなプロジェクションが返されます。verbose: true で未加工のレスポンスが返ります。

Testing

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

スモークテストは、コンパイル済みサーバーを stdio 経由で別プロセスとして起動し、モックなしで実サイトに対して各ツールを呼び出します。パラメータは前のレスポンスからチェーンされます (ブランド → 検索 → productId → sellerId → バナー)。各呼び出しは意味のある検証を行います: PRICE_DESC が実際に価格の降順を返すこと、conditionIds: [1] が実際に状態1のみを返すこと、フィルタが単調に結果を絞り込むこと。最後の実行結果は SMOKE-TEST-OUTPUT.txt です (23 呼び出し、14/14 ツール、0 失敗)。

CI は Node 22/24/26 でプロジェクトをビルドし、npm run verify を実行します。ライブスモークテストは、ランナーから他人のサイトに負荷をかけないよう、手動実行 (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__ 形式 (src/nuxt.ts に reviver を追加するよう指示する明示的なエラーで失敗します)、ファセットコード、セグメント ID。レート制限はテストされていません。タイムアウトは 45 秒、リトライは意図的に行っていません。