@bintangtimurlangit/shopee-mcp 0.1.0

package/.env.example

@@ -0,0 +1,25 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Shopee MCP — Environment Variables
+#
+# Unlike a plain scraper, this server drives a real Chromium profile so it can
+# clear Shopee's anti-bot gate. You log in ONCE with `npm run login`; the session
+# is saved to the profile dir below and reused. Everything here is optional.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Shopee regional domain (default: shopee.co.id)
+SHOPEE_DOMAIN=shopee.co.id
+
+# Where the persistent Chromium profile (your saved login) lives.
+# Default: ~/.shopee-mcp/chrome-profile
+# SHOPEE_PROFILE_DIR=/home/you/.shopee-mcp/chrome-profile
+
+# The browser runs HEADED by default because Shopee detects headless — keep it
+# that way. On a server, provide a virtual display via `xvfb-run`. Setting this
+# to "true" is for experiments only and will almost certainly be blocked.
+SHOPEE_HEADLESS=false
+
+# Cache lifetime in milliseconds (default: 30000 = 30s)
+CACHE_TTL_MS=30000
+
+# Set to "true" to log startup/debug info to stderr
+DEBUG=false

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0/). For **how** we version, tag, and publish, see [docs/RELEASES.md](./docs/RELEASES.md).
+
+## [Unreleased]
+
+### Added
+
+- Standardized project scaffolding: `LICENSE` (MIT), `.editorconfig`, ESLint + Prettier, Conventional Commits (commitlint), Husky pre-commit hooks, CI + release workflows, issue/PR templates, and a `docs/` guide set.
+
+## [0.1.0] - 2026-07-12
+
+### Added
+
+- Initial release: MCP server for **exploring Shopee** over stdio, driving a logged-in CloakBrowser session to clear Shopee's anti-bot gate.
+- **2 tools:** `search_products` (keyword search with sorting & pagination) and `get_product_detail` (price, discount, brand, condition, rating, review/sold counts, stock, location, description).
+- In-memory read cache and a persistent browser profile under `~/.shopee-mcp/`.
+
+[Unreleased]: https://github.com/bintangtimurlangit/shopee-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bintangtimurlangit/shopee-mcp/releases/tag/v0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of conduct
+
+We want a respectful, harassment-free environment for everyone.
+
+This project adopts the **[Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)** version **2.1**. See the linked page for the full text.
+
+## Reporting
+
+- For **security-sensitive** issues, follow [SECURITY.md](./SECURITY.md).
+- For **conduct** concerns, contact the maintainers via GitHub (e.g. a direct message if available) or open a discussion/issue as appropriate for the situation.
+
+Unacceptable behavior may result in temporary or permanent exclusion from project spaces.

