mcp-unknowncheatz 0.3.0

package/src/tools/get-thread.ts

@@ -0,0 +1,137 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { fetchHtml } from "../crawl.js";
+import { parseThread } from "../parsers/thread.js";
+import type { ThreadPost } from "../types.js";
+
+const MAX_PAGES = 50;
+const MAX_IMAGES = 10; // max images to fetch and embed per call
+
+function buildPageUrl(baseUrl: string, page: number): string {
+  const url = new URL(baseUrl);
+  url.searchParams.set("page", String(page));
+  return url.toString();
+}
+
+async function fetchImageAsBase64(url: string): Promise<{ data: string; mimeType: string } | null> {
+  try {
+    const res = await fetch(url, {
+      headers: { "User-Agent": "Mozilla/5.0" },
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!res.ok) return null;
+
+    const contentType = res.headers.get("content-type") ?? "image/png";
+    const mimeType = contentType.split(";")[0].trim();
+    if (!mimeType.startsWith("image/")) return null;
+
+    const buffer = await res.arrayBuffer();
+    const data = Buffer.from(buffer).toString("base64");
+    return { data, mimeType };
+  } catch {
+    return null;
+  }
+}
+
+export function registerGetThread(server: McpServer): void {
+  server.tool(
+    "get_thread",
+    "Get a forum thread. Use latest_pages for recent posts in long-running threads; the default reads only the linked page.",
+    {
+      url: z.string().url().describe("Thread URL"),
+      fetch_all_pages: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, fetches all pages of the thread (max 50 pages)"),
+      latest_pages: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("Read the last 1-5 pages. Takes precedence over fetch_all_pages."),
+      include_images: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, fetches post images and returns them as viewable image content (max 10 images)"),
+    },
+    async ({ url, fetch_all_pages, latest_pages, include_images }) => {
+      try {
+        const firstHtml = await fetchHtml(url);
+        const pageParam = Number(new URL(url).searchParams.get("page"));
+        const requestedPage = Number.isInteger(pageParam) && pageParam > 0 ? pageParam : 1;
+        const firstPage = parseThread(firstHtml, url, requestedPage);
+        const totalPages = firstPage.totalPages;
+        const pagesToFetch = latest_pages
+          ? Array.from({ length: Math.min(latest_pages, totalPages) }, (_, index) =>
+              totalPages - Math.min(latest_pages, totalPages) + index + 1)
+          : fetch_all_pages
+            ? Array.from({ length: Math.min(totalPages, MAX_PAGES) }, (_, index) => index + 1)
+            : [Math.min(requestedPage, totalPages)];
+
+        const allPosts: ThreadPost[] = [];
+        for (const pageNum of pagesToFetch) {
+          const pageUrl = buildPageUrl(url, pageNum);
+          const html = pageNum === requestedPage ? firstHtml : await fetchHtml(pageUrl);
+          allPosts.push(...parseThread(html, pageUrl, pageNum).posts);
+          console.error(`[get-thread] Fetched page ${pageNum}/${totalPages}`);
+        }
+
+        const result = {
+          title: firstPage.title,
+          posts: allPosts,
+          currentPage: pagesToFetch.at(-1),
+          pagesFetched: pagesToFetch,
+          totalPages,
+          url,
+          ...(fetch_all_pages && !latest_pages && totalPages > MAX_PAGES
+            ? { note: `Capped at ${MAX_PAGES} pages (thread has ${totalPages} total)` }
+            : {}),
+        };
+
+        // Build content array
+        const content: Array<
+          | { type: "text"; text: string }
+          | { type: "image"; data: string; mimeType: string }
+        > = [{ type: "text", text: JSON.stringify(result) }];
+
+        if (include_images) {
+          // Collect all unique image URLs from all posts
+          const seen = new Set<string>();
+          const imageUrls: string[] = [];
+
+          for (const post of allPosts) {
+            for (const imgUrl of post.images) {
+              if (!seen.has(imgUrl)) {
+                seen.add(imgUrl);
+                imageUrls.push(imgUrl);
+              }
+              if (imageUrls.length >= MAX_IMAGES) break;
+            }
+            if (imageUrls.length >= MAX_IMAGES) break;
+          }
+
+          console.error(`[get-thread] Fetching ${imageUrls.length} images...`);
+
+          for (const imgUrl of imageUrls) {
+            const img = await fetchImageAsBase64(imgUrl);
+            if (img) {
+              content.push({ type: "image", data: img.data, mimeType: img.mimeType });
+              console.error(`[get-thread] Fetched image: ${imgUrl}`);
+            }
+          }
+        }
+
+        return { content };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/get-user-reputation.ts

@@ -0,0 +1,125 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { load } from "cheerio";
+import { fetchHtml } from "../crawl.js";
+import { validateUrl } from "../browser.js";
+
+function extractStat(text: string, pattern: RegExp): string | undefined {
+  const match = text.match(pattern);
+  return match ? match[1].trim() : undefined;
+}
+
+function parseNumber(text?: string): number | null {
+  if (!text) return null;
+  const n = parseInt(text.replace(/,/g, ""), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function registerGetUserReputation(server: McpServer): void {
+  server.tool(
+    "get_user_reputation",
+    "Get an UnknownCheats user's reputation, rep power, join date, post count, and tier from their profile page.",
+    {
+      profile_url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Full user profile URL, e.g. https://www.unknowncheats.me/forum/members/6719713.html"),
+      user_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Numeric UC user ID (alternative to profile_url)"),
+    },
+    async ({ profile_url, user_id }) => {
+      try {
+        const url = profile_url ?? (user_id
+          ? `https://www.unknowncheats.me/forum/members/${user_id}.html`
+          : undefined);
+        if (!url) {
+          return {
+            content: [{ type: "text", text: "Error: provide either profile_url or user_id." }],
+            isError: true,
+          };
+        }
+        validateUrl(url);
+
+        const html = await fetchHtml(url);
+        const $ = load(html);
+
+        const rawTitle = $("title").text().trim();
+        const username = $("h1").first().text().trim().split(/\s+/)[0] ||
+          rawTitle.replace(/^View Profile:\s*/i, "").split("-")[0].trim();
+
+        const bodyText = $("body").text();
+
+        const reputationText = extractStat(bodyText, /Reputation[:\s]+([-\d,]+)/i);
+        const repPowerText = extractStat(bodyText, /Rep\s*Power[:\s]+([-\d,]+)/i);
+        const postsText = extractStat(bodyText, /(?:Total Posts|Posts)[:\s]+([\d,]+)/i);
+        const joinText = extractStat(bodyText, /(?:Join Date|Joined)[:\s]+([\w\s,-]{4,25}?)(?=\s{2,}|\n|$)/i);
+        const location = extractStat(bodyText, /Location[:\s]+([^\n]{1,60})/i);
+
+        const repDot = $("img[src*='reputation_']").first();
+        const repDescription = repDot.attr("alt")?.trim();
+        const repSrc = repDot.attr("src") ?? "";
+        const sign =
+          repSrc.includes("_neg") ? "negative" :
+          repSrc.includes("_bar") ? "neutral" :
+          repSrc.includes("_pos") || repSrc.includes("_highpos") ? "positive" :
+          "unknown";
+
+        const reputation = parseNumber(reputationText);
+        const repPower = parseNumber(repPowerText);
+        const posts = parseNumber(postsText);
+
+        let tier: string;
+        if (sign === "negative") tier = "negative";
+        else if (reputation === null) tier = "unknown";
+        else if (reputation >= 5_000) tier = "legend";
+        else if (reputation >= 2_000) tier = "excellent";
+        else if (reputation >= 1_000) tier = "great";
+        else if (reputation >= 500) tier = "good";
+        else if (reputation >= 100) tier = "average";
+        else if (reputation >= 10) tier = "positive";
+        else if (reputation > 0) tier = "novice";
+        else tier = "neutral";
+
+        const trustScore = sign === "negative"
+          ? 5
+          : reputation === null
+            ? 15
+            : reputation <= 0
+              ? 20
+              : Math.max(15, Math.min(100, Math.round(Math.log10(reputation + 1) * 20)));
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                url,
+                username,
+                reputation,
+                repPower,
+                posts,
+                joinDate: joinText,
+                location,
+                tier,
+                sign,
+                description: repDescription,
+                trustScore,
+              }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/list-subforums.ts

@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { fetchHtml } from "../crawl.js";
+import { FORUM_INDEX, readForumCatalog, saveForumCatalog } from "../forum-catalog.js";
+
+export function registerListSubforums(server: McpServer): void {
+  server.tool(
+    "list_subforums",
+    "List game subforum URLs discovered from the live UnknownCheats index. The local directory expires after 24 hours.",
+    {
+      query: z.string().optional().describe("Optional keyword to filter subforum slugs/labels/descriptions"),
+      limit: z.number().int().min(1).max(500).optional().default(100).describe("Max subforums returned (default 100)"),
+      refresh: z.boolean().optional().default(false).describe("Fetch the forum index again instead of using the local directory"),
+    },
+    async ({ query, limit, refresh }) => {
+      try {
+        const cached = refresh ? null : await readForumCatalog();
+        const catalog = cached ?? await saveForumCatalog(await fetchHtml(FORUM_INDEX, { bypassCache: refresh }));
+        const all = catalog.subforums;
+
+        const filtered = query
+          ? all.filter((sf) => {
+              const haystack = `${sf.slug} ${sf.label} ${sf.description ?? ""}`.toLowerCase();
+              return query
+                .toLowerCase()
+                .split(/\s+/)
+                .filter(Boolean)
+                .every((term) => haystack.includes(term));
+            })
+          : all;
+
+        const capped = filtered.slice(0, limit);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                total: all.length,
+                matched: filtered.length,
+                returned: capped.length,
+                source: catalog.source,
+                indexedAt: catalog.indexedAt,
+                fromCache: Boolean(cached),
+                subforums: capped,
+              }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/login.ts

@@ -0,0 +1,71 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { load } from "cheerio";
+import { navigateWithRetry } from "../browser.js";
+import { clearCache } from "../crawl.js";
+import { isLoggedIn } from "../auth.js";
+
+const UC_LOGIN = "https://www.unknowncheats.me/forum/login.php";
+
+export function registerLogin(server: McpServer): void {
+  server.tool(
+    "login",
+    "Log into UnknownCheats with username and password",
+    {
+      username: z.string().describe("UnknownCheats username"),
+      password: z.string().describe("UnknownCheats password"),
+    },
+    async ({ username, password }) => {
+      try {
+        const { page } = await navigateWithRetry(UC_LOGIN);
+
+        // Fill login form — vBulletin field names
+        await page.type('input[name="vb_login_username"]', username, { delay: 60 });
+        await page.type('input[name="vb_login_password"], input[type="password"]', password, { delay: 60 });
+
+        // Submit
+        await Promise.all([
+          page.waitForNavigation({ waitUntil: "networkidle2", timeout: 30_000 }),
+          page.click('input[type="submit"], button[type="submit"]'),
+        ]);
+
+        const html = await page.content();
+        const $ = load(html);
+
+        const loggedIn = isLoggedIn(html);
+
+        if (!loggedIn) {
+          // Check for error message
+          const error = $(".error, .panel .error, #navbar_notice").first().text().trim();
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({ success: false, error: error || "Login failed — check credentials" }),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        clearCache();
+
+        // Extract username from page to confirm
+        const welcomeEl = $("#welcomelink, .welcomelink").first();
+        const welcomeText = welcomeEl.text().trim();
+        const match = welcomeText.match(/Welcome,?\s+(.+)/i);
+        const confirmedUsername = match ? match[1].replace(/[!.]+$/, "").trim() : username;
+
+        return {
+          content: [{ type: "text", text: JSON.stringify({ success: true, username: confirmedUsername }) }],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/search-forum.ts

@@ -0,0 +1,146 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { load } from "cheerio";
+import { navigateWithRetry } from "../browser.js";
+import { fetchHtml } from "../crawl.js";
+import { isLoggedIn } from "../auth.js";
+import { searchViaSubforums } from "../search-fallback.js";
+import { filterThreads, parseThreadList } from "../parsers/thread-list.js";
+
+const UC_HOME = "https://www.unknowncheats.me/forum/";
+const UC_SEARCH = "https://www.unknowncheats.me/forum/search.php";
+
+async function runFallbackSearch(query: string) {
+  console.error(`[search] Not logged in — scanning UC subforums for "${query}"`);
+  const { results, scannedSubforums } = await searchViaSubforums(query, (url) => fetchHtml(url));
+
+  return {
+    count: results.length,
+    source: "subforum_scan" as const,
+    scannedSubforums,
+    requiresLoginForNativeSearch: true,
+    hint: results.length === 0
+      ? "No matches in scanned subforums. Pass subforum (e.g. apex-legends) or use the login tool for full UC search."
+      : "Use the login tool for full UC advanced search (filters, sort, author).",
+    results,
+  };
+}
+
+export function registerSearchForum(server: McpServer): void {
+  server.tool(
+    "search_forum",
+    "Search the UnknownCheats forum. Uses advanced search when logged in, scans relevant subforums as a guest, or browses a named subforum.",
+    {
+      query: z.string().optional().default("").describe("Search query string; optional when browsing a subforum"),
+      subforum: z.string().optional().describe("Subforum slug to browse directly (e.g. 'apex-legends')"),
+      title_only: z.boolean().optional().default(true).describe("Search only in thread titles (default true, more accurate)"),
+      sort_by: z.enum(["relevancy", "lastpost", "replycount", "views", "threadstart"]).optional().default("relevancy").describe("Sort results by"),
+      search_user: z.string().optional().describe("Filter by thread author username"),
+    },
+    async ({ query, subforum, title_only, sort_by, search_user }) => {
+      try {
+        if (!subforum && !query.trim()) {
+          return {
+            content: [{ type: "text", text: "Provide query or subforum" }],
+            isError: true,
+          };
+        }
+
+        if (subforum) {
+          const url = `https://www.unknowncheats.me/forum/${subforum}/`;
+          const html = await fetchHtml(url);
+          const results = filterThreads(parseThreadList(html), { query, includeSticky: true });
+          return {
+            content: [{ type: "text", text: JSON.stringify({ count: results.length, subforum, results }) }],
+          };
+        }
+
+        const homeHtml = await fetchHtml(UC_HOME);
+        if (!isLoggedIn(homeHtml)) {
+          const payload = await runFallbackSearch(query);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+          };
+        }
+
+        const { page } = await navigateWithRetry(UC_SEARCH);
+
+        const submitted = await page.evaluate((opts) => {
+          const searchForm = document.getElementById("searchform") as HTMLFormElement | null;
+          if (!searchForm) return { ok: false, error: "Advanced search form (#searchform) not found" };
+
+          const queryInput = searchForm.querySelector('input[name="query"][size="35"]') as HTMLInputElement
+            ?? searchForm.querySelector('input[name="query"]') as HTMLInputElement;
+          if (!queryInput) return { ok: false, error: "Query input not found in form" };
+          queryInput.value = opts.query;
+
+          const titleOnlySelect = searchForm.querySelector('select[name="titleonly"]') as HTMLSelectElement;
+          if (titleOnlySelect) {
+            titleOnlySelect.value = opts.titleOnly ? "1" : "0";
+          }
+
+          const showThreads = searchForm.querySelector('input[name="showposts"][value="0"]') as HTMLInputElement;
+          if (showThreads) showThreads.checked = true;
+
+          const sortSelect = searchForm.querySelector('select[name="sortby"]') as HTMLSelectElement;
+          if (sortSelect) sortSelect.value = opts.sortBy;
+
+          if (opts.searchUser) {
+            const userInput = searchForm.querySelector('input[name="searchuser"]') as HTMLInputElement;
+            if (userInput) userInput.value = opts.searchUser;
+          }
+
+          return { ok: true };
+        }, { query, titleOnly: title_only, sortBy: sort_by, searchUser: search_user ?? "" });
+
+        if (!submitted.ok) {
+          const payload = await runFallbackSearch(query);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+          };
+        }
+
+        await Promise.all([
+          page.waitForNavigation({ waitUntil: "domcontentloaded", timeout: 30_000 }),
+          page.evaluate(() => (document.getElementById("searchform") as HTMLFormElement).submit()),
+        ]);
+
+        const html = await page.content();
+        const results = parseThreadList(html);
+        const $ = load(html);
+        const pageTitle = $("title").text().trim();
+
+        const errorText = $(".standard_error, .errorwrap, .blockbody .error").first().text().trim();
+        if (errorText) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({ count: 0, error: errorText, pageTitle }) }],
+          };
+        }
+
+        const pageNav = $(".pagenav td.vbmenu_control").first().text().trim();
+        const pageMatch = pageNav.match(/Page (\d+) of (\d+)/);
+        const pagination = pageMatch ? { currentPage: parseInt(pageMatch[1]), totalPages: parseInt(pageMatch[2]) } : undefined;
+
+        console.error(`[search] "${query}" → ${results.length} results, page: ${pageTitle}`);
+
+        return {
+          content: [{ type: "text", text: JSON.stringify({ count: results.length, source: "unknowncheats", pageTitle, pagination, results }) }],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+          const payload = await runFallbackSearch(query);
+          return {
+            content: [{ type: "text", text: JSON.stringify({ ...payload, nativeSearchError: message }) }],
+          };
+        } catch (fallbackErr) {
+          const fallbackMessage = fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+          return {
+            content: [{ type: "text", text: `Error: ${message} (fallback also failed: ${fallbackMessage})` }],
+            isError: true,
+          };
+        }
+      }
+    }
+  );
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+export interface PostLink {
+  text: string;
+  url: string;
+}
+
+import type { AuthorReputation } from "./parsers/reputation.js";
+
+export interface ThreadPost {
+  author: string;
+  date: string;
+  content: string;
+  postNumber: number;
+  links: PostLink[];
+  images: string[];
+  reputation?: AuthorReputation;
+}
+
+export interface ThreadData {
+  title: string;
+  posts: ThreadPost[];
+  currentPage: number;
+  totalPages: number;
+  url: string;
+}
+
+export interface CodeBlock {
+  code: string;
+  language: string;
+  context?: string;
+  postId?: string;
+}