@bintangtimurlangit/shopee-mcp 0.1.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,52 @@
+# Development
+
+## Scripts
+
+| Command             | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| `npm install`       | Install dependencies (also fetches the CloakBrowser binary) |
+| `npm run login`     | One-time: open a browser window and log into Shopee         |
+| `npm run build`     | Compile TypeScript to `build/` (`tsc`)                      |
+| `npm run dev`       | Watch mode: `tsx watch src/index.ts`                        |
+| `npm run start`     | Run compiled server: `node build/index.js`                  |
+| `npm run lint`      | ESLint over the repo                                        |
+| `npm run format`    | Prettier write; `npm run format:check` to verify            |
+| `npm run typecheck` | `tsc --noEmit`, strict, with unused-symbol checks           |
+| `npm test`          | **Live smoke test** — needs a login and a display           |
+
+## Project layout
+
+```
+src/
+  index.ts          # MCP server entry; registers tools
+  login.ts          # one-time interactive login (npm run login)
+  api/
+    client.ts       # navigates the real page and intercepts the app's response
+    types.ts        # shared types
+  browser/
+    session.ts      # CloakBrowser persistent-profile session
+  tools/
+    search.ts       # search_products
+    product.ts      # get_product_detail
+  utils/
+    cache.ts        # in-memory TTL cache
+    errors.ts       # error wrapper / friendly messages
+test/
+  smoke.ts          # the npm test health check
+```
+
+## Why a browser is required
+
+Shopee does **not** expose an open API or server-rendered product HTML. Its `/api/v4/*` endpoints are guarded by an anti-fraud gate that requires per-request signature headers minted by Shopee's own obfuscated SDK. Plain `fetch`, headless Chromium, and hand-rolled in-page fetches are all rejected.
+
+So this server drives **[CloakBrowser](https://github.com/CloakHQ/cloakbrowser)** (a fingerprint-patched Chromium) against a persistent profile you log into once, **navigates to the real Shopee page, and intercepts the response** its own app fetches — so the request carries valid signatures. The browser runs **headed** (Shopee detects headless); on a server use `xvfb`.
+
+## Build output
+
+`npm run build` emits JavaScript under **`build/`**. The repo **gitignores** `build/`; CI and `prepublishOnly` run `npm run build`.
+
+## Tech stack
+
+- TypeScript, **strict** (with `noUnusedLocals` / `noUnusedParameters`)
+- Zod for MCP tool input validation
+- `@modelcontextprotocol/sdk` (stdio), CloakBrowser + Playwright

package/docs/README.md

@@ -0,0 +1,14 @@
+# shopee-mcp documentation
+
+**shopee-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io/) server for **public discovery** on Shopee — product search and detail through a logged-in browser session — over **stdio**, for Claude Code, Claude Desktop, Cursor, and other MCP hosts. Discovery only; no seller features.
+
+| Document                            | Description                                                                                                    |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [Configuration](./CONFIGURATION.md) | Env vars, `mcpServers` JSON, `xvfb` for headless machines, per-client setup                                    |
+| [Development](./DEVELOPMENT.md)     | Scripts, build, login, the live smoke test, why a browser is required                                          |
+| [Releases](./RELEASES.md)           | SemVer, npm tags, git tags, publishing, [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
+| [Changelog](../CHANGELOG.md)        | Version history ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/))                                     |
+
+**Installation** is in the [root README](../README.md#installation).
+
+**Community, security, license:** [CONTRIBUTING.md](../CONTRIBUTING.md) · [SECURITY.md](../SECURITY.md) · [Code of Conduct](../CODE_OF_CONDUCT.md) · [MIT License](../LICENSE)

package/docs/RELEASES.md

@@ -0,0 +1,46 @@
+# Releases and versioning
+
+This project uses **Semantic Versioning** ([SemVer 2.0](https://semver.org/)) for the **npm package**. The canonical version string is **`package.json`** → `version`.
+
+Commit messages follow **[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)** (`feat:`, `fix:`, `docs:`, `chore:`, …). That pairs with SemVer: `fix` → PATCH, `feat` → MINOR, breaking changes → MAJOR.
+
+## Version format
+
+`MAJOR.MINOR.PATCH` — e.g. `0.1.0`, `1.2.3`.
+
+- **MAJOR** — Breaking changes (removed/renamed tools, incompatible env or behavior).
+- **MINOR** — Backward-compatible features (new tools, new optional config).
+- **PATCH** — Bug fixes and safe corrections that do not change the public contract.
+
+## npm dist-tags
+
+| Tag      | Typical use                                                          |
+| -------- | -------------------------------------------------------------------- |
+| `latest` | Default stable install: `npm install @bintangtimurlangit/shopee-mcp` |
+| `beta`   | Optional prereleases: `npm publish --tag beta` with `X.Y.Z-beta.N`   |
+
+Scoped packages use **`"publishConfig": { "access": "public" }`**.
+
+## Publishing (maintainers)
+
+Releases are **automated** by the [`release` workflow](../.github/workflows/release.yml): pushing a `vX.Y.Z` tag runs typecheck + build and publishes to npm (with [provenance](https://docs.npmjs.com/generating-provenance-statements)), then creates a GitHub release.
+
+**One-time setup:** add an npm **automation token** as the repo secret **`NPM_TOKEN`**. Without it, the workflow still builds but skips publish.
+
+**To cut a release:**
+
+1. Bump **`version`** in **`package.json`** per SemVer.
+2. Update **`CHANGELOG.md`**: move items from **`[Unreleased]`** into **`[X.Y.Z] - YYYY-MM-DD`**.
+3. Commit with Conventional Commits, e.g. `chore(release): v0.1.1`.
+4. Tag and push:
+
+   ```bash
+   git tag v0.1.1
+   git push origin main --tags
+   ```
+
+5. The workflow publishes to npm and opens the GitHub release.
+
+## Git tags
+
+Tag stable releases as **`vX.Y.Z`**; prereleases **`vX.Y.Z-beta.N`**.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@bintangtimurlangit/shopee-mcp",
+  "version": "0.1.0",
+  "description": "An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bintangtimurlangit/shopee-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bintangtimurlangit/shopee-mcp/issues"
+  },
+  "homepage": "https://github.com/bintangtimurlangit/shopee-mcp#readme",
+  "bin": {
+    "shopee-mcp": "build/index.js",
+    "shopee-mcp-login": "build/login.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "login": "tsx src/login.ts",
+    "dev": "tsx watch src/index.ts",
+    "start": "node build/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "tsx test/smoke.ts",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "lint-staged": {
+    "*.{ts,js,json,md,yml,yaml}": "prettier --write",
+    "*.ts": "eslint --fix"
+  },
+  "files": [
+    "build",
+    ".env.example",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "shopee",
+    "indonesia",
+    "ecommerce",
+    "marketplace",
+    "product-search",
+    "discovery"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cloakbrowser": "^0.4.10",
+    "dotenv": "^17.4.2",
+    "playwright": "^1.49.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.1",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.3.0",
+    "prettier": "^3.4.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.19.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}