mcp-unknowncheatz 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amaralkaff
+
+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,70 @@
+# mcp-unknowncheat
+
+A TypeScript MCP server for reading and searching the [UnknownCheats](https://www.unknowncheats.me) forum. It uses Bun, a local Chrome window, and Cheerio to parse forum pages.
+
+## Install
+
+Install [Bun](https://bun.sh) and Chrome or Chromium. Run the npm package with:
+
+```sh
+bunx mcp-unknowncheatz
+```
+
+To run the source:
+
+```sh
+git clone https://github.com/amangly/mcp-unknowncheat.git
+cd mcp-unknowncheat
+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. You can log in with the `login` tool; session cookies are saved locally in `cookies.json`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `check_login` | Check session status |
+| `login` | Log in with a username and password |
+| `search_forum` | Search threads or browse a subforum |
+| `get_thread` | Read posts and pages in a thread |
+| `extract_code` | Extract code blocks from a thread |
+| `download_file` | Download and inspect an attachment |
+| `list_subforums` | List forum sections from a 24-hour local directory; use `refresh: true` to rebuild it |
+| `crawl_subforum` | Collect threads from subforum pages |
+| `bulk_get_threads` | Read several threads |
+| `get_user_reputation` | Read reputation details |
+| `find_latest_offsets` | Find a game's offsets thread in the forum and scan recent pages backward |
+| `debug_page` | Inspect page structure |
+| `crawl_cache` | Inspect or clear the HTML cache |
+
+The MCP tool schemas provide the available arguments. For example:
+
+```text
+search_forum({ query: "example" })
+get_thread({ url: "https://www.unknowncheats.me/forum/showthread.php?t=123" })
+find_latest_offsets({ game: "Apex Legends" })
+```
+
+The first directory lookup saves forum URLs in `forum-index.json`. Offsets lookups read the selected game's live thread listing, choose a linked candidate, and scan its recent pages from newest to oldest. Results include the listing URL, scanned pages, and source post. A matching post does not prove the offsets work with the current game build. If the game name is ambiguous, use a slug returned by `list_subforums` or pass an exact `thread_url`.
+
+## Development
+
+```sh
+bun run typecheck
+bun run test
+bun run build
+```
+
+The browser code and tools are in `src/`; HTML parsers are in `src/parsers/`. `downloads/`, `exports/`, `cookies.json`, and `forum-index.json` are local output ignored by Git.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `UC_CF_WAIT_MS` | `15000` | 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 |
+
+The npm package is [mcp-unknowncheatz](https://www.npmjs.com/package/mcp-unknowncheatz). Report bugs in [GitHub Issues](https://github.com/amangly/mcp-unknowncheat/issues).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mcp-unknowncheatz",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "MCP server for searching and reading the UnknownCheats forum",
+  "bin": {
+    "mcp-unknowncheatz": "src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "unknowncheats",
+    "puppeteer",
+    "cloudflare",
+    "scraper",
+    "ai"
+  ],
+  "author": "amangly",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amangly/mcp-unknowncheat.git"
+  },
+  "homepage": "https://github.com/amangly/mcp-unknowncheat",
+  "bugs": {
+    "url": "https://github.com/amangly/mcp-unknowncheat/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "build": "bun build src/index.ts --target=bun --outdir=dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "cheerio": "^1.2.0",
+    "puppeteer-real-browser": "^1.4.4",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,6 @@
+import { load } from "cheerio";
+
+export function isLoggedIn(html: string): boolean {
+  const $ = load(html);
+  return $('a[href*="login.php?do=logout"]').length > 0;
+}

package/src/browser.ts

@@ -0,0 +1,182 @@
+import { connect } from "puppeteer-real-browser";
+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 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);
+
+function useRealDisplay(): boolean {
+  return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}
+
+const ALLOWED_HOSTS = new Set(["www.unknowncheats.me", "unknowncheats.me"]);
+
+export function validateUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`Blocked URL scheme: ${parsed.protocol} — only http/https allowed`);
+  }
+  if (!ALLOWED_HOSTS.has(parsed.hostname)) {
+    throw new Error(`Blocked URL host: ${parsed.hostname} — only unknowncheats.me is allowed`);
+  }
+}
+
+type BrowserInstance = {
+  browser: Awaited<ReturnType<typeof connect>>["browser"];
+  page: Awaited<ReturnType<typeof connect>>["page"];
+};
+
+let instance: BrowserInstance | null = null;
+
+async function loadCookies(page: BrowserInstance["page"]): Promise<void> {
+  try {
+    const file = Bun.file(COOKIES_PATH);
+    if (await file.exists()) {
+      const cookies = await file.json();
+      if (Array.isArray(cookies) && cookies.length > 0) {
+        await page.setCookie(...cookies);
+        console.error("[browser] Loaded cookies from", COOKIES_PATH);
+      }
+    }
+  } catch (err) {
+    console.error("[browser] Cookie load failed (starting fresh):", err);
+  }
+}
+
+async function saveCookies(page: BrowserInstance["page"]): Promise<void> {
+  try {
+    const cookies = await page.cookies();
+    await Bun.write(COOKIES_PATH, JSON.stringify(cookies, null, 2));
+  } catch (err) {
+    console.error("[browser] Cookie save failed:", err);
+  }
+}
+
+async function launchBrowser(): Promise<BrowserInstance> {
+  console.error("[browser] Launching Chrome...");
+  const onWayland = process.env.XDG_SESSION_TYPE === "wayland" || !!process.env.WAYLAND_DISPLAY;
+  const { browser, page } = await connect({
+    headless: false,
+    turnstile: true,
+    args: onWayland ? ["--ozone-platform=wayland", "--start-maximized"] : ["--start-maximized"],
+    customConfig: {},
+    connectOption: {
+      defaultViewport: null,
+    },
+    disableXvfb: useRealDisplay(),
+  });
+
+  browser.on("disconnected", () => {
+    console.error("[browser] Browser disconnected");
+    instance = null;
+  });
+
+  await loadCookies(page);
+  return { browser, page };
+}
+
+export async function getPage(): Promise<BrowserInstance["page"]> {
+  if (!instance) {
+    instance = await launchBrowser();
+  }
+  return instance.page;
+}
+
+export async function ensureFreshBrowser(): Promise<BrowserInstance["page"]> {
+  if (instance) {
+    try {
+      await instance.browser.close();
+    } catch {
+      // ignore — may already be dead
+    }
+    instance = null;
+  }
+  instance = await launchBrowser();
+  return instance.page;
+}
+
+function hasCloudflareChallenge(html: string): boolean {
+  return CLOUDFLARE_INDICATORS.some((indicator) => html.includes(indicator));
+}
+
+function isDetachedError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message;
+  return (
+    msg.includes("Detached Frame") ||
+    msg.includes("Execution context was destroyed") ||
+    msg.includes("Target closed") ||
+    msg.includes("Session closed")
+  );
+}
+
+function isNavigationAbortError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return err.message.includes("ERR_ABORTED") || err.message.includes("Navigation failed");
+}
+
+export async function navigateWithRetry(url: string): Promise<{ page: BrowserInstance["page"]; html: string }> {
+  validateUrl(url);
+  let page = await getPage();
+  let navRetried = false;
+  let detachedRetried = false;
+
+  const attempt = async (timeout: number, waitUntil: "networkidle2" | "domcontentloaded" = "networkidle2"): Promise<string> => {
+    await page.goto(url, { waitUntil, 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, CF_WAIT_MS));
+      html = await page.content();
+
+      if (hasCloudflareChallenge(html)) {
+        throw new Error("CloudflareBlockError: Challenge did not resolve after waiting");
+      }
+    }
+
+    await saveCookies(page);
+    return html;
+  };
+
+  try {
+    const html = await attempt(NAV_TIMEOUT);
+    return { page, html };
+  } catch (err) {
+    if (isNavigationAbortError(err) && !navRetried) {
+      console.error("[browser] Navigation aborted (often ads), retrying with domcontentloaded...");
+      navRetried = true;
+      const html = await attempt(NAV_TIMEOUT_RETRY, "domcontentloaded");
+      return { page, html };
+    }
+    if (isDetachedError(err) && !detachedRetried) {
+      console.error("[browser] Detached frame error, relaunching browser and retrying...");
+      detachedRetried = true;
+      page = await ensureFreshBrowser();
+      const html = await attempt(NAV_TIMEOUT_RETRY);
+      return { page, html };
+    }
+    throw err;
+  }
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (instance) {
+    try {
+      await instance.browser.close();
+    } catch {
+      // ignore
+    }
+    instance = null;
+  }
+}

package/src/crawl.ts

@@ -0,0 +1,62 @@
+import { navigateWithRetry, validateUrl } from "./browser.js";
+
+const CACHE_TTL_MS = Number(process.env.UC_CACHE_TTL_MS ?? 5 * 60_000);
+const MIN_REQUEST_INTERVAL_MS = Number(process.env.UC_MIN_REQUEST_INTERVAL_MS ?? 900);
+const CACHE_MAX_ENTRIES = 128;
+
+interface CacheEntry {
+  html: string;
+  timestamp: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+let lastRequestAt = 0;
+
+function evictIfNeeded(): void {
+  if (cache.size <= CACHE_MAX_ENTRIES) return;
+  const oldestKey = cache.keys().next().value;
+  if (oldestKey !== undefined) cache.delete(oldestKey);
+}
+
+async function throttle(): Promise<void> {
+  const now = Date.now();
+  const elapsed = now - lastRequestAt;
+  if (elapsed < MIN_REQUEST_INTERVAL_MS) {
+    await new Promise((r) => setTimeout(r, MIN_REQUEST_INTERVAL_MS - elapsed));
+  }
+  lastRequestAt = Date.now();
+}
+
+export interface FetchOptions {
+  bypassCache?: boolean;
+  cacheOverrideTtlMs?: number;
+}
+
+export async function fetchHtml(url: string, opts: FetchOptions = {}): Promise<string> {
+  validateUrl(url);
+  const ttl = opts.cacheOverrideTtlMs ?? CACHE_TTL_MS;
+
+  if (!opts.bypassCache) {
+    const cached = cache.get(url);
+    if (cached && Date.now() - cached.timestamp < ttl) {
+      console.error(`[crawl] Cache hit: ${url}`);
+      return cached.html;
+    }
+  }
+
+  await throttle();
+  const { html } = await navigateWithRetry(url);
+  cache.set(url, { html, timestamp: Date.now() });
+  evictIfNeeded();
+  return html;
+}
+
+export function clearCache(): number {
+  const size = cache.size;
+  cache.clear();
+  return size;
+}
+
+export function getCacheStats(): { entries: number; ttlMs: number; minIntervalMs: number } {
+  return { entries: cache.size, ttlMs: CACHE_TTL_MS, minIntervalMs: MIN_REQUEST_INTERVAL_MS };
+}

package/src/forum-catalog.ts

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSubforums, type Subforum } from "./parsers/subforums.js";
+
+export const FORUM_INDEX = "https://www.unknowncheats.me/forum/index.php";
+const CATALOG_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "forum-index.json");
+const CATALOG_TTL_MS = 24 * 60 * 60_000;
+
+export interface ForumCatalog {
+  source: string;
+  indexedAt: string;
+  subforums: Subforum[];
+}
+
+export async function readForumCatalog(): Promise<ForumCatalog | null> {
+  try {
+    const catalog: ForumCatalog = await Bun.file(CATALOG_PATH).json();
+    const age = Date.now() - Date.parse(catalog.indexedAt);
+    if (catalog.source !== FORUM_INDEX || !Number.isFinite(age) || age < 0 || age > CATALOG_TTL_MS ||
+        !Array.isArray(catalog.subforums) || !catalog.subforums.every((item) =>
+          typeof item.slug === "string" && typeof item.label === "string" && typeof item.url === "string")) {
+      return null;
+    }
+    return catalog;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveForumCatalog(html: string): Promise<ForumCatalog> {
+  const subforums = parseSubforums(html);
+  if (subforums.length === 0) throw new Error("Forum index contained no subforums");
+  const catalog = { source: FORUM_INDEX, indexedAt: new Date().toISOString(), subforums };
+  await Bun.write(CATALOG_PATH, JSON.stringify(catalog, null, 2));
+  return catalog;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { closeBrowser } from "./browser.js";
+import packageJson from "../package.json" with { type: "json" };
+import { registerCheckLogin } from "./tools/check-login.js";
+import { registerLogin } from "./tools/login.js";
+import { registerSearchForum } from "./tools/search-forum.js";
+import { registerGetThread } from "./tools/get-thread.js";
+import { registerExtractCode } from "./tools/extract-code.js";
+import { registerDebugPage } from "./tools/debug-page.js";
+import { registerDownloadFile } from "./tools/download-file.js";
+import { registerListSubforums } from "./tools/list-subforums.js";
+import { registerCrawlSubforum } from "./tools/crawl-subforum.js";
+import { registerBulkGetThreads } from "./tools/bulk-get-threads.js";
+import { registerCacheControl } from "./tools/cache-control.js";
+import { registerGetUserReputation } from "./tools/get-user-reputation.js";
+import { registerFindLatestOffsets } from "./tools/find-latest-offsets.js";
+
+const server = new McpServer(
+  { name: "mcp-unknowncheat", version: packageJson.version },
+  { instructions: "For the newest offsets for any game, call find_latest_offsets with the game name. It discovers the game forum and offset thread from live listings, then scans recent posts backward. Report the source post and scan coverage. Do not present a found post as a verified current game offset." }
+);
+
+// Register all tools
+registerCheckLogin(server);
+registerLogin(server);
+registerSearchForum(server);
+registerGetThread(server);
+registerExtractCode(server);
+registerDebugPage(server);
+registerDownloadFile(server);
+registerListSubforums(server);
+registerCrawlSubforum(server);
+registerBulkGetThreads(server);
+registerCacheControl(server);
+registerGetUserReputation(server);
+registerFindLatestOffsets(server);
+
+// Graceful shutdown
+async function shutdown() {
+  console.error("[server] Shutting down...");
+  await closeBrowser();
+  process.exit(0);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+// Connect stdio transport (IMPORTANT: never write to stdout except via MCP)
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+console.error("[server] mcp-unknowncheat started");

package/src/offset-discovery.ts

@@ -0,0 +1,60 @@
+import type { Subforum } from "./parsers/subforums.js";
+import type { ThreadListEntry } from "./parsers/thread-list.js";
+import type { ThreadPost } from "./types.js";
+
+export function normalizeName(value: string): string {
+  return value.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+export function rankGameForums(game: string, forums: Subforum[]): Subforum[] {
+  const query = normalizeName(game);
+  if (!query) return [];
+  const terms = query.split(" ");
+  return forums
+    .map((forum) => {
+      const label = normalizeName(forum.label);
+      const slug = normalizeName(forum.slug);
+      const score = label === query || slug === query
+        ? 100
+        : label.startsWith(`${query} `) || slug.startsWith(`${query} `)
+          ? 50
+          : terms.every((term) => label.split(" ").includes(term) || slug.split(" ").includes(term))
+            ? 10
+            : 0;
+      return { forum, score };
+    })
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score || a.forum.label.length - b.forum.label.length)
+    .map(({ forum }) => forum);
+}
+
+export type OffsetThread = ThreadListEntry & { listingPage: string; score: number };
+
+export function rankOffsetThreads(threads: ThreadListEntry[], listingPage: string): OffsetThread[] {
+  return threads
+    .map((thread) => {
+      const title = thread.title.toLowerCase();
+      const score = (/\boffsets?\b/.test(title) ? 5 : 0) +
+        (/\breversal\b/.test(title) ? 4 : 0) +
+        (/\bstructs?\b/.test(title) ? 2 : 0) +
+        (/\b(?:sigs?|signatures?)\b/.test(title) ? 2 : 0);
+      return { ...thread, listingPage, score };
+    })
+    .filter(({ score }) => score >= 4)
+    .sort((a, b) => b.score - a.score || b.replies - a.replies);
+}
+
+export function containsOffsetUpdate(post: ThreadPost): boolean {
+  const firstValue = post.content.search(/\b0x[0-9a-f]{3,}\b/i);
+  const firstLink = post.content.search(/https:\/\/(?:www\.)?(?:pastebin\.com|pastes\.dev)\//i);
+  const evidenceAt = [firstValue, firstLink].filter((index) => index >= 0).sort((a, b) => a - b)[0] ?? 200;
+  const introduction = post.content.slice(0, Math.min(evidenceAt, 200));
+  if (/\?|\b(?:anyone|looking for|need|requesting)\b/i.test(introduction)) {
+    return false;
+  }
+  const terms = /\b(offsets?|signatures?|sigs?|dump|patch)\b/i;
+  const pasteLink = post.links.some(({ url }) => /^https:\/\/(?:www\.)?(?:pastebin\.com|pastes\.dev)\//i.test(url));
+  const hexAssignments = post.content.match(/=\s*0x[0-9a-f]{3,}\b/gi)?.length ?? 0;
+  return (pasteLink && terms.test(post.content)) ||
+    (hexAssignments >= 3 && /\boffsets?\s*[:{]|\bconstexpr\b|\b(?:OFF_|dw[A-Z]|m_)/i.test(post.content));
+}

package/src/parsers/code-blocks.ts

@@ -0,0 +1,59 @@
+import { load } from "cheerio";
+import type { CodeBlock } from "../types.js";
+
+const CPP_PATTERNS = [/#include\s*[<"]/, /\bstd::/, /\bnullptr\b/, /\bcout\b/, /\bcin\b/, /\bvoid\s+\w+\s*\(/, /\bconstexpr\b/, /\bDWORD\b/, /\buint64_t\b/, /\buint32_t\b/, /#define\s+\w+/, /\bULONG\b/, /\bINT64\b/];
+const CSHARP_PATTERNS = [/\busing\s+System\b/, /\bnamespace\s+\w+/, /\bpublic\s+class\b/, /Console\.Write/];
+const PYTHON_PATTERNS = [/\bdef\s+\w+\s*\(/, /\bimport\s+\w+/, /\bprint\s*\(/, /\bself\./, /\b__init__\b/];
+const LUA_PATTERNS = [/\bfunction\s+\w+\s*\(/, /\blocal\s+\w+/, /\brequire\s*\(/, /\bend\b/];
+
+function detectLanguage(code: string, cssClass?: string): string {
+  if (cssClass) {
+    const cls = cssClass.toLowerCase();
+    if (cls.includes("cpp") || cls.includes("c++")) return "cpp";
+    if (cls.includes("csharp") || cls.includes("c#")) return "csharp";
+    if (cls.includes("python") || cls.includes("py")) return "python";
+    if (cls.includes("lua")) return "lua";
+  }
+
+  const score = (patterns: RegExp[]) => patterns.filter((p) => p.test(code)).length;
+
+  const scores: [string, number][] = [
+    ["cpp", score(CPP_PATTERNS)],
+    ["csharp", score(CSHARP_PATTERNS)],
+    ["python", score(PYTHON_PATTERNS)],
+    ["lua", score(LUA_PATTERNS)],
+  ];
+
+  const best = scores.reduce((a, b) => (b[1] > a[1] ? b : a));
+  return best[1] > 0 ? best[0] : "unknown";
+}
+
+export function parseCodeBlocks(html: string): CodeBlock[] {
+  const $ = load(html);
+  const blocks: CodeBlock[] = [];
+  const seen = new Set<string>();
+
+  // vBulletin highlight blocks, pre, and code tags
+  $(".highlight, pre, code").each((_, el) => {
+    const element = $(el);
+    const code = element.text().trim();
+
+    if (!code || code.length < 10 || seen.has(code)) return;
+    seen.add(code);
+
+    const cssClass = element.attr("class") ?? "";
+    const language = detectLanguage(code, cssClass);
+
+    // Grab surrounding context (previous sibling text, up to 100 chars)
+    const contextEl = element.prev();
+    const context = contextEl.length ? contextEl.text().trim().slice(0, 100) : undefined;
+
+    // Find ancestor post ID (vBulletin: table[id^='post'])
+    const postAncestor = element.closest("table[id]").filter((_, el) => /^post\d+$/.test($(el).attr("id") ?? ""));
+    const postId = postAncestor.length ? postAncestor.attr("id") : undefined;
+
+    blocks.push({ code, language, context, postId });
+  });
+
+  return blocks;
+}