package/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to shopee-mcp
+
+Thanks for helping improve this MCP server.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) **18+** (see `engines` in `package.json`)
+- Git
+- A display (or `xvfb`) — the server drives a **headed** browser.
+
+## Getting started
+
+```bash
+git clone https://github.com/bintangtimurlangit/shopee-mcp.git
+cd shopee-mcp
+npm install
+npm run build
+npm run login   # one-time: log into Shopee in the CloakBrowser window
+```
+
+More detail: [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md).
+
+## Workflow
+
+1. **Fork** the repository and create a **branch** from `main` (`feat/...`, `fix/...`, etc.).
+2. Make focused changes; match existing **style**, **types**, and **patterns** in the codebase.
+3. **Run checks** before opening a PR:
+
+   ```bash
+   npm run lint
+   npm run format:check
+   npm run typecheck
+   npm run build
+   npm test          # live smoke test (needs a login + a display)
+   ```
+
+4. **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat(tools): ...`, `fix(browser): ...`, `docs: ...`). A `commit-msg` hook enforces this.
+5. Open a **pull request** with a clear description of what changed and why.
+
+## What to contribute
+
+- Bug fixes with steps to reproduce when possible
+- Documentation improvements (`README.md`, `docs/`)
+- Features that fit the project's scope: **public** Shopee discovery via MCP — product search and detail. This is a read-only, discovery-only tool; seller/account features are intentionally out of scope.
+
+## AI-assisted contributions
+
+If a change was produced or heavily guided by an **AI coding agent or assistant**, disclose that in the PR description and **name the model** (e.g. _Claude Opus 4.8_, _GPT-5_).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bintang Timurlangit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# shopee-mcp
+
+[![npm](https://img.shields.io/npm/v/@bintangtimurlangit/shopee-mcp?style=flat-square)](https://www.npmjs.com/package/@bintangtimurlangit/shopee-mcp)
+[![license](https://img.shields.io/github/license/bintangtimurlangit/shopee-mcp?style=flat-square)](./LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/bintangtimurlangit/shopee-mcp/ci.yml?branch=main&style=flat-square)](https://github.com/bintangtimurlangit/shopee-mcp/actions)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-shopee--mcp-24292f?style=flat-square&logo=github)](https://github.com/bintangtimurlangit/shopee-mcp)
+
+An MCP server for **exploring Shopee** — product search and prices — from any MCP client (Claude Desktop, Claude Code, etc.). Discovery only: no seller features.
+
+> **Login required, read-only.** Shopee blocks anonymous requests, so this **unofficial** server reads public data through your own logged-in browser session (see [Why a browser?](#why-a-browser)). It performs no seller or account actions.
+
+**Full reference:** [Documentation](./docs/README.md) · **Changelog:** [CHANGELOG.md](./CHANGELOG.md) · **Versioning & releases:** [docs/RELEASES.md](./docs/RELEASES.md)
+
+## Tools
+
+| Tool                 | What it returns                                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `search_products`    | Keyword search with sorting & pagination — names, prices, sold counts, ratings, seller location, product IDs, URLs.                 |
+| `get_product_detail` | One product — price & discount, brand, condition, category, rating, **review count**, **sold count**, stock, location, description. |
+
+### Tool annotations
+
+Per the [MCP annotations spec](https://modelcontextprotocol.io/) — both tools are read-only, with no side effects.
+
+| Tool                 | Read-only | Idempotent | Destructive |
+| -------------------- | :-------: | :--------: | :---------: |
+| `search_products`    |     ✓     |     ✓      |      –      |
+| `get_product_detail` |     ✓     |     ✓      |      –      |
+
+## Why a browser?
+
+Shopee does **not** expose an open API or server-rendered product HTML. Its `/api/v4/*` endpoints are guarded by an anti-fraud gate (`error 90309999`) that requires per-request signature headers (`af-ac-enc-dat`, `x-sap-sec`, …) minted by Shopee's own obfuscated SDK. Plain `fetch`, headless Chromium, and even a hand-rolled fetch from inside the page all get rejected.
+
+So this server:
+
+1. Drives **[CloakBrowser](https://github.com/CloakHQ/cloakbrowser)** — a Chromium with binary-level fingerprint patches — against a **persistent profile you log into once**.
+2. **Navigates to the real Shopee page and intercepts the response** its own app fetches, so the request carries valid signatures.
+
+The browser must run **headed** (Shopee detects headless); on a server use a virtual display (`xvfb`).
+
+## Setup
+
+```bash
+npm install          # also downloads the CloakBrowser binary (~200 MB, cached)
+npm run build
+```
+
+### 1. Log in once
+
+Shopee blocks anonymous requests, so you sign in one time. This saves a session to `~/.shopee-mcp/chrome-profile`.
+
+```bash
+npm run login        # opens a CloakBrowser window — log in, then press Enter
+```
+
+- On a desktop / WSLg, the window appears normally.
+- Re-run only when the session expires.
+
+### 2. Register with your MCP client
+
+The server launches a **headed** browser, so it needs a display. On a headless machine, wrap it with `xvfb-run`.
+
+Claude Desktop / Claude Code `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "shopee": {
+      "command": "xvfb-run",
+      "args": ["-a", "node", "/absolute/path/to/shopee-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+On a machine with a real display you can drop `xvfb-run` and use `"command": "node"`, `"args": ["…/build/index.js"]` (a browser window will pop up per session).
+
+## Configuration
+
+All optional — see `.env.example`. Copy to `.env` to override.
+
+| Variable             | Default                        | Purpose                              |
+| -------------------- | ------------------------------ | ------------------------------------ |
+| `SHOPEE_DOMAIN`      | `shopee.co.id`                 | Regional Shopee domain.              |
+| `SHOPEE_PROFILE_DIR` | `~/.shopee-mcp/chrome-profile` | Where the saved login lives.         |
+| `SHOPEE_HEADLESS`    | `false`                        | Keep `false` — headless is detected. |
+| `CACHE_TTL_MS`       | `30000`                        | In-memory cache lifetime.            |
+| `DEBUG`              | `false`                        | Log startup/debug info to stderr.    |
+
+## Development
+
+```bash
+npm run lint         # eslint
+npm run format       # prettier --write (format:check to verify)
+npm run typecheck
+npm test             # live smoke test (needs a display; use xvfb-run on servers)
+npm run dev          # tsx watch
+```
+
+More detail: **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)**.
+
+## Troubleshooting
+
+| Symptom                                       | Likely cause / fix                                                                                                      |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `🔒 Not signed in` / anonymous-request errors | No/expired session → run `npm run login`.                                                                               |
+| `error 90309999` or empty results             | Shopee's anti-bot gate rejected the request. Ensure you're logged in and running **headed** (or via `xvfb-run`); retry. |
+| A read returns empty for a valid product      | Shopee lazy-loads; retry, and run with `DEBUG=true` to inspect.                                                         |
+| Empty or stale results right after a change   | In-memory cache — lower `CACHE_TTL_MS` or wait for the TTL to expire.                                                   |
+| Headless / server has no display              | Wrap the command in `xvfb-run -a …`.                                                                                    |
+
+## Caveats
+
+- **Login required.** No session → tools return a friendly "run `npm run login`" prompt.
+- **Anti-bot is a moving target.** The free CloakBrowser binary can go stale as Shopee updates detection; CloakBrowser Pro ships newer patches.
+- Respect Shopee's Terms of Service. This is for personal market exploration, not scraping at scale.
+
+## Contributing & security
+
+[CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [Code of Conduct](./CODE_OF_CONDUCT.md)
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+## Disclaimer
+
+This is an **unofficial** project. It is **not affiliated with, authorized, maintained, sponsored, or endorsed by Shopee or Sea Limited**.
+
+It works by driving a real logged-in browser session against Shopee's web app, which can change without notice — a tool may break when Shopee updates its site or anti-bot behavior. It reads only publicly available product data and performs no account actions.
+
+You are responsible for using this software in compliance with [Shopee's Terms of Service](https://shopee.co.id/docs/terms) and applicable law. Use reasonable request volumes. All product names, logos, and brands are property of their respective owners.

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security
+
+## Supported versions
+
+Security fixes are applied to the **latest release** on the default branch when practical.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for undisclosed security problems.
+
+1. Use [GitHub private vulnerability reporting](https://github.com/bintangtimurlangit/shopee-mcp/security/advisories/new) if it is enabled for this repository, **or**
+2. Contact the maintainers via a private channel (e.g. email on your GitHub profile).
+
+Include:
+
+- A short description of the issue and its impact
+- Steps to reproduce (or a proof-of-concept), if safe to share
+- Affected versions or dependency versions, if known
+
+We aim to acknowledge reports within a few days and coordinate disclosure after a fix is available.
+
+## Scope and credential handling
+
+This is a **local MCP server** that reads **public** Shopee product data through a **logged-in browser session** (Shopee blocks anonymous requests). Be aware:
+
+- Your **session lives on your machine** under `~/.shopee-mcp/chrome-profile` (configurable via `SHOPEE_PROFILE_DIR`). Treat that directory like a password. It is never transmitted anywhere by this server, and the repo **gitignores** local profile/state.
+- The server is **read-only** — it performs product search and detail lookups only; there are no seller or account actions.
+
+Issues in **Shopee's services**, **CloakBrowser**, or **upstream** dependencies (e.g. `@modelcontextprotocol/sdk`, `playwright`) should be reported to those projects when appropriate.

package/build/api/client.d.ts

@@ -0,0 +1,27 @@
+/** Shopee's anti-bot/anti-fraud rejection — almost always means "not logged in / detected". */
+export declare const SHOPEE_ANTIBOT_ERROR = 90309999;
+export declare class ShopeeAPIError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly endpoint?: string | undefined;
+    readonly shopeeError?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, endpoint?: string | undefined, shopeeError?: number | undefined);
+}
+/** Thrown specifically when the anti-bot gate blocks us (needs login / a fresher binary). */
+export declare class ShopeeAuthRequiredError extends ShopeeAPIError {
+    constructor(endpoint?: string);
+}
+/**
+ * Load a Shopee page and capture the JSON that its own app fetches from
+ * `/api/v4/*` — the only way to obtain data past the per-request anti-fraud
+ * signature (a hand-rolled fetch lacks the af-ac-enc-dat / x-sap-sec headers).
+ *
+ * @param pageUrl   the Shopee page to load (its app fires the API call)
+ * @param apiMatch  substring identifying the target /api/v4 response
+ */
+export declare function shopeeCapture<T extends {
+    error?: number;
+    error_msg?: string;
+}>(pageUrl: string, apiMatch: string, timeoutMs?: number): Promise<T>;
+/** Build an absolute Shopee URL from a path. */
+export declare function shopeeUrl(pathAndQuery: string): string;
+//# sourceMappingURL=client.d.ts.map

