codechef-mcp
# codechef-mcp (Unified Edition)
[](https://www.npmjs.com/package/codechef-mcp)
[](LICENSE)
[](package.json)
[](requirements.txt)
The unified, complete **Model Context Protocol (MCP)** server for CodeChef. It bridges AI assistants (such as Claude Desktop, Cursor, OpenCode, and Gemini) with CodeChef for both **User Profiling & Analytics** and **Contest Participation & Problem Solving**.
Available in two seamless runtimes:
* **Node.js (ESM)**: Lightweight, zero-config stdio MCP server for profile analytics and contest browsing.
* **Python (FastMCP)**: Full-featured engine supporting all tools, Docker sandbox code execution (C++, Python, Java, Go, Rust), and Playwright browser submission/verdict polling over STDIO or streamable HTTP/SSE.
---
## š Capabilities & Tools
### 1. User Profiles & Analytics
| Tool | Description |
| --- | --- |
| `get_profile` | Structured user profile (name, stars, current/highest rating, division, global/country rank, problems solved, contest count, recent form). |
| `get_rating_history` | Chronological contest history with rating after each contest, rating deltas (`ratingChange`), and ranks. |
| `get_activity` | Submission heat map summary: total submissions, active days, average submissions per active day, busiest day, and monthly breakdown. |
| `get_contests` | Contests participated in with problems solved in each, merged with rating change and rank. |
| `get_solved_problems` | Unique problems solved by a user mapped to their source contest. |
| `compare_users` | Compact side-by-side comparison for 2ā5 handles. |
### 2. Contest Management & Problem Solving
| Tool | Description |
| --- | --- |
| `open_contest` | Open contest and fetch metadata, start/end dates, problem list, and category details. |
| `list_problems` | List all problems in a contest with codes, names, and submission counts. |
| `get_problem` | Fetch clean problem statements (Markdown), constraints, time/memory limits, and sample test cases. |
| `validate_complexity` | Static heuristic time/space complexity analysis (loop nesting depth & annotations). |
| `generate_tests` | Generate adversarial edge cases (minimum/maximum bounds, all identical, sorted, boundary flips, random cases). |
| `get_contest_progress`* | Track attempted, solved, and remaining problems in an active contest. |
### 3. Execution, Submission & Automated Repair (Python Engine)
| Tool | Description |
| --- | --- |
| `run_code`* | Execute code in an isolated Docker sandbox with zero network access, memory limits, CPU caps, and timeouts (supports C++, Python, Java, Go, Rust). |
| `evaluate_confidence`* | Pre-submission confidence evaluation against sample and adversarial tests. |
| `submit_solution`* | Automate CodeChef submission via Playwright browser automation. |
| `get_submission_status`* | Poll submission verdict (AC, WA, TLE, RE) and runtime metrics. |
| `retry_solution`* | Self-repair diagnosis pipeline that analyzes failure causes and suggests code fixes. |
| `get_submission_history`* | Retrieve past submission history from local SQLite database. |
*\* Advanced execution and submission tools run via the Python engine.*
---
## š Project Structure
```text
codechef-mcp/
ā
āāā app/ # Python FastMCP Server
ā āāā browser/ # Profile scrapers, Playwright submitters, API clients
ā ā āāā profile.py # User profile, rating history, heatmap & comparison
ā ā āāā contest.py # Contest metadata & problem list fetching
ā ā āāā problem.py # Problem statement & sample test parser
ā ā āāā login.py # Playwright authentication manager
ā ā āāā submission.py # Code submission automation
ā ā āāā verdict.py # Verdict polling loop
ā āāā models/ # SQLAlchemy SQLite schema (contests, submissions, logs)
ā āāā retry_engine/ # Failure diagnostic & repair pipeline
ā āāā sandbox/ # Docker runner & multi-language configurations
ā āāā solver/ # Sequential contest solver state
ā āāā tools/ # FastMCP tool registrations (18 tools)
ā āāā utils/ # Structured logging & Redis/in-memory cache
ā āāā config.py # Configuration loader
ā āāā main.py # Streamable HTTP ASGI app
ā āāā mcp_server.py # FastMCP server instance
ā
āāā src/ # Node.js MCP Server
ā āāā api.js # Node API router
ā āāā contest.js # Contest metadata, problem statement & complexity analyzer
ā āāā errors.js # Error definitions
ā āāā http.js # HTTP fetch client with caching & rate limits
ā āāā parse.js # Profile HTML & inline script JSON parser
ā āāā server.js # Stdio server entrypoint
ā āāā tools.js # Stdio tool definitions (11 tools)
ā
āāā tests/ # Python test suite (33 unit tests)
āāā test/ # Node.js test suite (34 unit tests)
āāā docs/ # PRD and cloud deployment guides (Fly.io, Render)
āāā Dockerfile # Container definition
āāā docker-compose.yml # Docker Compose definition
āāā run_server.py # Python server CLI runner (STDIO & HTTP)
āāā requirements.txt # Python dependencies
āāā package.json # Node.js package definition
```
---
## š ļø Usage & Setup
### Running via Node.js
#### 1. Instant run via npx:
```bash
npx codechef-mcp
```
#### 2. Local installation:
```bash
npm install
npm test
npm start
```
### Running via Python
#### 1. Setup virtual environment:
```bash
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```
#### 2. Run Python tests:
```bash
pytest tests/ -v
```
#### 3. Run Python Server:
```bash
# STDIO Transport:
python run_server.py
# Streamable HTTP/SSE Transport:
python run_server.py --http --port 8000
```
---
## š Connecting to AI Clients
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"codechef": {
"command": "node",
"args": ["E:/PERSONAL/OpenSource/codechef-mcp/src/server.js"]
}
}
}
```
Or for the Python full-suite server:
```json
{
"mcpServers": {
"codechef": {
"command": "E:/PERSONAL/OpenSource/codechef-mcp/venv/Scripts/python.exe",
"args": ["E:/PERSONAL/OpenSource/codechef-mcp/run_server.py"]
}
}
}
```
### Cursor / Web Agents (HTTP/SSE)
Run:
```bash
python run_server.py --http --port 8000
```
Connect to `http://localhost:8000/mcp`.
---
## š License
MIT License.
TDQS
Scored across 11 tools
Tools mostly target distinct facets: profile, rating history, activity, contests, solved problems, contest problem access, and code analysis. Some overlap exists between open_contest and list_problems for contest problem lists, and between get_rating_history and get_contests for per-contest rating data, but descriptions largely clarify intended use.
All tool names use snake_case and follow a predictable verb_noun or verb_noun_plural pattern, such as get_profile, list_problems, compare_users, and generate_tests. There are no mixed casing styles or vague names.
With 11 tools, the server is well-scoped for CodeChef profile, contest, and problem analysis. The count is neither thin nor bloated, and each tool has a plausible role.
The surface covers the major read-only workflows: profiles, rating trends, activity, contests, solved problems, comparisons, contest problems, complexity validation, and test generation. Minor gaps include global problem search, submission/code retrieval, and contest leaderboards, but core workflows are supported.