oskelly-mcp

MCP 服务器，用于公开目录 oskelly.ru。14 个工具， 仅支持匿名只读操作，全部已在真实站点上验证。

非官方项目，与 Oskelly 无关联。它读取的内容与任何未注册访客看到的完全一致。 商标归其各自所有者所有。

许可证

MIT

Related MCP server: VkusVill MCP Server

安装

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"] } } }

  • 在 Windows 上出现 spawn node ENOENT → 请将 "node" 替换为 where node 的输出，斜杠需要转义。

  • 修改后请完全重启应用程序，包括托盘图标。

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

• 调试 — npm run inspector

工具

流程：describe_filters → list_brands/category_tree/filter_values → search_products → get_product。

范围

没有也不可能会有登录、Cookie、购物车、收藏、消息、订单。这是代码的固有特性：

• credentials: "omit"，没有任何 Authorization/Cookie。

• POST 只允许用于三个只读搜索端点——src/client.ts 中的允许列表 assertReadOnlyPost。

• 所有工具：readOnlyHint: true，destructiveHint: false。

• Smoke 测试检查工具列表中没有包含 login/cart/favourite/order/checkout/message/account 的名称。

备注

• 商品卡片从 __NUXT_DATA__ 解析。 单个商品没有公开的 JSON 端点（GET /api/v2/products/{id} → 404），页面由 Nuxt 3 在服务器端渲染。Payload 由官方包 devalue 解码——与 Nuxt 序列化它所用的库相同；自定义类型通过标准 revivers（src/nuxt.ts）接入。不是 Playwright：约 150 MB Chromium 和 3–5 秒，而一次 GET 仅约 150 ms。

• URL 中的 slug 会被忽略——只有末尾的数字 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： query 中的西里尔字符必须进行百分号编码，否则返回 403。

• 上下文： 原始响应非常庞大（树约 1 MB，品牌约 750 KB），因此默认返回紧凑的投影；verbose: true 返回未修改的原始响应。

测试

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

Smoke 测试以独立进程通过 stdio 启动编译后的服务器，并针对真实站点调用每个工具——不使用 mock。参数根据前一个响应链式构建（品牌 → 搜索 → productId → sellerId → 横幅），每次调用都会经过有意义的校验：PRICE_DESC 确实产生降序价格，conditionIds: [1] 确实只返回状态 1，筛选条件单调地缩小结果集。最近一次运行见 SMOKE-TEST-OUTPUT.txt（23 次调用，14/14 个工具，0 失败）。

CI 在 Node 22/24/26 上构建项目并运行 npm run verify。真实的 smoke 测试被放到手动运行（Actions → CI → Run workflow → run_smoke_test），以免从 runner 上频繁访问他人网站。

结构

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

贡献

欢迎提交 PR。提交前请运行 npm run build、npm run verify、node smoke-test.mjs。

如果 oskelly 更新，最容易出问题的地方：__NUXT_DATA__ 格式（会以一个明确错误崩溃，提示在 src/nuxt.ts 中添加 reviver）、分面代码、区段 id。速率限制未测试；超时 45 秒，没有重试——这是有意为之。