package/build/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,qBAAa,cAAe,SAAQ,KAAK;aAGrB,UAAU,CAAC,EAAE,MAAM;aACnB,QAAQ,CAAC,EAAE,MAAM;aACjB,WAAW,CAAC,EAAE,MAAM;gBAHpC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC;AAED,6FAA6F;AAC7F,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,QAAQ,CAAC,EAAE,MAAM;CAU9B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAClF,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/build/api/client.js

@@ -0,0 +1,57 @@
+import { captureJson, BASE_URL } from '../browser/session.js';
+/** Shopee's anti-bot/anti-fraud rejection — almost always means "not logged in / detected". */
+export const SHOPEE_ANTIBOT_ERROR = 90309999;
+export class ShopeeAPIError extends Error {
+    statusCode;
+    endpoint;
+    shopeeError;
+    constructor(message, statusCode, endpoint, shopeeError) {
+        super(message);
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.shopeeError = shopeeError;
+        this.name = 'ShopeeAPIError';
+    }
+}
+/** Thrown specifically when the anti-bot gate blocks us (needs login / a fresher binary). */
+export class ShopeeAuthRequiredError extends ShopeeAPIError {
+    constructor(endpoint) {
+        super('Shopee blocked this request with its anti-bot gate. Run `npm run login` (or ' +
+            '`shopee-mcp-login`) once to sign in, then retry.', 200, endpoint, SHOPEE_ANTIBOT_ERROR);
+        this.name = 'ShopeeAuthRequiredError';
+    }
+}
+/**
+ * Load a Shopee page and capture the JSON that its own app fetches from
+ * `/api/v4/*` — the only way to obtain data past the per-request anti-fraud
+ * signature (a hand-rolled fetch lacks the af-ac-enc-dat / x-sap-sec headers).
+ *
+ * @param pageUrl   the Shopee page to load (its app fires the API call)
+ * @param apiMatch  substring identifying the target /api/v4 response
+ */
+export async function shopeeCapture(pageUrl, apiMatch, timeoutMs) {
+    let json;
+    try {
+        json = await captureJson(pageUrl, { apiMatch, timeoutMs });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (/timeout/i.test(msg)) {
+            // No matching response arrived — usually the gate silently dropped it.
+            throw new ShopeeAuthRequiredError(apiMatch);
+        }
+        throw new ShopeeAPIError(`Browser error loading ${apiMatch}: ${msg}`, undefined, apiMatch);
+    }
+    if (json.error === SHOPEE_ANTIBOT_ERROR) {
+        throw new ShopeeAuthRequiredError(apiMatch);
+    }
+    if (json.error !== undefined && json.error !== null && json.error !== 0) {
+        throw new ShopeeAPIError(`Shopee API error ${json.error}${json.error_msg ? `: ${json.error_msg}` : ''} for ${apiMatch}`, 200, apiMatch, json.error);
+    }
+    return json;
+}
+/** Build an absolute Shopee URL from a path. */
+export function shopeeUrl(pathAndQuery) {
+    return `${BASE_URL}${pathAndQuery.startsWith('/') ? '' : '/'}${pathAndQuery}`;
+}
+//# sourceMappingURL=client.js.map

