codeforces-mcp

Un servidor MCP que da a los agentes de programación acceso a los datos de práctica de Codeforces. Te ayuda a entender tus etiquetas débiles y a encontrar problemas que aún no has resuelto.

El servidor es solo de lectura, utiliza la API pública de Codeforces y no requiere autenticación de Codeforces. Funciona con VS Code Copilot, Claude Desktop/Code y otros clientes MCP compatibles con servidores stdio.

Características

• Encontrar problemas por rating y etiqueta, excluyendo opcionalmente los problemas ya resueltos de un usuario.

• Clasificar las etiquetas de un handle por tasa de resolución y rating medio de los problemas resueltos.

• Revisar los envíos recientes y filtrar por veredicto.

• Consultar el perfil de un usuario y su historial de rating.

• Listar los próximos concursos.

• Devolver los resultados como Markdown legible o JSON estructurado.

• Guardar en caché local las respuestas del servidor y aplicar una frecuencia de peticiones razonable.

Related MCP server: cf-mcp-orange

Requisitos

• Python 3.10 o superior

• Un handle de Codeforces para las herramientas específicas de usuario

• VS Code con el modo Agente de GitHub Copilot, Claude u otro cliente compatible con MCP

No se requiere ninguna clave API.

Instalación

Clona el repositorio y crea un entorno virtual:

git clone https://github.com/<owner>/codeforces-mcp.git
cd codeforces-mcp
python -m venv .venv

Activa el entorno:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

Instala el paquete:

python -m pip install -e .

Para desarrollo, instala también las dependencias de test y lint:

python -m pip install -e ".[dev]"

La instalación crea el comando codeforces-mcp en el entorno virtual.

Uso con VS Code Copilot

El repositorio incluye una configuración de espacio de trabajo en .vscode/mcp.json. En Windows, puede apuntar directamente al venv del repositorio clonado:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "E:\\path\\to\\codeforces-mcp\\.venv\\Scripts\\codeforces-mcp.exe"
    }
  }
}

Sustituye la ruta por la ubicación real de tu clon. Para macOS/Linux, usa:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "/path/to/codeforces-mcp/.venv/bin/codeforces-mcp"
    }
  }
}

En VS Code:

1. Ejecuta MCP: Open Workspace Folder Configuration desde la paleta de comandos.

2. Añade o actualiza la entrada del servidor codeforces.

3. Abre el chat de Copilot y cambia al modo Agent.

4. Abre el menú de herramientas, inicia o habilita el servidor codeforces y permite el uso de las herramientas.

Después pide a Copilot algo como:

Encuentra 5 problemas de DP no resueltos con rating 1300-1500 para el handle 3.141f.

El servidor usa stdio, por lo que VS Code lo inicia y lo detiene cuando lo necesita. No inicies una segunda copia manualmente mientras Copilot esté conectado.

Uso con Claude

Después de activar el venv, registra el comando con Claude Code:

claude mcp add codeforces -- codeforces-mcp

Si el comando no está en tu PATH, usa el ejecutable directamente.

claude mcp add codeforces -- .\.venv\Scripts\codeforces-mcp.exe

El comando equivalente en macOS/Linux es:

claude mcp add codeforces -- .venv/bin/codeforces-mcp

Herramientas

Todas las herramientas son de solo lectura y admiten response_format, que puede ser "markdown" (el valor por defecto) o "json".

codeforces_search_problems

Encuentra problemas, primero los más fáciles. Configura exclude_solved_by para ocultar los problemas cuyo veredicto para ese handle sea OK.

Ejemplo de petición:

Find 5 unsolved dp problems rated 1300-1500 for 3.141f.

Argumentos equivalentes:

{
  "min_rating": 1300,
  "max_rating": 1500,
  "tags": ["dp"],
  "exclude_solved_by": "3.141f",
  "limit": 5
}

codeforces_tag_performance

Calcula para cada etiqueta los intentos, los problemas resueltos, la tasa de resolución y el rating de un handle. Los resultados se ordenan de la tasa de resolución más baja a la más alta. min_attempted evita que muestras muy pequeñas dominen la clasificación.

{
  "handle": "3.141f",
  "min_attempted": 8,
  "response_format": "markdown"
}

codeforces_recent_submissions

Lista los envíos más recientes de un handle. Usa verdict con valores como WRONG_ANSWER, TIME_LIMIT_EXCEEDED u OK para filtrar la lista.

{
  "handle": "3.141f",
  "verdict": "WRONG_ANSWER",
  "limit": 10
}

codeforces_user_profile

Muestra el rating actual, el rating máximo, el rango y la organización de un handle.

{
  "handle": "3.141f"
}

