mcp-unknowncheatz 0.3.2 → 0.3.4

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
@@ -25,6 +25,74 @@ bun run start
 
 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
 
 | Tool | Purpose |
@@ -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.2",
+  "version": "0.3.4",
   "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,4 +1,4 @@
-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";
@@ -41,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;
@@ -101,14 +101,17 @@ async function launchBrowser(): Promise<BrowserInstance> {
   const executablePath = process.env.UC_CHROME_PATH?.trim();
   const existingProfile = existsSync(PROFILE_DIR);
   mkdirSync(PROFILE_DIR, { recursive: true });
-  const browser = await puppeteer.launch({
-    ...(executablePath ? { executablePath } : { channel: "chrome" as const }),
+  const { browser, page } = await connect({
     headless: useHeadless(),
+    turnstile: true,
     args: onWayland ? ["--ozone-platform=wayland", "--start-maximized"] : ["--start-maximized"],
-    defaultViewport: null,
-    userDataDir: PROFILE_DIR,
+    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");
@@ -143,8 +146,12 @@ function hasCloudflareChallenge(html: string): boolean {
   return CLOUDFLARE_INDICATORS.some((indicator) => html.includes(indicator));
 }
 
-async function waitForChallenge(page: Page, initialHtml: string, deadlineAt?: number): Promise<string> {
-  if (!hasCloudflareChallenge(initialHtml)) return initialHtml;
+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.");
   }
@@ -155,7 +162,7 @@ async function waitForChallenge(page: Page, initialHtml: string, deadlineAt?: nu
     await Bun.sleep(Math.min(1_000, stopAt - Date.now()));
     try {
       const html = await page.content();
-      if (!hasCloudflareChallenge(html)) return html;
+      if (!isPendingPage(html)) return html;
     } catch (error) {
       if (!isDetachedError(error)) throw error;
     }