package/build/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE9D,+FAA+F;AAC/F,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGrB;IACA;IACA;IAJlB,YACE,OAAe,EACC,UAAmB,EACnB,QAAiB,EACjB,WAAoB;QAEpC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,eAAU,GAAV,UAAU,CAAS;QACnB,aAAQ,GAAR,QAAQ,CAAS;QACjB,gBAAW,GAAX,WAAW,CAAS;QAGpC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,6FAA6F;AAC7F,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IACzD,YAAY,QAAiB;QAC3B,KAAK,CACH,8EAA8E;YAC5E,kDAAkD,EACpD,GAAG,EACH,QAAQ,EACR,oBAAoB,CACrB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,QAAgB,EAChB,SAAkB;IAElB,IAAI,IAAO,CAAC;IACZ,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,WAAW,CAAI,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,uEAAuE;YACvE,MAAM,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,IAAI,cAAc,CAAC,yBAAyB,QAAQ,KAAK,GAAG,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,KAAK,oBAAoB,EAAE,CAAC;QACxC,MAAM,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,cAAc,CACtB,oBAAoB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,QAAQ,EAAE,EAC9F,GAAG,EACH,QAAQ,EACR,IAAI,CAAC,KAAK,CACX,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,SAAS,CAAC,YAAoB;IAC5C,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,YAAY,EAAE,CAAC;AAChF,CAAC"}

