codechef-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarthak Agnihotri
+
+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

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# codechef-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/codechef-mcp)](https://www.npmjs.com/package/codechef-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+
+An MCP server that turns CodeChef user profiles into **structured JSON** for LLMs — no more
+dumping 180 KB of HTML into the context window and hoping the model finds the rating.
+
+Written in plain Node.js (ESM). No build step.
+
+## Why
+
+A CodeChef profile page is ~180 KB of markup. Most of the useful data is actually already
+machine-readable inside it, just buried:
+
+| Data | Where it lives |
+| --- | --- |
+| Contest rating history | `var all_rating = [...]` |
+| Submission heat map | `userDailySubmissionsStats = [...]` |
+| Name, stars, country, role, organisation | `.user-details` sidebar |
+| Rating, division, global/country rank | `#rating-block-all` |
+| Problems solved total | `Total Problems Solved: N` |
+| Per-contest solved problems | `.problems-solved .content` |
+
+This server extracts those into typed fields, normalizes dates/numbers, computes deltas, and
+returns compact JSON (a few KB) instead of raw HTML.
+
+## Tools
+
+OpenCode prefixes tool names with the server name, so a server named `codechef` exposes them as
+`codechef_get_profile`, `codechef_get_rating_history`, and so on.
+
+| Tool | Returns |
+| --- | --- |
+| `get_profile` | Name, stars, country, role, organisation, current/highest rating, division, global rank, country rank, problems solved, contest count, latest contest, best rating, last 5 contests |
+| `get_rating_history` | Newest-first contest list with `rating`, `ratingChange` delta and `rank` |
+| `get_activity` | Submission heat map summary: total submissions, active days, average per active day, busiest day, monthly totals (daily detail when `days <= 60`) |
+| `get_contests` | Recent contests with the problems solved in each, merged with rank and rating delta |
+| `get_solved_problems` | Unique problem names with their contest, plus the profile's reported total |
+| `compare_users` | Compact side-by-side profiles for 2–5 handles |
+
+All tools take a `handle` (CodeChef username, e.g. `gennady.korotkevich`).
+
+## Install
+
+```sh
+npx codechef-mcp
+```
+
+Or globally:
+
+```sh
+npm install -g codechef-mcp
+```
+
+## Quick start
+
+```sh
+cd codechef-mcp
+npm install
+npm test          # unit + live + MCP handshake
+```
+
+Run the server directly (it speaks MCP over stdio):
+
+```sh
+npm start
+```
+
+Try the scraper without MCP:
+
+```sh
+node test/smoke.js aryanc403
+```
+
+## Wiring it into OpenCode (V2)
+
+Config uses `mcp.servers`. Either run:
+
+```sh
+opencode mcp add codechef --global -- node "/path/to/codechef-mcp/src/server.js"
+```
+
+or add it by hand to `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "codechef": {
+        "type": "local",
+        "command": ["node", "/path/to/codechef-mcp/src/server.js"],
+        "cwd": "/path/to/codechef-mcp"
+      }
+    }
+  }
+}
+```
+
+Then check it with `opencode mcp list`. Under Code Mode the tools appear as
+`tools.codechef.get_profile(...)`.
+
+## Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codechef": {
+      "command": "node",
+      "args": ["/path/to/codechef-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+## Behavior
+
+- **Cache:** parsed pages are cached for 10 minutes per handle (max 200 entries).
+- **Throttle:** at least 800 ms between outbound requests.
+- **Retries:** up to 3 attempts with backoff on `403`, `429`, `5xx` and Cloudflare challenges.
+- **Errors:** typed codes — `INVALID_HANDLE`, `USER_NOT_FOUND`, `BLOCKED`, `UNPARSEABLE`,
+  `FETCH_FAILED` — returned with `isError: true` so the model can react instead of retrying blindly.
+- **User-Agent:** identifies the client; requests are one profile page at a time.
+
+## Security
+
+- **Outbound HTTPS only, to `www.codechef.com`.** Responses redirected to any other host are rejected.
+- **TLS verification** is on (Node's default `fetch`; no `rejectUnauthorized: false` anywhere).
+- **Bounded resources:** 5 MB response cap (streamed, aborts mid-body), 25 s timeout, 3 retries,
+  200-entry cache.
+- **No `eval`, no `new Function`, no child processes, no filesystem or environment access.**
+- **No credentials** are read, stored, or sent — requests are anonymous.
+- **Handle whitelisting:** handles must match `^[A-Za-z0-9._-]{1,64}$` and are URL-encoded, so a
+  handle cannot alter the request path.
+- **Null-prototype maps** for page-derived keys, so a crafted label cannot touch `Object.prototype`.
+- Publishing is limited by the `files` field: only `src/` + docs ship to npm.
+
+## Caveats
+
+- **Unofficial.** CodeChef's HTML is not a contract. If they change markup, `test/unit.js` and
+  `test/smoke.js` will tell you which field broke.
+- **Cloudflare.** CodeChef fronts the site with Cloudflare. A burst of requests can get a
+  "Just a moment..." challenge; the server detects it and reports `BLOCKED` rather than
+  returning garbage. Wait a minute and retry.
+- **`robots.txt`.** `/users/*` is not disallowed, which is what this server reads. The
+  `/rankings/*` leaderboard **is** disallowed, so global/country rank are taken from the profile
+  page instead of scraping rankings.
+- **Counts can differ.** `get_solved_problems.uniqueProblemsSolved` (from the per-contest list) can
+  be lower than `reportedTotalSolved`, because the profile only lists problems for the contests it
+  renders.
+- No login-only data (submissions, code, unsolved problems) — that needs a session and is out of
+  scope.
+
+## Layout
+
+```
+src/server.js   MCP entry point (stdio)
+src/tools.js    tool registration + schemas
+src/api.js      derived data (deltas, summaries)
+src/parse.js    HTML/embedded-JSON parsing
+src/http.js     fetch, cache, throttle, retries
+test/unit.js    offline parser tests
+test/smoke.js   live scraper test
+test/mcp.js     end-to-end MCP client handshake
+```
+
+## License
+
+MIT © Sarthak Agnihotri ([sarthaksec](https://github.com/sarthaksec)).
+Not affiliated with or endorsed by CodeChef.

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "codechef-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server that turns CodeChef user profiles into structured JSON for LLMs",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "codechef-mcp": "src/server.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node test/unit.js && node test/smoke.js && node test/mcp.js",
+    "test:unit": "node test/unit.js",
+    "test:live": "node test/smoke.js",
+    "test:mcp": "node test/mcp.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "codechef",
+    "competitive-programming",
+    "scraper",
+    "llm"
+  ],
+  "author": "Sarthak Agnihotri (sarthaksec)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sarthaksec/codechef-mcp.git"
+  },
+  "homepage": "https://github.com/sarthaksec/codechef-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/sarthaksec/codechef-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "cheerio": "^1.2.0",
+    "zod": "^4.6.7"
+  }
+}