codeforces_rating_history

Muestra los cambios de rating concurso a concurso, primero los más antiguos. Define limit para devolver solo los concursos más recientes.

{
  "handle": "3.141f",
  "limit": 10
}

codeforces_upcoming_contests

Lista los concursos que aún no han comenzado, primero los más próximos.

{
  "limit": 5
}

Ejemplo de salida

**5 of 208 matching problems** (offset 0, more available)

| Rating | Problem | Tags | Link |
| --- | --- | --- | --- |
| 1300 | 189A - Cut Ribbon | brute force, dp | https://codeforces.com/problemset/problem/189/A |
| 1300 | 234C - Weather | dp, implementation | https://codeforces.com/problemset/problem/234/C |
| 1300 | 416B - Art Union | brute force, dp, implementation | https://codeforces.com/problemset/problem/416/B |

El json mw:El formato JSON contiene los mismos datos tipados para las aplicaciones que necesiten procesar el resultado programáticamente. (Note: oops, I inserted "El json mw" incorrectly; should be "El formato JSON contains..." Let's handle carefully.)

I'll rewrite cleanly:

Ejemplo de salida

**5 of 208 matching problems** (offset 0, more available)

| Rating | Problem | Tags | Link |
| --- | --- | --- | --- |
| 1300 | 189A - Cut Ribbon | brute force, dp | https://codeforces.com/problemset/problem/189/A |
| 1300 | 234C - Weather | dp, implementation | https://codeforces.com/problemset/problem/234/C |
| 1300 | 416B - Art Union | brute force, dp, implementation | https://codeforces.com/problemset/problem/416/B |

El formato JSON contiene los mismos datos tipados para las aplicaciones que necesiten procesar el resultado programáticamente.

Caché y límites de frecuencia

La API de Codeforces documenta aproximadamente una solicitud cada dos segundos. El cliente aplica un límite de frecuencia y guarda las respuestas en ~/.cache/codeforces-mcp por defecto. La caducidad de la caché refleja la frecuencia con la que cambian los datos: seis horas para el compendio de problemas, cinco minutos para los envíos y una hora para los perfiles de usuario.

Solución de problemas

El servidor no arranca

Comprueba que el ejecutable existe en el entorno que usa tu configuración de MCP:

Test-Path .\.venv\Scripts\codeforces-mcp.exe

./.venv/bin/codeforces-mcp

Si instalaste en otro venv, actualiza la ruta de command en mcp.json.

Codeforces devuelve un error

Comprueba la ortografía del handle e inténtalo de nuevo más tarde. El servidor envía al cliente los comentarios de error accionables de Codeforces. La API pública también puede estar temporalmente limitada o no disponible por límite de frecuencia.

Desarrollo

Ejecuta las comprobaciones deterministas antes de enviar un cambio:

ruff check .
mypy src/
pytest tests/contract -q
python eval/run_eval.py

Las pruebas en vivo llaman a Codeforces y son optativas:

pytest -m live -q

Reescribir fechas de commmits locales

The repo includes rebase... In Spanish: "El repositorio incluye rebase-commits-to-july.sh para reescribir todos los commits de la rama actual con fechas del 14 y 15 de julio de 2026. Crea una rama de copia de seguridad antes de modificar el historial:"

bash rebase-commits-to-july.sh

El árbol de trabajo debe estar limpio y el script debe ejecutarse desde una rama con nombre. El script reescribe los IDs de los commits, por lo que no lo uses en una rama compartida sin coordinación. Para restaurar el punto original, usa la rama de respaldo que imprime el script:

git reset --hard backup/pre-date-rebase-<timestamp>

Lee SPEC.md antes de cambiar el comportamiento de la herramienta. Allí se definen los contratos y criterios de aceptación, y cada criterio tiene una prueba de contrato correspondiente.

Estructura del proyecto

Cómo contribuir

1. Abre una issue para reportar un error o proponer un cambio de comportamiento.

2. Actualiza SPEC.md y su prueba de contrato antes de cambiar el comportamiento.

3. Mantén la lógica de herramientas en src/codeforces_mcp/tools/ libre de imports de MCP.

4. Ejecuta las comprobaciones de desarrollo e incluye la salida relevante de las pruebas en la pull request.

Por favor, evita hacer commit de entornos virtuales, cachés, artefactos de compilación o grabaciones de API que contengan datos personales. El .gitignore del repositorio ya excluye los artefactos de desarrollo local creados por este proyecto.

Documentación relacionada

• SPEC.md - contratos de herramientas y decisiones de diseño

• docs/TECHNICAL-OVERVIEW.md - arquitectura y detalles de implementación