Repovive MCP Server

An MCP server that exposes the Repovive competitive-programming platform to any MCP client (Claude Desktop, Claude Code, IDE extensions, …). Built with FastMCP v3 and httpx.

It provides 93 tools, 10 resources (1 templated), and 8 prompts covering problems, contests, ratings, courses, blog posts, direct messages, notifications, mock-interview info, Vive points, account/profile management, real code submission, contest standings, production problem/contest authoring in Repovive's build editor, and a built-in local judge.

Every tool has been tested end-to-end — read/write tools against the live Repovive API, submission verified with a real Accepted verdict, and the authoring/judge tools by generating full contests and running every reference solution to Accepted.

Contents

• How it works

• What you can do

• Submitting code

• Quick start

• Install

• Configure your MCP client

• Tool reference

• Authoring & local judge

• Repovive house style

• Resources & prompts

• Example agent session

• How auth works

• Deployment

• Project layout

• Documentation

• Development & tests

• Security notes

Related MCP server: MCP Chef

How it works

1. Connect your MCP client (Claude Desktop, Claude Code, an IDE) to the server over stdio or HTTP.

2. Read & author — browse problems and contests, or generate and draft new ones in Repovive's build editor.

3. Judge locally — verify a solution against its tests with the built-in judge before anything leaves your machine.

4. Submit / publish — submit for a real verdict, or (with approval) publish a draft to a contest.

What you can do

• Browse & read problems — list a contest's problems with full statements, constraints, I/O formats, time/memory limits, tags, and sample test cases.

• Explore contests — list upcoming/ongoing/past contests, view details, check and manage your registrations, get invite links.

• Submit & track — submit a solution for a real verdict, read your submission history, and pull a contest's ranking, results and announcements.

• Ratings — page and filter the global leaderboard by country / name / tier.

• Courses & blog — list courses and posts; manage course editors/metadata (with the right permissions).

• Community — read/send direct messages, manage conversations and blocks, read and mark notifications.

• Interviews & Vive — read mock-interview pricing/capacity/sessions; view Vive earn methods and create a Vive checkout link.

• Account — who am I, profile, update country, search users, sign out.

• Author for production — create problem drafts in Repovive's editor and fill in statement, tests, model solution, editorial and validator; generate and verify whole rounds; judge solutions locally — see Authoring.

Submitting code

repovive_submit_solution submits to POST /api/code/submit and polls until the verdict is final — a real submission recorded on your account. Verify locally first with repovive_judge_solution; Repovive rate-limits submissions to roughly 10 per minute.

repovive_submit_solution(contest_id="<24-hex>", problem_slug="remainder-count",
                         source=..., language="pypy")
#  -> {"submissionId": "...", "status": "Accepted", "passed": 18, "total": 18}

Language ids for submission follow the Judge0 set (python 71, pypy 220, cpp 54, java 62, …), which differs from the problem editor's own ids — the tool maps names for you. repovive_list_my_submissions lists your submission history.

Notes. The curated problem sets (Classics / FAANG / Quant / Math) are premium content served only through the website, so their problem lists are not available via the API — repovive_list_problem_sets returns their metadata and website URLs; for API-readable problems use contests (repovive_list_contest_problems). A problem like/dislike vote endpoint exists but keys on browser-URL identifiers that can't be resolved reliably from the public API, so it is intentionally not exposed.

Quick start

cd repovive-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .                       # fastmcp>=3 and httpx

export REPOVIVE_EMAIL="you@example.com"
export REPOVIVE_PASSWORD="your-password"
python -m repovive_mcp                  # stdio transport (or: repovive-mcp)

Then point your MCP client at it (see below) and try repovive_whoami or repovive_list_contests. Prefer containers? docker compose up --build serves the same server over HTTP on :8000 (endpoint /mcp).

Install

Requires Python ≥ 3.10.

cd repovive-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .          # installs fastmcp>=3 and httpx
# dev extras (pytest): pip install -e ".[dev]"