package/src/api.js

@@ -0,0 +1,210 @@
+import { fetchUserPage } from "./http.js";
+import { parseUserPage } from "./parse.js";
+
+async function load(handle, opts) {
+  const { html, fromCache, url } = await fetchUserPage(handle, opts);
+  const data = parseUserPage(html, handle);
+  return { data, meta: { profileUrl: url, fromCache } };
+}
+
+function sortedHistory(history) {
+  return [...history]
+    .filter((h) => h.date)
+    .sort((a, b) => a.date.localeCompare(b.date));
+}
+
+function withDeltas(history) {
+  const sorted = sortedHistory(history);
+  return sorted.map((entry, i) => ({
+    ...entry,
+    ratingChange: i === 0 || entry.rating == null || sorted[i - 1].rating == null
+      ? null
+      : entry.rating - sorted[i - 1].rating,
+  }));
+}
+
+export async function getProfile(handle) {
+  const { data, meta } = await load(handle);
+  const history = withDeltas(data.ratingHistory);
+
+  const latest = history.at(-1) ?? null;
+  const best = history.reduce(
+    (acc, h) => (h.rating != null && (!acc || h.rating > acc.rating) ? h : acc),
+    null,
+  );
+
+  return {
+    username: data.username,
+    name: data.name,
+    stars: data.stars,
+    country: data.country,
+    countryCode: data.countryCode,
+    role: data.role,
+    organisation: data.organisation,
+    rating: data.rating,
+    problemsSolved: data.problemsSolved,
+    contestsParticipated: history.length,
+    latestContest: latest
+      ? {
+          contest: latest.contest,
+          date: latest.date,
+          rating: latest.rating,
+          ratingChange: latest.ratingChange,
+          rank: latest.rank,
+        }
+      : null,
+    bestRating: best
+      ? { rating: best.rating, contest: best.contest, date: best.date }
+      : null,
+    recentForm: history.slice(-5).map((h) => ({
+      date: h.date,
+      rating: h.rating,
+      ratingChange: h.ratingChange,
+      rank: h.rank,
+    })),
+    profileUrl: meta.profileUrl,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function getRatingHistory(handle, { limit = 20 } = {}) {
+  const { data, meta } = await load(handle);
+  const history = withDeltas(data.ratingHistory);
+  const recent = history.slice(-limit).reverse();
+
+  return {
+    username: data.username,
+    totalContests: history.length,
+    currentRating: data.rating.current,
+    highestRating: data.rating.highest,
+    contests: recent.map((h) => ({
+      contest: h.contest,
+      code: h.code,
+      date: h.date,
+      rating: h.rating,
+      ratingChange: h.ratingChange,
+      rank: h.rank,
+    })),
+    profileUrl: meta.profileUrl,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function getActivity(handle, { days = 90 } = {}) {
+  const { data, meta } = await load(handle);
+  const cutoff = new Date(Date.now() - days * 86_400_000)
+    .toISOString()
+    .slice(0, 10);
+
+  const window = data.heatmap
+    .filter((d) => d.date >= cutoff)
+    .sort((a, b) => a.date.localeCompare(b.date));
+
+  const totalSubmissions = window.reduce((s, d) => s + d.submissions, 0);
+  const activeDays = window.filter((d) => d.submissions > 0).length;
+  const busiest = window.reduce(
+    (acc, d) => (d.submissions > (acc?.submissions ?? 0) ? d : acc),
+    null,
+  );
+
+  const byMonth = {};
+  for (const d of window) {
+    const month = d.date.slice(0, 7);
+    byMonth[month] = (byMonth[month] ?? 0) + d.submissions;
+  }
+
+  return {
+    username: data.username,
+    windowDays: days,
+    since: cutoff,
+    totalSubmissions,
+    activeDays,
+    avgSubmissionsPerActiveDay: activeDays
+      ? Number((totalSubmissions / activeDays).toFixed(1))
+      : 0,
+    busiestDay: busiest,
+    byMonth,
+    daily: days <= 60 ? window : undefined,
+    profileUrl: meta.profileUrl,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function getContests(handle, { limit = 10 } = {}) {
+  const { data, meta } = await load(handle);
+  const byName = new Map(
+    withDeltas(data.ratingHistory).map((h) => [h.contest, h]),
+  );
+
+  const contests = [...data.contests]
+    .reverse()
+    .slice(0, limit)
+    .map((c) => {
+      const rating = byName.get(c.contest);
+      return {
+        contest: c.contest,
+        problemsSolved: c.problemsSolved,
+        problems: c.problems,
+        date: rating?.date ?? null,
+        rank: rating?.rank ?? null,
+        ratingAfter: rating?.rating ?? null,
+        ratingChange: rating?.ratingChange ?? null,
+      };
+    });
+
+  return {
+    username: data.username,
+    totalContestsWithSolutions: data.contests.length,
+    contests,
+    profileUrl: meta.profileUrl,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function getSolvedProblems(handle, { limit = 200 } = {}) {
+  const { data, meta } = await load(handle);
+  const seen = new Map();
+
+  for (const c of data.contests) {
+    for (const p of c.problems) {
+      if (!seen.has(p)) seen.set(p, c.contest);
+    }
+  }
+
+  const all = [...seen.entries()].map(([problem, contest]) => ({ problem, contest }));
+
+  return {
+    username: data.username,
+    uniqueProblemsSolved: all.length,
+    reportedTotalSolved: data.problemsSolved,
+    returned: Math.min(limit, all.length),
+    problems: all.slice(0, limit),
+    profileUrl: meta.profileUrl,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function compareUsers(handles) {
+  const results = [];
+  for (const handle of handles) {
+    try {
+      const p = await getProfile(handle);
+      results.push({
+        username: p.username,
+        name: p.name,
+        stars: p.stars,
+        country: p.country,
+        rating: p.rating,
+        problemsSolved: p.problemsSolved,
+        contestsParticipated: p.contestsParticipated,
+        bestRating: p.bestRating?.rating ?? null,
+      });
+    } catch (err) {
+      results.push({ username: handle, error: err.message });
+    }
+  }
+  return {
+    users: results,
+    fetchedAt: new Date().toISOString(),
+  };
+}

package/src/errors.js

@@ -0,0 +1,9 @@
+export class CodeChefError extends Error {
+  constructor(message, { code = "ERROR", status, retryable = false } = {}) {
+    super(message);
+    this.name = "CodeChefError";
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+  }
+}

package/src/http.js

@@ -0,0 +1,219 @@
+import { CodeChefError } from "./errors.js";
+
+const BASE = "https://www.codechef.com/users/";
+const ALLOWED_HOST = "www.codechef.com";
+const USER_AGENT =
+  "codechef-mcp/0.1 (+https://github.com/sarthaksec/codechef-mcp)";
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const MIN_INTERVAL_MS = 800;
+const REQUEST_TIMEOUT_MS = 25_000;
+const MAX_RETRIES = 3;
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+
+const cache = new Map();
+let lastRequestAt = 0;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function throttle() {
+  const wait = MIN_INTERVAL_MS - (Date.now() - lastRequestAt);
+  if (wait > 0) await sleep(wait);
+  lastRequestAt = Date.now();
+}
+
+export function isValidHandle(handle) {
+  return typeof handle === "string" && /^[A-Za-z0-9._-]{1,64}$/.test(handle);
+}
+
+/**
+ * Fetch a CodeChef user profile page, with caching, global throttling and
+ * retries for transient/Cloudflare responses.
+ */
+export async function fetchUserPage(handle, { force = false } = {}) {
+  if (!isValidHandle(handle)) {
+    throw new CodeChefError(
+      `Invalid CodeChef handle: ${JSON.stringify(handle)}`,
+      { code: "INVALID_HANDLE" },
+    );
+  }
+
+  const key = handle.toLowerCase();
+  const cached = cache.get(key);
+  if (!force && cached && Date.now() - cached.at < CACHE_TTL_MS) {
+    return { html: cached.html, fromCache: true, url: cached.url };
+  }
+
+  const url = BASE + encodeURIComponent(handle);
+  let lastErr;
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    await throttle();
+    try {
+      const res = await fetch(url, {
+        headers: {
+          "User-Agent": USER_AGENT,
+          Accept: "text/html,application/xhtml+xml",
+          "Accept-Language": "en-US,en;q=0.9",
+        },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        redirect: "follow",
+      });
+
+      if (res.status === 404) {
+        throw new CodeChefError(`CodeChef user "${handle}" not found (HTTP 404).`, {
+          code: "USER_NOT_FOUND",
+          status: 404,
+        });
+      }
+      if (res.status === 429 || res.status === 403 || res.status >= 500) {
+        lastErr = new CodeChefError(
+          `CodeChef responded with HTTP ${res.status}.`,
+          { code: "UPSTREAM", status: res.status, retryable: true },
+        );
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      if (!res.ok) {
+        throw new CodeChefError(`Unexpected HTTP ${res.status} from CodeChef.`, {
+          code: "UPSTREAM",
+          status: res.status,
+        });
+      }
+
+      // Never follow a redirect off CodeChef (defends against an upstream
+      // redirect being used to point the client at another host).
+      if (new URL(res.url).hostname !== ALLOWED_HOST) {
+        throw new CodeChefError(
+          `Refusing response redirected to unexpected host: ${new URL(res.url).hostname}`,
+          { code: "UNEXPECTED_REDIRECT" },
+        );
+      }
+
+      const html = await readTextCapped(res, MAX_RESPONSE_BYTES);
+
+      if (isCloudflareChallenge(html)) {
+        lastErr = new CodeChefError(
+          "CodeChef's Cloudflare protection served a bot challenge instead of the profile. " +
+            "Wait a minute and retry, or lower the request rate.",
+          { code: "BLOCKED", retryable: true },
+        );
+        await sleep(1500 * 2 ** attempt);
+        continue;
+      }
+
+      if (isNotFoundPage(html)) {
+        throw new CodeChefError(`CodeChef user "${handle}" does not exist.`, {
+          code: "USER_NOT_FOUND",
+          status: 404,
+        });
+      }
+
+      if (!looksLikeProfile(html)) {
+        throw new CodeChefError(
+          "CodeChef returned a page without profile data (possible markup change or outage).",
+          { code: "UNPARSEABLE", retryable: true },
+        );
+      }
+
+      cache.set(key, { html, at: Date.now(), url });
+      pruneCache();
+      return { html, fromCache: false, url };
+    } catch (err) {
+      if (err instanceof CodeChefError && !err.retryable) throw err;
+      lastErr = err;
+      await sleep(500 * 2 ** attempt);
+    }
+  }
+
+  if (lastErr instanceof CodeChefError && lastErr.code === "BLOCKED") {
+    throw lastErr;
+  }
+
+  throw new CodeChefError(
+    `Could not fetch CodeChef profile for "${handle}" after ${MAX_RETRIES} attempts: ${
+      lastErr?.message ?? "unknown error"
+    }`,
+    { code: "FETCH_FAILED", retryable: true },
+  );
+}
+
+export async function readTextCapped(res, maxBytes) {
+  const declared = Number(res.headers.get("content-length") ?? 0);
+  if (declared > maxBytes) {
+    throw new CodeChefError(`Response too large (${declared} bytes).`, {
+      code: "RESPONSE_TOO_LARGE",
+    });
+  }
+  if (!res.body) return res.text();
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let total = 0;
+  let out = "";
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {});
+        throw new CodeChefError(
+          `Response exceeded ${maxBytes} bytes; aborted to protect memory.`,
+          { code: "RESPONSE_TOO_LARGE" },
+        );
+      }
+      out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+    return out;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      /* already released */
+    }
+  }
+}
+
+function looksLikeProfile(html) {
+  return (
+    typeof html === "string" &&
+    (html.includes('class="user-details"') || html.includes("h2-style")) &&
+    html.includes("all_rating")
+  );
+}
+
+function isCloudflareChallenge(html) {
+  return (
+    typeof html === "string" &&
+    (html.includes("_cf_chl_opt") ||
+      html.includes("Just a moment...") ||
+      html.includes("Enable JavaScript and cookies to continue"))
+  );
+}
+
+export function isNotFoundPage(html) {
+  if (typeof html !== "string") return false;
+  if (looksLikeProfile(html)) return false;
+  if (/does not exist|user not found|no such user|invalid user/i.test(html)) {
+    return true;
+  }
+  // Unknown handles soft-404 to the generic CodeChef home shell with HTTP 200.
+  return (
+    /<title>\s*CodeChef\s*-\s*Learn and Practice Coding with Problems\s*<\/title>/i.test(html) ||
+    /property="og:url"\s+content="https:\/\/www\.codechef\.com\/"/i.test(html)
+  );
+}
+
+export { isCloudflareChallenge };
+
+function pruneCache() {
+  if (cache.size <= 200) return;
+  const oldest = [...cache.entries()].sort((a, b) => a[1].at - b[1].at);
+  for (const [k] of oldest.slice(0, cache.size - 200)) cache.delete(k);
+}
+
+export function clearCache() {
+  cache.clear();
+}

package/src/parse.js

@@ -0,0 +1,163 @@
+import * as cheerio from "cheerio";
+
+const clean = (s = "") =>
+  s.replace(/\u00a0/g, " ").replace(/\s+/g, " ").trim();
+
+const num = (v) => {
+  if (v == null) return null;
+  const n = Number(String(v).replace(/[^0-9-]/g, ""));
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * Extract a JS array literal that follows `marker`, e.g.
+ *   var all_rating = [ ... ];
+ * Uses bracket matching so nested objects/strings don't break it.
+ */
+export function extractJsonArray(source, marker) {
+  const at = source.indexOf(marker);
+  if (at === -1) return null;
+  const start = source.indexOf("[", at);
+  if (start === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString) {
+      if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "[") depth++;
+    else if (ch === "]") {
+      depth--;
+      if (depth === 0) return source.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+function safeParseArray(source, marker) {
+  const raw = extractJsonArray(source, marker);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function normalizeDate(value) {
+  if (!value) return null;
+  const m = /^(\d{4})-(\d{1,2})-(\d{1,2})/.exec(String(value).trim());
+  if (!m) return null;
+  return `${m[1]}-${String(m[2]).padStart(2, "0")}-${String(m[3]).padStart(2, "0")}`;
+}
+
+export function parseUserPage(html, handle) {
+  const $ = cheerio.load(html);
+
+  const name = clean($("h1.h2-style").first().text()) || null;
+  const username = clean($(".m-username--link").first().text()) || handle;
+
+  // Sidebar: Username / Country / Student-Professional / Organisation / Pro Plan
+  const sidebar = Object.create(null);
+  $(".user-details li").each((_, li) => {
+    const $li = $(li);
+    const label = clean($li.find("label").first().text())
+      .replace(/:$/, "")
+      .toLowerCase();
+    if (!label) return;
+    const clone = $li.clone();
+    clone.find("label").remove();
+    clone.find("a").remove();
+    const value = clean(clone.text()).replace(/View Details$/i, "").trim();
+    if (value) sidebar[label] = value;
+  });
+
+  const starsText = clean($(".user-details .rating").first().text());
+  const stars = num(/(\d+)/.exec(starsText)?.[1]);
+  const starCount = $("#rating-block-all .rating-star span").length || null;
+
+  const block = $("#rating-block-all");
+  const ratingText = clean(block.find(".rating-number").first().text());
+  const currentRating = /^\d+$/.test(ratingText) ? Number(ratingText) : null;
+
+  const headerText = clean(block.find(".rating-header").first().text());
+  const division = /\(Div\s*(\d+)\)/i.exec(headerText)?.[1] ?? null;
+  const highestRating = num(/(\d+)/.exec(clean(block.find("small").first().text()))?.[1]);
+
+  const ranks = Object.create(null);
+  block.find(".rating-ranks li").each((_, li) => {
+    const $li = $(li);
+    const value = clean($li.find("strong").first().text());
+    const label = clean($li.text()).replace(value, "").trim().toLowerCase();
+    const key = label.includes("global")
+      ? "global"
+      : label.includes("country")
+        ? "country"
+        : label || "unknown";
+    ranks[key] = /^\d+$/.test(value) ? Number(value) : value || null;
+  });
+
+  let problemsSolved = null;
+  $("h3").each((_, h) => {
+    const m = /Total Problems Solved:\s*([\d,]+)/i.exec(clean($(h).text()));
+    if (m) problemsSolved = Number(m[1].replace(/,/g, ""));
+  });
+
+  const contests = [];
+  $(".problems-solved .content").each((_, el) => {
+    const contest = clean($(el).find("h5").first().text());
+    const problems = clean($(el).find("p").first().text())
+      .split(",")
+      .map((p) => p.trim())
+      .filter(Boolean);
+    if (contest) contests.push({ contest, problemsSolved: problems.length, problems });
+  });
+
+  const ratingHistory = safeParseArray(html, "var all_rating")
+    .map((r) => ({
+      code: r.code ?? null,
+      contest: clean(r.name) || null,
+      date: normalizeDate(r.end_date) ?? normalizeDate(`${r.getyear}-${r.getmonth}-${r.getday}`),
+      rating: num(r.rating),
+      rank: num(r.rank),
+      reason: r.reason ?? null,
+    }))
+    .filter((r) => r.date || r.rating != null);
+
+  const heatmap = safeParseArray(html, "userDailySubmissionsStats")
+    .map((d) => ({ date: normalizeDate(d.date), submissions: num(d.value) ?? 0 }))
+    .filter((d) => d.date);
+
+  return {
+    username,
+    name,
+    stars: stars ?? starCount,
+    country: clean($(".user-country-name").first().text()) || null,
+    countryCode: $("img.user-country-flag").first().attr("title") || null,
+    role: sidebar["student/professional"] ?? null,
+    organisation: sidebar["organisation"] ?? sidebar["institution"] ?? null,
+    rating: {
+      current: currentRating,
+      highest: highestRating,
+      division: division ? Number(division) : null,
+      globalRank: ranks.global ?? null,
+      countryRank: ranks.country ?? null,
+    },
+    problemsSolved,
+    contests,
+    ratingHistory,
+    heatmap,
+  };
+}

package/src/server.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+
+const server = new McpServer({
+  name: "codechef-mcp",
+  version: "0.1.0",
+});
+
+registerTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// stdout is reserved for the MCP protocol; diagnostics go to stderr.
+console.error("[codechef-mcp] running on stdio");

package/src/tools.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import {
+  compareUsers,
+  getActivity,
+  getContests,
+  getProfile,
+  getRatingHistory,
+  getSolvedProblems,
+} from "./api.js";
+
+const handleSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .describe("CodeChef username/handle, e.g. 'gennady.korotkevich'");
+
+const json = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+
+const fail = (err) => ({
+  isError: true,
+  content: [
+    {
+      type: "text",
+      text: `CodeChef MCP error (${err.code ?? "ERROR"}): ${err.message}`,
+    },
+  ],
+});
+
+const wrap = (fn) => async (args) => {
+  try {
+    return json(await fn(args));
+  } catch (err) {
+    return fail(err);
+  }
+};
+
+export function registerTools(server) {
+  server.registerTool(
+    "get_profile",
+    {
+      title: "Get CodeChef profile",
+      description:
+        "Fetch a CodeChef user's profile as compact structured JSON: name, star rating, " +
+        "current and highest rating, division, global rank, country rank, problems solved, " +
+        "contests participated, latest contest and recent form. Prefer this over downloading " +
+        "and parsing the profile HTML page.",
+      inputSchema: { handle: handleSchema },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handle }) => getProfile(handle)),
+  );
+
+  server.registerTool(
+    "get_rating_history",
+    {
+      title: "Get CodeChef rating history",
+      description:
+        "Return a user's contest rating history (newest first) with rating after each contest, " +
+        "rating change (delta) and rank. Useful for trends, streaks and 'how has X improved' questions.",
+      inputSchema: {
+        handle: handleSchema,
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe("How many recent contests to return (default 20)."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handle, limit }) => getRatingHistory(handle, { limit: limit ?? 20 })),
+  );
+
+  server.registerTool(
+    "get_activity",
+    {
+      title: "Get CodeChef submission activity",
+      description:
+        "Summarize a user's submission heat map over a time window: total submissions, active days, " +
+        "average per active day, busiest day and monthly totals. Answers 'how active is X' without " +
+        "loading the heat map image or HTML.",
+      inputSchema: {
+        handle: handleSchema,
+        days: z
+          .number()
+          .int()
+          .min(7)
+          .max(3650)
+          .optional()
+          .describe("Look-back window in days (default 90). Daily breakdown included only when <= 60."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handle, days }) => getActivity(handle, { days: days ?? 90 })),
+  );
+
+  server.registerTool(
+    "get_contests",
+    {
+      title: "Get CodeChef contest results",
+      description:
+        "List a user's contests (newest first) with the problems solved in each, plus rank and rating change " +
+        "where available. Use this for 'what has X solved recently' or per-contest performance.",
+      inputSchema: {
+        handle: handleSchema,
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(100)
+          .optional()
+          .describe("How many recent contests to return (default 10)."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handle, limit }) => getContests(handle, { limit: limit ?? 10 })),
+  );
+
+  server.registerTool(
+    "get_solved_problems",
+    {
+      title: "Get CodeChef solved problems",
+      description:
+        "Return the unique problem names a user has solved (as listed on their profile), with the contest " +
+        "each came from, plus their reported total solved count. Capped by 'limit' to protect context size.",
+      inputSchema: {
+        handle: handleSchema,
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(1000)
+          .optional()
+          .describe("Maximum number of problem names to return (default 200)."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handle, limit }) => getSolvedProblems(handle, { limit: limit ?? 200 })),
+  );
+
+  server.registerTool(
+    "compare_users",
+    {
+      title: "Compare CodeChef users",
+      description:
+        "Fetch compact side-by-side profiles for 2-5 CodeChef handles: rating, stars, ranks, problems solved " +
+        "and contest count. Handy for 'who is better' or team-selection questions.",
+      inputSchema: {
+        handles: z
+          .array(z.string().min(1).max(64))
+          .min(2)
+          .max(5)
+          .describe("Two to five CodeChef handles to compare."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(({ handles }) => compareUsers(handles)),
+  );
+}