oskelly-mcp

oskelly.ru 공개 카탈로그용 MCP 서버. 14개 도구, 익명 read-only 작업만, 모두 실사이트에서 검증됨.

비공식 프로젝트이며 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.

범위

로그인, 쿠키, 장바구니, 찜, 메시지, 주문은 없고 앞으로도 없을 것입니다. 이는 코드 속성입니다:

• credentials: "omit", Authorization/Cookie 헤더 없음.

• POST는 read-only 검색 엔드포인트 3개에만 허용 — src/client.ts의 allow-list assertReadOnlyPost.

• 모든 도구: readOnlyHint: true, destructiveHint: false.

• 스모크 테스트는 도구 목록에 login/cart/favourite/order/checkout/message/account 이름이 없는지 확인합니다.

참고 사항

• 상품 카드는 __NUXT_DATA__에서 파싱됩니다. 단일 상품용 공개 JSON 엔드포인트는 없습니다 (GET /api/v2/products/{id} → 404), 페이지는 서버에서 Nuxt 3로 렌더링됩니다. Payload는 공식 패키지 devalue로 디코딩됩니다 — Nuxt가 직렬화에 사용하는 것과 동일한 라이브러리입니다. 커스텀 타입은 표준 reviver를 통해 연결됩니다 (src/nuxt.ts). Playwright가 아닙니다: ~150MB Chromium과 3–5초 대신 GET 한 번에 ~150ms.

• URL의 슬러그는 무시됩니다 — tool은 끝의 숫자 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: 쿼리의 키릴 문자는 percent-encoding이 필수이며, 그렇지 않으면 403.

• 컨텍스트: 원시 응답은 거대합니다 (트리 ~1MB, 브랜드 ~750KB), 따라서 기본적으로 컴팩트 프로젝션이 반환됩니다. verbose: true는 원본 응답을 반환합니다.

테스트

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), 러너에서 타사 사이트에 부하를 주지 않기 위해서입니다.

구조

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. Rate-limiting은 테스트되지 않았습니다; 타임아웃 45초, 재시도 없음 — 의도적입니다.