mcp-unknowncheatz 0.3.1 → 0.3.3

package/README.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/9f00f783-0a03-4e8d-b5b6-abd308936f20
 
 ## Install
 
-Install [Bun](https://bun.sh) and Google Chrome. The server uses the maintained `puppeteer-core` package and your installed browser; installation does not download a browser. Set `UC_CHROME_PATH` to an absolute Chrome or Chromium executable path if Chrome is not in its standard location. Run the npm package with:
+Install [Bun](https://bun.sh) and Google Chrome. The server uses `puppeteer-real-browser` and your installed browser; installation does not download a browser. Set `UC_CHROME_PATH` to an absolute Chrome or Chromium executable path if Chrome is not in its standard location. Run the npm package with:
 
 ```sh
 bunx mcp-unknowncheatz
@@ -23,7 +23,75 @@ bun install --frozen-lockfile
 bun run start
 ```
 
-The server uses MCP over standard input and output. Chrome opens when a tool first needs a page. On Linux without a graphical display, it runs headless; set `UC_HEADLESS=1` to request headless mode elsewhere. You can log in with the `login` tool; session cookies are saved locally in `cookies.json`. Browser challenges may require manual interaction in a visible Chrome window.
+The server uses MCP over standard input and output. Chrome opens when a tool first needs a page. It keeps a dedicated profile under the user's application data directory (`mcp-unknowncheat/chrome-profile`) so a manually completed browser challenge and login can survive restarts. Set `UC_PROFILE_DIR` to an absolute path to choose another profile; an existing `cookies.json` is imported only when the profile is first created. On Linux without a graphical display, Chrome runs headless; set `UC_HEADLESS=1` to request headless mode elsewhere. If a Cloudflare challenge appears, complete it in the visible Chrome window. The server waits up to 45 seconds by default (`UC_CF_WAIT_MS`), subject to each tool's time budget. Automated browsers are not guaranteed to pass production challenges. Clients may need a tool timeout over 60 seconds for first-time manual setup.
+
+## Connect an MCP client
+
+Install Bun and Chrome first. Your MCP client starts the server with `bunx mcp-unknowncheatz`; you do not need to leave a separate terminal running. The examples below use the published npm package. To use a source checkout, replace `bunx mcp-unknowncheatz` with `bun run /absolute/path/to/mcp-unknowncheat/src/index.ts`.
+
+### Codex
+
+Add the server from a terminal:
+
+```sh
+codex mcp add unknowncheat -- bunx mcp-unknowncheatz
+codex mcp list
+```
+
+Or add this to `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`):
+
+```toml
+[mcp_servers.unknowncheat]
+command = "bunx"
+args = ["mcp-unknowncheatz"]
+tool_timeout_sec = 120
+```
+
+Restart Codex after editing the config file.
+
+### Claude Code
+
+```sh
+claude mcp add --scope user unknowncheat -- bunx mcp-unknowncheatz
+claude mcp list
+```
+
+Use `--scope project` if the server should be available only in one project.
+
+### Claude Desktop and Cursor
+
+Add the server entry under `mcpServers` in the client's JSON config. Claude Desktop uses `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS. Cursor uses `~/.cursor/mcp.json` for all projects or `.cursor/mcp.json` in one project.
+
+```json
+{
+  "mcpServers": {
+    "unknowncheat": {
+      "command": "bunx",
+      "args": ["mcp-unknowncheatz"]
+    }
+  }
+}
+```
+
+Merge this entry into an existing `mcpServers` object if you already have other servers. Quit and reopen the client after saving the file.
+
+### VS Code
+
+Add this to `.vscode/mcp.json` in your workspace, then run **MCP: List Servers** from the Command Palette to start or inspect it:
+
+```json
+{
+  "servers": {
+    "unknowncheat": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["mcp-unknowncheatz"]
+    }
+  }
+}
+```
+
+For other clients, configure a local stdio MCP server with command `bunx` and argument `mcp-unknowncheatz`. If the client cannot find `bunx`, use its absolute executable path. On first use, allow time for the package to start and for any browser challenge; where supported, set a tool timeout of at least 120 seconds. Ask the client to list its MCP tools or call `check_login` to confirm the connection.
 
 ## Tools
 
@@ -78,7 +146,7 @@ The HTML inspector reads a saved page locally and reports selector counts, parse
 
 | Variable | Default | Purpose |
 |---|---:|---|
-| `UC_CF_WAIT_MS` | `15000` | Time to wait for a Cloudflare challenge, in milliseconds |
+| `UC_CF_WAIT_MS` | `45000` | Time to wait for a Cloudflare challenge, in milliseconds |
 | `UC_CACHE_TTL_MS` | `300000` | HTML cache lifetime, in milliseconds |
 | `UC_MIN_REQUEST_INTERVAL_MS` | `900` | Minimum interval between crawl requests, in milliseconds |
 | `UC_INDEX_PATH` | User application data directory | Path of the local SQLite search index |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-unknowncheatz",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "MCP server for searching and reading the UnknownCheats forum",
   "bin": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
     "cheerio": "^1.2.0",
-    "puppeteer-core": "25.12.0",
+    "puppeteer-real-browser": "1.4.4",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/browser.ts

@@ -1,18 +1,28 @@
-import puppeteer, { type Browser, type Page } from "puppeteer-core";
+import { connect } from "puppeteer-real-browser";
+import { existsSync, mkdirSync } from "node:fs";
+import os from "node:os";
 import path from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const COOKIES_PATH = path.join(__dirname, "..", "cookies.json");
+const DATA_DIR = process.platform === "win32"
+  ? path.join(process.env.LOCALAPPDATA ?? os.homedir(), "mcp-unknowncheat")
+  : path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share"), "mcp-unknowncheat");
+const PROFILE_DIR = process.env.UC_PROFILE_DIR ?? path.join(DATA_DIR, "chrome-profile");
 const CLOUDFLARE_INDICATORS = ["Just a moment", "cf-browser-verification", "Checking your browser"];
 const NAV_TIMEOUT = 30_000;
 const NAV_TIMEOUT_RETRY = 60_000;
-const CF_WAIT_MS = Number(process.env.UC_CF_WAIT_MS ?? 15_000);
+const CF_WAIT_MS = Number(process.env.UC_CF_WAIT_MS ?? 45_000);
 
 function useRealDisplay(): boolean {
   return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }
 
+function useHeadless(): boolean {
+  return process.env.UC_HEADLESS === "1" || (process.platform !== "win32" && !useRealDisplay());
+}
+
 const ALLOWED_HOSTS = new Set(["www.unknowncheats.me", "unknowncheats.me"]);
 
 export function validateUrl(url: string): void {
@@ -31,8 +41,8 @@ export function validateUrl(url: string): void {
 }
 
 type BrowserInstance = {
-  browser: Browser;
-  page: Page;
+  browser: Awaited<ReturnType<typeof connect>>["browser"];
+  page: Awaited<ReturnType<typeof connect>>["page"];
 };
 
 let instance: BrowserInstance | null = null;
@@ -89,20 +99,26 @@ async function launchBrowser(): Promise<BrowserInstance> {
   console.error("[browser] Launching Chrome...");
   const onWayland = process.env.XDG_SESSION_TYPE === "wayland" || !!process.env.WAYLAND_DISPLAY;
   const executablePath = process.env.UC_CHROME_PATH?.trim();
-  const browser = await puppeteer.launch({
-    ...(executablePath ? { executablePath } : { channel: "chrome" as const }),
-    headless: process.env.UC_HEADLESS === "1" || (process.platform !== "win32" && !useRealDisplay()),
+  const existingProfile = existsSync(PROFILE_DIR);
+  mkdirSync(PROFILE_DIR, { recursive: true });
+  const { browser, page } = await connect({
+    headless: useHeadless(),
+    turnstile: true,
     args: onWayland ? ["--ozone-platform=wayland", "--start-maximized"] : ["--start-maximized"],
-    defaultViewport: null,
+    customConfig: {
+      ...(executablePath ? { chromePath: executablePath } : {}),
+      userDataDir: PROFILE_DIR,
+    },
+    connectOption: { defaultViewport: null },
+    disableXvfb: useRealDisplay(),
   });
-  const page = await browser.newPage();
 
   browser.on("disconnected", () => {
     console.error("[browser] Browser disconnected");
     instance = null;
   });
 
-  await loadCookies(page);
+  if (!existingProfile) await loadCookies(page);
   return { browser, page };
 }
 
@@ -130,6 +146,30 @@ function hasCloudflareChallenge(html: string): boolean {
   return CLOUDFLARE_INDICATORS.some((indicator) => html.includes(indicator));
 }
 
+function isPendingPage(html: string): boolean {
+  return html.length < 200 || hasCloudflareChallenge(html);
+}
+
+async function waitForChallenge(page: BrowserInstance["page"], initialHtml: string, deadlineAt?: number): Promise<string> {
+  if (!isPendingPage(initialHtml)) return initialHtml;
+  if (useHeadless()) {
+    throw new Error("CloudflareBlockError: A challenge appeared in headless Chrome. Use visible Chrome to complete it manually.");
+  }
+  const waitMs = Number.isFinite(CF_WAIT_MS) ? Math.max(0, CF_WAIT_MS) : 45_000;
+  const stopAt = Math.min(Date.now() + waitMs, deadlineAt ?? Infinity);
+  console.error(`[browser] Cloudflare challenge: complete it in the visible Chrome window (up to ${Math.ceil((stopAt - Date.now()) / 1000)} seconds).`);
+  while (Date.now() < stopAt) {
+    await Bun.sleep(Math.min(1_000, stopAt - Date.now()));
+    try {
+      const html = await page.content();
+      if (!isPendingPage(html)) return html;
+    } catch (error) {
+      if (!isDetachedError(error)) throw error;
+    }
+  }
+  throw new Error("CloudflareBlockError: Challenge stayed open in Chrome. Complete it manually or use forum-supported access; this server cannot guarantee automated clearance.");
+}
+
 function isDetachedError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   const msg = err.message;
@@ -159,21 +199,11 @@ export async function navigateWithRetry(url: string, deadlineAt?: number): Promi
     return Math.max(1, Math.min(maximum, left));
   };
 
-  const attempt = async (timeout: number, waitUntil: "networkidle2" | "domcontentloaded" = "networkidle2"): Promise<string> => {
+  const attempt = async (timeout: number, waitUntil: "networkidle2" | "domcontentloaded" = "domcontentloaded"): Promise<string> => {
     await page.goto(url, { waitUntil, timeout: remaining(timeout) });
 
-    let html = await page.content();
-
-    if (hasCloudflareChallenge(html)) {
-      console.error("[browser] Cloudflare challenge detected, waiting", CF_WAIT_MS, "ms...");
-      await new Promise((res) => setTimeout(res, remaining(CF_WAIT_MS)));
-      remaining(1);
-      html = await page.content();
-
-      if (hasCloudflareChallenge(html)) {
-        throw new Error("CloudflareBlockError: Challenge did not resolve after waiting");
-      }
-    }
+    const html = await waitForChallenge(page, await page.content(), deadlineAt);
+    remaining(1);
 
     await saveCookies(page);
     return html;