Run it directly (stdio transport):

export REPOVIVE_EMAIL="you@example.com"
export REPOVIVE_PASSWORD="your-password"
python -m repovive_mcp          # or: repovive-mcp

Configure your MCP client

Add a server entry. Example (Claude Desktop claude_desktop_config.json / Claude Code mcp config):

{
  "mcpServers": {
    "repovive": {
      "command": "python",
      "args": ["-m", "repovive_mcp"],
      "env": {
        "REPOVIVE_EMAIL": "you@example.com",
        "REPOVIVE_PASSWORD": "your-password"
      }
    }
  }
}

If you installed into a virtualenv, point command at that interpreter (e.g. /path/to/.venv/bin/python) or use the repovive-mcp console script.

Tool reference

All tools are prefixed repovive_. Read tools accept response_format (markdown default, or json) where a summary view is useful. The list below is grouped by area; the always-current, auto-generated reference is docs/TOOLS.md.

Account & profile (7)

Problems (4)

Contests & ratings (12)

Standings & results (4)

Submissions (3)

Content — courses & blog (8)

Community — notifications & DMs (14)

Interviews & Vive (5)

Authoring & judge — local (11)

Problem editor — build sessions (25)

Drafts are not visible on the platform until reviewed; publishing is the separate repovive_build_add_to_contest call. Details in docs/AUTHORING.md.

Authoring & local judge

The server can generate complete problems, build full contests, and evaluate them with a local judge — offline, with no writes to the live platform. Every generated problem's expected outputs are computed by running its reference solution, so it is correct by construction; repovive_build_contest(..., verify=True) judges every reference solution and only reports success when all are Accepted.

repovive_build_house_round(title="Repovive Starter Round 8")
  -> {round, verification: {all_passed: true, ...}}   # 7 problems, house-style, all AC

When you're ready to put a draft into Repovive's editor, the build-session tools write everything and leave publishing to you:

Verified example artifacts live in examples/ (12 problems, 4 contests). Full details in docs/AUTHORING.md. A ready-to-use agent skill is in skills/repovive-contest-dev/.

Repovive house style

The generators and the skill follow Repovive's measured conventions — read from all 98 published problems and 23 contests, and exposed as the repovive://house-style resource:

• Problems are multi-test (every problem starts with t), use a braced-array input format, a markdown-bullet constraints list, exactly one sample holding several sub-cases, and one explanation paragraph per sub-case. Memory limit 256 MB; time limits 1–2 s.

• Rounds are 7 problems (A–G) on the 500…3500 points ladder with the difficulty curve easy, easy, medium, medium, medium, hard, hard, 120 minutes, tags drawn from a fixed 12-word vocabulary.

repovive_check_house_style validates a problem against these rules, and repovive_build_house_round assembles a whole conforming round and verifies every problem.

Resources & prompts

Resources (read via URI) — 10, one templated: repovive://me, repovive://profile, repovive://contests, repovive://contests/{contest_id}/problems (templated), repovive://problem-sets, repovive://leaderboard, repovive://posts, repovive://courses, repovive://notifications, repovive://house-style.

Prompts (parameterised workflows) — 8: solve_problem, prepare_for_contest, study_plan, analyze_leaderboard, inbox_triage, build_repovive_round, problemset_contest, author_and_verify_problem.

Example agent session

A typical "solve a real problem" loop chains a handful of tools:

1. repovive_list_contests(status="ongoing")            # find a contest id
2. repovive_list_contest_problems(contest_id=…)        # pick a problem slug
3. repovive_get_problem(contest_id=…, problem_slug=…)  # statement + samples
4. …write a solution…
5. repovive_judge_solution(problem=…, source=…)        # local check → Accepted
6. repovive_submit_solution(contest_id=…, problem_slug=…, source=…, language="pypy")
   # -> {"status": "Accepted", "passed": 18, "total": 18}
