mcp-unknowncheatz 0.3.0 → 0.3.2

package/src/inspect-html.ts

@@ -0,0 +1,31 @@
+import { load } from "cheerio";
+import { parsePaginationInfo, parseThreadList } from "./parsers/thread-list.js";
+import { parseSubforums } from "./parsers/subforums.js";
+import { parseThread } from "./parsers/thread.js";
+
+export function inspectForumHtml(html: string) {
+  const $ = load(html);
+  const listing = parseThreadList(html);
+  const thread = parseThread(html, "https://www.unknowncheats.me/forum/showthread.php?t=0");
+  const subforums = parseSubforums(html);
+  const title = $("title").first().text().trim();
+  return {
+    title,
+    challengeDetected: /Just a moment|cf-browser-verification|Checking your browser/i.test(html),
+    likelyPage: thread.posts.length > 0 ? "thread" : listing.length > 0 ? "listing" : subforums.length > 0 ? "forum_index" : "unrecognized",
+    selectors: {
+      subforumLinks: $("a[href*='/forum/']").length,
+      threadTitleLinks: $("a[id^='thread_title_']").length,
+      postTables: $("table[id^='post']").length,
+      postMessages: $("div[id^='post_message_']").length,
+      pagination: $(".pagenav").length,
+    },
+    parsed: {
+      subforums: subforums.length,
+      threads: listing.length,
+      posts: thread.posts.length,
+      listingPages: parsePaginationInfo(html).totalPages,
+      threadPages: thread.totalPages,
+    },
+  };
+}

package/src/offset-discovery.ts

@@ -6,9 +6,31 @@ export function normalizeName(value: string): string {
   return value.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
 }
 