package/build/api/types.d.ts

@@ -0,0 +1,92 @@
+export interface ItemRating {
+    rating_star: number;
+    rating_count: number[];
+}
+export interface ItemBasic {
+    itemid: number;
+    shopid: number;
+    name: string;
+    /** Price in the currency's smallest unit × 100000 (divide by 100000 for IDR). */
+    price: number;
+    price_min: number;
+    price_max: number;
+    price_before_discount: number;
+    currency: string;
+    stock: number;
+    sold: number;
+    historical_sold: number;
+    liked_count: number;
+    discount?: string;
+    item_rating: ItemRating;
+    shop_location: string;
+    is_official_shop: boolean;
+    shopee_verified: boolean;
+    image: string;
+}
+export interface SearchItem {
+    itemid: number;
+    shopid: number;
+    item_basic: ItemBasic;
+}
+export interface SearchItemsResponse {
+    error?: number;
+    total_count: number;
+    nomore: boolean;
+    items: SearchItem[] | null;
+}
+export interface PdpCategory {
+    display_name: string;
+}
+export interface PdpItem {
+    item_id: number;
+    shop_id: number;
+    title: string;
+    brand?: string;
+    /** 1 = new, otherwise used. */
+    condition?: number;
+    currency?: string;
+    item_rating?: {
+        rating_star: number;
+        rating_count: number[];
+    };
+    shop_location?: string;
+    categories?: PdpCategory[];
+    description?: string;
+    image?: string;
+    stock?: number | null;
+    normal_stock?: number | null;
+    historical_sold?: number;
+    global_sold_count?: number;
+    is_free_shipping?: boolean;
+    is_official_shop?: boolean;
+}
+/** A price value: prices are the real amount × 100000. range_* are -1 when single. */
+export interface PdpPriceValue {
+    single_value: number;
+    range_min: number;
+    range_max: number;
+}
+export interface PdpProductPrice {
+    discount?: number;
+    price: PdpPriceValue;
+    price_before_discount?: PdpPriceValue;
+}
+/** /api/v4/pdp/get_pc → data.product_review — where the sold/review counts live. */
+export interface PdpProductReview {
+    total_rating_count?: number;
+    cmt_count?: number;
+    /** Human-formatted sold counts, e.g. "355", "1,2rb". */
+    sold_count_display?: string;
+    historical_sold_display?: string;
+    global_sold_display?: string;
+}
+export interface PdpResponse {
+    error?: number;
+    error_msg?: string;
+    data?: {
+        item: PdpItem;
+        product_price: PdpProductPrice;
+        product_review?: PdpProductReview;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/build/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}

package/build/api/types.js

@@ -0,0 +1,4 @@
+// ─── Search Types ─────────────────────────────────────────────────────────────
+// Shape of Shopee's /api/v4/search/search_items response (subset we use).
+export {};
+//# sourceMappingURL=types.js.map

package/build/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,0EAA0E"}

package/build/browser/session.d.ts

@@ -0,0 +1,30 @@
+import 'dotenv/config';
+import type { BrowserContext } from 'playwright';
+export declare const DOMAIN: string;
+export declare const BASE_URL: string;
+export declare const PROFILE_DIR: string;
+/**
+ * Get the shared browser context, launching it on first use.
+ * `headless` overrides the env default (the login flow forces a visible window).
+ */
+export declare function getContext(headless?: boolean): Promise<BrowserContext>;
+export interface CaptureOptions {
+    /** Substring the target /api/v4 response URL must contain. */
+    apiMatch: string;
+    /** Max time to wait for the matching response (ms). */
+    timeoutMs?: number;
+}
+/**
+ * Navigate to `pageUrl` and return the JSON body of the first `/api/v4/*`
+ * response whose URL contains `apiMatch` — i.e. the request Shopee's own app
+ * fires (carrying the valid anti-fraud signature). Returns the raw parsed JSON;
+ * callers inspect its `error` field.
+ */
+export declare function captureJson<T>(pageUrl: string, opts: CaptureOptions): Promise<T>;
+/** Warm the session once (loads Shopee so the anti-fraud SDK initialises). */
+export declare function warm(): Promise<void>;
+/** Best-effort check that the saved profile is logged in. */
+export declare function isLoggedIn(): Promise<boolean>;
+/** Cleanly close the browser (used on shutdown / after login). */
+export declare function closeContext(): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

package/build/browser/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/browser/session.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,YAAY,CAAC;AAIjE,eAAO,MAAM,MAAM,QAA8C,CAAC;AAClE,eAAO,MAAM,QAAQ,QAAsB,CAAC;AAE5C,eAAO,MAAM,WAAW,QACoE,CAAC;AAwC7F;;;GAGG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAE,OAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGtF;AAqBD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAgBtF;AAED,8EAA8E;AAC9E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAS1C;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAKnD;AAED,kEAAkE;AAClE,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAMlD"}

package/build/browser/session.js

@@ -0,0 +1,109 @@
+import 'dotenv/config';
+import os from 'node:os';
+import path from 'node:path';
+import { launchPersistentContext } from 'cloakbrowser';
+// ─── Configuration ────────────────────────────────────────────────────────────
+export const DOMAIN = process.env.SHOPEE_DOMAIN || 'shopee.co.id';
+export const BASE_URL = `https://${DOMAIN}`;
+export const PROFILE_DIR = process.env.SHOPEE_PROFILE_DIR || path.join(os.homedir(), '.shopee-mcp', 'chrome-profile');
+// Shopee detects headless even with fingerprint patches, so we run HEADED by
+// default (needs a display: WSLg, a desktop X server, or xvfb for servers).
+// Set SHOPEE_HEADLESS=true only to experiment.
+const HEADLESS = process.env.SHOPEE_HEADLESS === 'true';
+const USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+function debug(msg) {
+    if (process.env.DEBUG === 'true')
+        process.stderr.write(`[shopee-mcp] ${msg}\n`);
+}
+// ─── Context singleton ────────────────────────────────────────────────────────
+//
+// Shopee gates product data behind per-request anti-fraud signatures that only
+// its own SDK, running in a non-detected browser, can mint. So we drive
+// CloakBrowser (a fingerprint-patched Chromium) against a persistent profile the
+// user logs into once (npm run login). We never hand-craft the signed request —
+// instead we navigate to the relevant page and intercept the response Shopee's
+// app fires (see captureJson).
+let contextPromise = null;
+async function createContext(headless) {
+    debug(`Launching CloakBrowser (headless=${headless}) with profile: ${PROFILE_DIR}`);
+    const ctx = (await launchPersistentContext({
+        userDataDir: PROFILE_DIR,
+        headless,
+        userAgent: USER_AGENT,
+        locale: 'id-ID',
+        timezone: 'Asia/Jakarta',
+        viewport: { width: 1366, height: 768 },
+        humanize: true,
+        args: ['--no-sandbox', '--disable-dev-shm-usage'],
+    }));
+    return ctx;
+}
+/**
+ * Get the shared browser context, launching it on first use.
+ * `headless` overrides the env default (the login flow forces a visible window).
+ */
+export async function getContext(headless = HEADLESS) {
+    if (!contextPromise)
+        contextPromise = createContext(headless);
+    return contextPromise;
+}
+/** The single reused page. */
+async function getPage() {
+    const ctx = await getContext();
+    const existing = ctx.pages().find((p) => !p.isClosed());
+    return existing ?? (await ctx.newPage());
+}
+// ─── Serialized navigation + interception ──────────────────────────────────────
+//
+// A single page is shared across tool calls; serialize access so overlapping
+// calls don't clobber each other's navigation.
+let lock = Promise.resolve();
+function withLock(fn) {
+    const run = lock.then(fn, fn);
+    lock = run.catch(() => { });
+    return run;
+}
+/**
+ * Navigate to `pageUrl` and return the JSON body of the first `/api/v4/*`
+ * response whose URL contains `apiMatch` — i.e. the request Shopee's own app
+ * fires (carrying the valid anti-fraud signature). Returns the raw parsed JSON;
+ * callers inspect its `error` field.
+ */
+export async function captureJson(pageUrl, opts) {
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    return withLock(async () => {
+        const page = await getPage();
+        const matched = page.waitForResponse((r) => r.url().includes('/api/v4/') && r.url().includes(opts.apiMatch), { timeout: timeoutMs });
+        await page.goto(pageUrl, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+        const resp = await matched;
+        const json = (await resp.json());
+        return json;
+    });
+}
+/** Warm the session once (loads Shopee so the anti-fraud SDK initialises). */
+export async function warm() {
+    await withLock(async () => {
+        const page = await getPage();
+        if (!page.url().includes(DOMAIN)) {
+            debug('Warming session on Shopee homepage…');
+            await page.goto(`${BASE_URL}/`, { waitUntil: 'domcontentloaded', timeout: 45000 });
+            await page.waitForTimeout(3000);
+        }
+    });
+}
+/** Best-effort check that the saved profile is logged in. */
+export async function isLoggedIn() {
+    const ctx = await getContext();
+    const cookies = await ctx.cookies(BASE_URL);
+    // Shopee sets SPC_U (user id) and SPC_EC (encrypted session) once authenticated.
+    return cookies.some((c) => (c.name === 'SPC_U' || c.name === 'SPC_EC') && c.value.length > 4);
+}
+/** Cleanly close the browser (used on shutdown / after login). */
+export async function closeContext() {
+    if (contextPromise) {
+        const ctx = await contextPromise;
+        await ctx.close();
+        contextPromise = null;
+    }
+}
+//# sourceMappingURL=session.js.map