7. repovive_get_contest_ranking(contest_id=…)          # see where you land

How auth works

• With REPOVIVE_EMAIL + REPOVIVE_PASSWORD, the server logs in on first use, keeping both the JWT bearer token and the auth_token session cookie (some routes need the cookie). It re-authenticates automatically on a 401 and caches the token (REPOVIVE_TOKEN_CACHE) to avoid login rate limits.

• With REPOVIVE_TOKEN only, it uses the bearer token (cookie-gated routes may not work).

• The server sends a descriptive User-Agent and standard Origin header, exactly like any first-party API client.

Deployment

Runs over stdio (local) or HTTP (REPOVIVE_MCP_TRANSPORT=http, endpoint /mcp). Docker, Docker Compose, Kubernetes (kustomize), Helm, OpenTofu/Terraform, Ansible, and Vagrant paths are all provided under deploy/ and the root Docker/Vagrant files.

docker compose up --build            # HTTP on :8000
# or: helm install rv deploy/helm/repovive-mcp --set credentials.email=... --set credentials.password=...
# or: kubectl apply -k deploy/kubernetes   (after creating the secret)

Full guide: docs/DEPLOYMENT.md. Handy targets in the Makefile (make help) and a Taskfile.yml for go-task (task --list).

Project layout

repovive-mcp/
├── repovive_mcp/          the server package
│   ├── app.py             shared FastMCP instance + RepoviveClient
│   ├── client.py          async httpx client (login, re-auth, token cache)
│   ├── tools_*.py         tool groups (account, contests, submit, build, …)
│   ├── resources.py       MCP resources        prompts.py   MCP prompts
│   ├── authoring.py housestyle.py templates_house.py production.py   local authoring
│   ├── localjudge.py      Judge0-style subprocess judge
│   └── server.py          registers everything; stdio or HTTP
├── scripts/gen_tools_doc.py   regenerates docs/TOOLS.md from the decorators
├── diagrams/generate.py       renders docs/diagrams/*.png via `diagrams`
├── docs/                  architecture, tools, authoring, deployment, api map, security
├── deploy/                docker, kubernetes, helm, opentofu, ansible
├── examples/              verified problems & contests
├── skills/                repovive-contest-dev agent skill
└── tests/                 smoke, offline authoring, and live e2e tests

Documentation

• docs/ARCHITECTURE.md — components + diagrams

• docs/TOOLS.md — full tool reference (auto-generated)

• docs/AUTHORING.md — problem/contest generation + local judge

• docs/DEPLOYMENT.md — Docker/K8s/Helm/OpenTofu/Ansible/Vagrant

• docs/API_MAP.md — the Repovive endpoints the tools use

• docs/SECURITY.md — credentials, boundaries, judge sandboxing

• skills/repovive-contest-dev/ — production contest-development skill

• CONTRIBUTING.md · ROADMAP.md · CHANGELOG.md

Development & tests

pip install -e ".[dev]"
# Live tests require real credentials and are skipped without them:
REPOVIVE_EMAIL=... REPOVIVE_PASSWORD=... pytest -q
make test-offline        # or: task test:offline  (no credentials needed)
make docs                # regenerate docs/TOOLS.md from the @mcp.tool decorators

tests/test_smoke.py boots the server in-memory (fastmcp.Client(mcp)), lists tools/resources/prompts, and exercises representative read tools plus error handling. docs/TOOLS.md is generated by scripts/gen_tools_doc.py (CI can enforce freshness with --check).

Security notes

• Credentials come only from environment variables — never hard-code them.

• Treat the JWT/cookie as secrets; they grant access to your account. The token cache lives outside the repo (REPOVIVE_TOKEN_CACHE, default /tmp).

• Write tools (submission, DMs, registration, deletes, course/contest admin) perform real actions; their annotations (destructiveHint, etc.) let clients gate them appropriately.

• Authoring writes drafts; publishing a draft to a live contest is a separate, explicit call. See docs/SECURITY.md.