+const GAME_FORUM_ALIASES: Record<string, string> = {
+  pubg: "playerunknown-s-battlegrounds",
+  "playerunknowns battlegrounds": "playerunknown-s-battlegrounds",
+  cs2: "counter-strike-2-a",
+  "counter strike 2": "counter-strike-2-a",
+  csgo: "counterstrike-global-offensive",
+};
+
+export function preferredForumSlug(queryText: string): string | undefined {
+  const query = normalizeName(queryText);
+  if (query.includes("pubg mobile")) return undefined;
+  return Object.entries(GAME_FORUM_ALIASES)
+    .sort(([a], [b]) => b.length - a.length)
+    .find(([name]) => query === name || query.startsWith(`${name} `) ||
+      query.endsWith(` ${name}`) || query.includes(` ${name} `))?.[1];
+}
+
 export function rankGameForums(game: string, forums: Subforum[]): Subforum[] {
   const query = normalizeName(game);
   if (!query) return [];
+  const alias = preferredForumSlug(game);
+  if (alias) {
+    const exact = forums.find((forum) => forum.slug === alias);
+    if (exact) return [exact];
+  }
   const terms = query.split(" ");
   return forums
     .map((forum) => {

package/src/search-fallback.ts

@@ -1,5 +1,6 @@
 import { load } from "cheerio";
 import { filterThreads, parseThreadList, type ThreadListEntry } from "./parsers/thread-list.js";
+import { preferredForumSlug } from "./offset-discovery.js";
 
 function discoverSubforumSlugs(html: string): Array<{ slug: string; label: string }> {
   const $ = load(html);
@@ -26,11 +27,13 @@ function rankSubforums(
 ): Array<{ slug: string; label: string; score: number }> {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
   const slugGuess = query.trim().toLowerCase().replace(/\s+/g, "-");
+  const preferredSlug = preferredForumSlug(query);
 
   const ranked = subforums.map((entry) => {
     const haystack = `${entry.slug} ${entry.label}`.toLowerCase();
     let score = terms.filter((term) => haystack.includes(term)).length;
     if (entry.slug === slugGuess) score += 10;
+    if (entry.slug === preferredSlug) score += 20;
     if (entry.slug.includes(slugGuess) || slugGuess.includes(entry.slug)) score += 3;
     return { ...entry, score };
   });
@@ -40,10 +43,10 @@ function rankSubforums(
 
 export async function searchViaSubforums(
   query: string,
-  fetchHtml: (url: string) => Promise<string>
+  fetchHtml: (url: string) => Promise<string>,
+  knownSubforums?: Array<{ slug: string; label: string }>,
 ): Promise<{ results: ThreadListEntry[]; scannedSubforums: string[] }> {
-  const indexHtml = await fetchHtml("https://www.unknowncheats.me/forum/index.php");
-  const subforums = discoverSubforumSlugs(indexHtml);
+  const subforums = knownSubforums ?? discoverSubforumSlugs(await fetchHtml("https://www.unknowncheats.me/forum/index.php"));
   const ranked = rankSubforums(subforums, query);
 
   const candidates = ranked.length > 0

package/src/sync-index.ts

@@ -0,0 +1,113 @@
+import { fetchHtml } from "./crawl.js";
+import { validateUrl } from "./browser.js";
+import { ForumIndex } from "./forum-index.js";
+import { parsePaginationInfo, parseThreadList, type ThreadListEntry } from "./parsers/thread-list.js";
+import { parseThread } from "./parsers/thread.js";
+import type { ThreadPost } from "./types.js";
+
+export interface SyncResult {
+  subforum: string;
+  listingPages: number[];
+  threadsSeen: number;
+  threadsUpdated: number;
+  threadsSkipped: number;
+  postPagesFetched: number;
+  timeBudgetReached: boolean;
+  coverage: "first_and_recent_pages";
+  errors: Array<{ url: string; message: string }>;
+}
+
+function listingUrl(slug: string, page: number): string {
+  const base = `https://www.unknowncheats.me/forum/${slug}/`;
+  return page === 1 ? base : `${base}index${page}.html`;
+}
+
+function threadPageUrl(url: string, page: number): string {
+  const target = new URL(url);
+  target.searchParams.set("page", String(page));
+  return target.toString();
+}
+
+export async function syncSubforumIndex(
+  index: ForumIndex,
+  slug: string,
+  options: { maxListingPages: number; maxThreads: number; recentPages: number; maxPostAgeMs?: number; deadlineAt?: number },
+  fetcher: (url: string) => Promise<string> = fetchHtml,
+): Promise<SyncResult> {
+  if (!/^[a-z0-9][a-z0-9-]{1,80}$/.test(slug)) throw new Error("Invalid subforum slug");
+  const result: SyncResult = {
+    subforum: slug, listingPages: [], threadsSeen: 0, threadsUpdated: 0,
+    threadsSkipped: 0, postPagesFetched: 0, timeBudgetReached: false,
+    coverage: "first_and_recent_pages", errors: [],
+  };
+  const seen = new Map<string, ThreadListEntry>();
+
+  for (let page = 1; page <= options.maxListingPages; page++) {
+    if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) {
+      result.timeBudgetReached = true;
+      break;
+    }
+    const url = listingUrl(slug, page);
+    try {
+      const html = await fetcher(url);
+      const entries = parseThreadList(html);
+      if (entries.length === 0) throw new Error("No thread links parsed");
+      const validEntries = entries.filter((entry) => {
+        try {
+          validateUrl(entry.url);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+      if (validEntries.length === 0) throw new Error("No allowed thread URLs parsed");
+      index.recordListing(slug, page, validEntries);
+      for (const entry of validEntries) seen.set(entry.threadId, entry);
+      result.listingPages.push(page);
+      if (page >= parsePaginationInfo(html).totalPages) break;
+    } catch (error) {
+      if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) result.timeBudgetReached = true;
+      result.errors.push({ url, message: error instanceof Error ? error.message : String(error) });
+      break;
+    }
+  }
+
+  result.threadsSeen = seen.size;
+  let attempted = 0;
+  for (const entry of seen.values()) {
+    if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) {
+      result.timeBudgetReached = true;
+      break;
+    }
+    if (attempted >= options.maxThreads) break;
+    if (!index.needsPosts(entry.threadId, options.maxPostAgeMs)) {
+      result.threadsSkipped++;
+      continue;
+    }
+    attempted++;
+    try {
+      const firstHtml = await fetcher(entry.url);
+      const first = parseThread(firstHtml, entry.url, 1);
+      if (first.posts.length === 0) throw new Error("No posts parsed from first page");
+      const pages: Array<{ page: number; posts: ThreadPost[] }> = [{ page: 1, posts: first.posts }];
+      const start = Math.max(2, first.totalPages - options.recentPages + 1);
+      for (let page = start; page <= first.totalPages; page++) {
+        if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) {
+          result.timeBudgetReached = true;
+          throw new Error("Time budget reached before all sampled post pages were fetched");
+        }
+        const url = threadPageUrl(entry.url, page);
+        const parsed = parseThread(await fetcher(url), url, page);
+        if (parsed.posts.length === 0) throw new Error(`No posts parsed from page ${page}`);
+        pages.push({ page, posts: parsed.posts });
+      }
+      index.upsertPosts(entry.threadId, pages);
+      result.threadsUpdated++;
+      result.postPagesFetched += pages.length;
+    } catch (error) {
+      if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) result.timeBudgetReached = true;
+      result.errors.push({ url: entry.url, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return result;
+}

package/src/tools/bulk-get-threads.ts

@@ -1,9 +1,11 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetchHtml } from "../crawl.js";
 import { parseThread } from "../parsers/thread.js";
 import { parseCodeBlocks } from "../parsers/code-blocks.js";
 import { validateUrl } from "../browser.js";
+import { getForumIndex } from "../forum-index.js";
 import type { ThreadPost } from "../types.js";
 import type { AuthorReputation } from "../parsers/reputation.js";
 
@@ -130,18 +132,27 @@ export function registerBulkGetThreads(server: McpServer): void {
       min_op_rep,
       exclude_negative_op,
       min_op_trust,
-    }) => {
+    }) => withBrowserSession(async () => {
       const results: unknown[] = [];
       const skipped: Array<{ url: string; reason: string; opAuthor?: string; opReputation?: AuthorReputation }> = [];
       let successCount = 0;
       let errorCount = 0;
+      let processed = 0;
+      let timeBudgetReached = false;
+      const deadlineAt = Date.now() + 45_000;
 
       for (const url of urls) {
+        if (Date.now() >= deadlineAt) {
+          timeBudgetReached = true;
+          break;
+        }
+        processed++;
         try {
           validateUrl(url);
 
-          const firstHtml = await fetchHtml(url);
+          const firstHtml = await fetchHtml(url, { deadlineAt });
           const first = parseThread(firstHtml, url, 1);
+          getForumIndex().recordThreadPage(first, 1);
           const opPost = first.posts[0];
           const opRep = opPost?.reputation ?? null;
 
@@ -181,13 +192,19 @@ export function registerBulkGetThreads(server: McpServer): void {
           if (fetch_all_pages && first.totalPages > 1) {
             const limit = Math.min(first.totalPages, MAX_PAGES_PER_THREAD);
             for (let pageNum = 2; pageNum <= limit; pageNum++) {
+              if (Date.now() >= deadlineAt) {
+                timeBudgetReached = true;
+                break;
+              }
               const pageUrl = buildPageUrl(url, pageNum);
               try {
-                const pageHtml = await fetchHtml(pageUrl);
+                const pageHtml = await fetchHtml(pageUrl, { deadlineAt });
                 const parsed = parseThread(pageHtml, pageUrl, pageNum);
+                getForumIndex().recordThreadPage(parsed, pageNum);
                 allPosts.push(...parsed.posts);
                 pagesFetched.push(pageNum);
               } catch (pageErr) {
+                if (Date.now() >= deadlineAt) timeBudgetReached = true;
                 console.error(`[bulk] Page ${pageNum} of ${url} failed:`, pageErr);
                 break;
               }
@@ -262,6 +279,7 @@ export function registerBulkGetThreads(server: McpServer): void {
           results.push(threadResult);
           successCount++;
         } catch (err) {
+          if (Date.now() >= deadlineAt) timeBudgetReached = true;
           const message = err instanceof Error ? err.message : String(err);
           results.push({ url, error: message });
           errorCount++;
@@ -276,6 +294,8 @@ export function registerBulkGetThreads(server: McpServer): void {
               requested: urls.length,
               succeeded: successCount,
               failed: errorCount,
+              timeBudgetReached,
+              remainingUrls: urls.slice(processed),
               skipped: skipped.length,
               skippedDetail: skipped,
               threads: results,
@@ -283,6 +303,6 @@ export function registerBulkGetThreads(server: McpServer): void {
           },
         ],
       };
-    }
+    })
   );
 }

package/src/tools/check-login.ts

@@ -1,3 +1,4 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { load } from "cheerio";
 import { navigateWithRetry } from "../browser.js";
@@ -6,7 +7,7 @@ import { isLoggedIn } from "../auth.js";
 const UC_HOME = "https://www.unknowncheats.me/forum/";
 
 export function registerCheckLogin(server: McpServer): void {
-  server.tool("check_login", "Check if the browser session is logged into UnknownCheats", {}, async () => {
+  server.tool("check_login", "Check if the browser session is logged into UnknownCheats", {}, async () => withBrowserSession(async () => {
     try {
       const { html } = await navigateWithRetry(UC_HOME);
       const $ = load(html);
@@ -37,5 +38,5 @@ export function registerCheckLogin(server: McpServer): void {
         isError: true,
       };
     }
-  });
+  }));
 }

package/src/tools/crawl-subforum.ts

@@ -1,6 +1,8 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetchHtml } from "../crawl.js";
+import { getForumIndex } from "../forum-index.js";
 import {
   filterThreads,
   parsePaginationInfo,
@@ -43,19 +45,26 @@ export function registerCrawlSubforum(server: McpServer): void {
         .describe("Sort the collected results locally"),
       limit: z.number().int().min(1).max(500).optional().default(100).describe("Max threads returned after filtering/sorting"),
     },
-    async ({ subforum, max_pages, query, min_replies, min_views, author, prefix, include_sticky, sort_by, limit }) => {
+    async ({ subforum, max_pages, query, min_replies, min_views, author, prefix, include_sticky, sort_by, limit }) => withBrowserSession(async () => {
       try {
+        const deadlineAt = Date.now() + 45_000;
+        let timeBudgetReached = false;
         const pagesWalked: number[] = [];
         const collected: ThreadListEntry[] = [];
         const seen = new Set<string>();
         let totalPagesAvailable = 1;
 
         for (let page = 1; page <= max_pages; page++) {
+          if (Date.now() >= deadlineAt) {
+            timeBudgetReached = true;
+            break;
+          }
           const url = buildPageUrl(subforum, page);
           let html: string;
           try {
-            html = await fetchHtml(url);
+            html = await fetchHtml(url, { deadlineAt });
           } catch (err) {
+            if (Date.now() >= deadlineAt) timeBudgetReached = true;
             const message = err instanceof Error ? err.message : String(err);
             console.error(`[crawl-subforum] Failed page ${page}: ${message}`);
             break;
@@ -66,6 +75,7 @@ export function registerCrawlSubforum(server: McpServer): void {
           pagesWalked.push(page);
 
           const threads = parseThreadList(html);
+          if (threads.length > 0) getForumIndex().recordListing(subforum, page, threads);
           for (const thread of threads) {
             if (seen.has(thread.url)) continue;
             seen.add(thread.url);
@@ -98,6 +108,7 @@ export function registerCrawlSubforum(server: McpServer): void {
               text: JSON.stringify({
                 subforum,
                 pagesWalked,
+                timeBudgetReached,
                 totalPagesAvailable,
                 collected: collected.length,
                 matched: filtered.length,
@@ -123,6 +134,6 @@ export function registerCrawlSubforum(server: McpServer): void {
           isError: true,
         };
       }
-    }
+    })
   );
 }

package/src/tools/debug-page.ts

@@ -1,3 +1,4 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { load } from "cheerio";
@@ -11,7 +12,7 @@ export function registerDebugPage(server: McpServer): void {
       url: z.string().url().describe("URL to inspect"),
       selector: z.string().optional().describe("CSS selector to extract (returns matched outerHTML)"),
     },
-    async ({ url, selector }) => {
+    async ({ url, selector }) => withBrowserSession(async () => {
       try {
         const { html } = await navigateWithRetry(url);
         const $ = load(html);
@@ -97,6 +98,6 @@ export function registerDebugPage(server: McpServer): void {
           isError: true,
         };
       }
-    }
+    })
   );
 }

package/src/tools/download-file.ts

@@ -1,3 +1,4 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { getPage, navigateWithRetry, validateUrl } from "../browser.js";
@@ -148,7 +149,7 @@ export function registerDownloadFile(server: McpServer): void {
         .default(true)
         .describe("If true, reads and returns text file contents for analysis (default true)"),
     },
-    async ({ url, analyze }) => {
+    async ({ url, analyze }) => withBrowserSession(async () => {
       try {
         validateUrl(url);
         await mkdir(DOWNLOADS_DIR, { recursive: true });
@@ -401,6 +402,6 @@ export function registerDownloadFile(server: McpServer): void {
           isError: true,
         };
       }
-    }
+    })
   );
 }

package/src/tools/extract-code.ts

@@ -1,3 +1,4 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetchHtml } from "../crawl.js";
@@ -29,7 +30,7 @@ export function registerExtractCode(server: McpServer): void {
         .default(false)
         .describe("If true, exports ALL code blocks to a JSON file instead of returning them inline. Recommended when a page has many code blocks."),
     },
-    async ({ url, limit, export_to_file }) => {
+    async ({ url, limit, export_to_file }) => withBrowserSession(async () => {
       try {
         const html = await fetchHtml(url);
         const all = parseCodeBlocks(html);
@@ -103,6 +104,6 @@ export function registerExtractCode(server: McpServer): void {
           isError: true,
         };
       }
-    }
+    })
   );
 }

package/src/tools/find-latest-offsets.ts

@@ -1,3 +1,4 @@
+import { withBrowserSession } from "../browser.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { navigateWithRetry, validateUrl } from "../browser.js";
@@ -6,6 +7,7 @@ import type { Subforum } from "../parsers/subforums.js";
 import { parseThreadList, parsePaginationInfo } from "../parsers/thread-list.js";
 import { parseThread } from "../parsers/thread.js";
 import { containsOffsetUpdate, normalizeName, rankGameForums, rankOffsetThreads, type OffsetThread } from "../offset-discovery.js";
+import { getForumIndex } from "../forum-index.js";
 
 const MAX_LISTING_PAGES = 10;
 const MAX_THREAD_PAGES = 50;
@@ -17,27 +19,28 @@ function withPage(url: string, page: number): string {
   return target.toString();
 }
 
-async function readPage(page: ForumPage, url: string): Promise<{ page: ForumPage; html: string }> {
+async function readPage(page: ForumPage, url: string, deadlineAt: number): Promise<{ page: ForumPage; html: string }> {
   validateUrl(url);
+  if (Date.now() >= deadlineAt) throw new Error("Offsets lookup time budget exhausted");
   try {
-    const response = await page.evaluate(async (target) => {
-      const result = await fetch(target, { credentials: "include", signal: AbortSignal.timeout(8_000) });
+    const response = await page.evaluate(async ({ target, timeoutMs }) => {
+      const result = await fetch(target, { credentials: "include", signal: AbortSignal.timeout(timeoutMs) });
       return { ok: result.ok, url: result.url, html: await result.text() };
-    }, url);
+    }, { target: url, timeoutMs: Math.max(1, Math.min(8_000, deadlineAt - Date.now())) });
     validateUrl(response.url);
     if (!response.ok || /Just a moment|cf-browser-verification|Checking your browser/i.test(response.html)) {
       throw new Error("Forum returned a challenge or an error");
     }
     return { page, html: response.html };
   } catch {
-    return navigateWithRetry(url);
+    return navigateWithRetry(url, deadlineAt);
   }
 }
 
 export function registerFindLatestOffsets(server: McpServer): void {
   server.tool(
     "find_latest_offsets",
-    "Discover a game's offsets thread from live UnknownCheats forum listings, then scan from its last page backward for the newest matching post.",
+    "Use when asked for the newest game offsets on UnknownCheats. Discover the game's offsets thread from live listings, then scan from its last page backward for the newest matching post; this does not verify the offsets against a game build.",
     {
       game: z.string().min(1).describe("Game name, such as Apex Legends or PUBG"),
       subforum_slug: z.string().optional().describe("Exact subforum slug from list_subforums when needed"),
@@ -45,10 +48,12 @@ export function registerFindLatestOffsets(server: McpServer): void {
       max_listing_pages: z.number().int().min(1).max(MAX_LISTING_PAGES).optional().default(5).describe("Maximum game-forum listing pages to inspect"),
       max_thread_pages: z.number().int().min(1).max(MAX_THREAD_PAGES).optional().default(20).describe("Maximum recent thread pages to inspect"),
     },
-    async ({ game, subforum_slug, thread_url, max_listing_pages, max_thread_pages }) => {
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    async ({ game, subforum_slug, thread_url, max_listing_pages, max_thread_pages }) => withBrowserSession(async () => {
+      const deadlineAt = Date.now() + 45_000;
       try {
         if (thread_url) validateUrl(thread_url);
-        const entry = thread_url ? await navigateWithRetry(thread_url) : null;
+        const entry = thread_url ? await navigateWithRetry(thread_url, deadlineAt) : null;
         let browserPage: ForumPage | null = entry?.page ?? null;
         let catalog: ForumCatalog | null = null;
         let fromCache = false;
@@ -64,7 +69,7 @@ export function registerFindLatestOffsets(server: McpServer): void {
           catalog = await readForumCatalog();
           fromCache = catalog !== null;
           if (!catalog) {
-            const index = await navigateWithRetry(FORUM_INDEX);
+            const index = await navigateWithRetry(FORUM_INDEX, deadlineAt);
             browserPage = index.page;
             catalog = await saveForumCatalog(index.html);
           }
@@ -72,7 +77,7 @@ export function registerFindLatestOffsets(server: McpServer): void {
           forumChoices = rankGameForums(game, forums);
           forum = subforum_slug ? forums.find((item) => item.slug === subforum_slug) ?? null : forumChoices[0] ?? null;
           if (!forum && fromCache) {
-            const index = await navigateWithRetry(FORUM_INDEX);
+            const index = await navigateWithRetry(FORUM_INDEX, deadlineAt);
             browserPage = index.page;
             catalog = await saveForumCatalog(index.html);
             fromCache = false;
@@ -96,12 +101,14 @@ export function registerFindLatestOffsets(server: McpServer): void {
           }
 
           for (let number = 1; number <= max_listing_pages; number++) {
+            if (Date.now() >= deadlineAt) break;
             const url = number === 1 ? forum.url : `${forum.url}index${number}.html`;
-            const response = browserPage ? await readPage(browserPage, url) : await navigateWithRetry(url);
+            const response = browserPage ? await readPage(browserPage, url, deadlineAt) : await navigateWithRetry(url, deadlineAt);
             browserPage = response.page;
             listingPagesScanned.push(url);
             const threads = parseThreadList(response.html);
             if (threads.length === 0) throw new Error(`No thread list parsed from ${url}`);
+            getForumIndex().recordListing(forum.slug, number, threads);
             candidates.push(...rankOffsetThreads(threads, url));
             if (candidates.length > 0 || number >= parsePaginationInfo(response.html).totalPages) break;
           }
@@ -112,7 +119,7 @@ export function registerFindLatestOffsets(server: McpServer): void {
           const selected = candidates[0];
           if (!selected) {
             return { content: [{ type: "text", text: JSON.stringify({
-              found: false, reason: "offset_thread_not_found_in_scanned_listings", game, forum,
+              found: false, reason: Date.now() >= deadlineAt ? "time_budget_reached" : "offset_thread_not_found_in_scanned_listings", game, forum,
               forumIndex: { url: FORUM_INDEX, indexedAt: catalog.indexedAt, fromCache }, listingPagesScanned,
             }) }] };
           }
@@ -121,7 +128,7 @@ export function registerFindLatestOffsets(server: McpServer): void {
           discoveredAt = selected.listingPage;
         }
 
-        const first = entry ?? await readPage(browserPage!, selectedUrl);
+        const first = entry ?? await readPage(browserPage!, selectedUrl, deadlineAt);
         browserPage = first.page;
         const thread = parseThread(first.html, selectedUrl);
         selectedTitle ??= thread.title;
@@ -130,11 +137,14 @@ export function registerFindLatestOffsets(server: McpServer): void {
         const oldestPage = Math.max(1, thread.totalPages - max_thread_pages + 1);
 
         for (let number = thread.totalPages; number >= oldestPage; number--) {
+          if (Date.now() >= deadlineAt) break;
           const url = withPage(selectedUrl, number);
-          const response: { page: ForumPage; html: string } = number === 1 && thread.totalPages === 1 ? first : await readPage(browserPage!, url);
+          const response: { page: ForumPage; html: string } = number === 1 && thread.totalPages === 1 ? first : await readPage(browserPage!, url, deadlineAt);
           browserPage = response.page;
-          const posts = parseThread(response.html, url, number).posts;
+          const parsed = parseThread(response.html, url, number);
+          const posts = parsed.posts;
           if (posts.length === 0) throw new Error(`No posts parsed from ${url}`);
+          getForumIndex().recordThreadPage(parsed, number);
           pagesScanned.push(number);
           const match = posts.reverse().find(containsOffsetUpdate);
           if (match) {
@@ -152,7 +162,7 @@ export function registerFindLatestOffsets(server: McpServer): void {
         }
 
         return { content: [{ type: "text", text: JSON.stringify({
-          found: false, reason: "no_offset_update_in_scanned_pages", game, forum,
+          found: false, reason: Date.now() >= deadlineAt ? "time_budget_reached" : "no_offset_update_in_scanned_pages", game, forum,
           forumIndex: catalog ? { url: FORUM_INDEX, indexedAt: catalog.indexedAt, fromCache } : undefined,
           thread: { title: selectedTitle, url: selectedUrl, discoveredAt }, candidateThreads: candidates,
           listingPagesScanned, totalThreadPages: thread.totalPages, pagesScanned,
@@ -160,8 +170,14 @@ export function registerFindLatestOffsets(server: McpServer): void {
         }) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        if (Date.now() >= deadlineAt) {
+          return { content: [{ type: "text", text: JSON.stringify({
+            found: false, reason: "time_budget_reached", game, thread_url,
+            checkedAt: new Date().toISOString(), error: message,
+          }) }] };
+        }
         return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
       }
-    }
+    })
   );
 }

package/src/tools/forum-index.ts

@@ -0,0 +1,66 @@
+import { withBrowserSession } from "../browser.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getForumIndex } from "../forum-index.js";
+import { fetchHtml } from "../crawl.js";
+import { syncSubforumIndex } from "../sync-index.js";
+
+export function registerForumIndex(server: McpServer): void {
+  server.tool(
+    "index_subforum",
+    "Incrementally index a bounded subforum listing and the first/recent pages of changed threads.",
+    {
+      subforum: z.string().describe("Exact slug from list_subforums"),
+      max_listing_pages: z.number().int().min(1).max(5).optional().default(1),
+      max_threads: z.number().int().min(0).max(20).optional().default(5),
+      recent_pages: z.number().int().min(1).max(3).optional().default(1),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    async ({ subforum, max_listing_pages, max_threads, recent_pages }) => withBrowserSession(async () => {
+      try {
+        const deadlineAt = Date.now() + 45_000;
+        const result = await syncSubforumIndex(getForumIndex(), subforum, {
+          maxListingPages: max_listing_pages, maxThreads: max_threads, recentPages: recent_pages,
+          deadlineAt,
+        }, (url) => fetchHtml(url, { deadlineAt }));
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+      }
+    }),
+  );
+
+  server.tool(
+    "search_index",
+    "Use first for forum-related game hacking, cheat, anti-cheat, reversing, or offsets questions. Search locally indexed thread titles, snippets and sampled post pages without fetching the forum. Results include timestamps and may be partial or stale.",
+    {
+      query: z.string().min(1),
+      subforum: z.string().optional(),
+      limit: z.number().int().min(1).max(100).optional().default(20),
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async ({ query, subforum, limit }) => {
+      try {
+        const index = getForumIndex();
+        const hits = index.search(query, subforum, limit);
+        return { content: [{ type: "text", text: JSON.stringify({ source: "local_index", count: hits.length, coverage: index.status(subforum), hits }) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "index_status",
+    "Show local index coverage, counts, and last update times; does not contact the forum.",
+    { subforum: z.string().optional().describe("Optional subforum slug to inspect indexed listing page numbers") },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async ({ subforum }) => {
+      try {
+        return { content: [{ type: "text", text: JSON.stringify(getForumIndex().status(subforum)) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+      }
+    },
+  );
+}