Servidor MCP de ClassDojo Roster

Un servidor MCP (Model Context Protocol) no oficial, local-primero para docentes que necesitan inspeccionar listas de estudiantes en Excel/XLSX, previsualizar cambios, importar estudiantes a ClassDojo y verificar la lista guardada posteriormente. Funciona con cualquier cliente MCP que pueda lanzar un servidor stdio local, incluyendo Claude Desktop, Codex, Cursor y VS Code.

[!IMPORTANTE] Este proyecto comunitario no está afiliado, respaldado ni soportado por ClassDojo. Utiliza el sitio web de docentes de ClassDojo con sesión iniciada a través de un adaptador de navegador local porque aún no existe una API/MCP pública oficial de ClassDojo. Los cambios en la interfaz de ClassDojo pueden requerir una actualización del adaptador.

Documentación en chino tradicional: docs/README.zh-TW.md

Por qué existe este servidor MCP

El flujo de pegado masivo de ClassDojo puede interpretar un número inicial como numeración de lista en lugar de parte del nombre visible del estudiante. Este servidor mantiene los cambios de la lista revisables y admite dos formatos explícitos:

• seat_number_dot_name: crea nombres como 1.Student A uno a la vez para que se conserve el número de asiento.

• name_only: utiliza el flujo de pegado masivo más rápido de ClassDojo cuando no se necesitan números de asiento; se rechaza si una clase de origen contiene nombres duplicados.

Cada escritura requiere un ID de previsualización fresco de 15 minutos más confirm: true. Después de guardar, el servidor lee la clase nuevamente y compara nombres y recuentos.

Related MCP server: excel-mcp-server

Qué puede hacer

El inspector de libros de trabajo no asume nombres de hoja fijos ni posiciones de columna. Escanea todo el libro en busca de encabezados comunes de clase/asiento/nombre en chino e inglés. La previsualización y la verificación requieren entonces una selección explícita no vacía de sheetNames más asignaciones de clase, evitando que un Agente combine silenciosamente hojas duplicadas o no relacionadas.

Flujo de trabajo seguro

1. Ejecuta classdojo_doctor.

2. Ejecuta classdojo_inspect_workbook y selecciona la hoja prevista y los bloques de clase detectados.

3. Ejecuta classdojo_preview_roster_import con un studentNameFormat explícito.

4. Revisa las asignaciones de clase, recuentos, números de asiento faltantes y adiciones.

5. Solo después de la aprobación humana, llama a classdojo_apply_roster_import con el previewId devuelto y confirm: true.

6. Ejecuta classdojo_verify_roster_against_workbook para una verificación independiente de lectura posterior.

Todas las capturas de pantalla contienen solo datos sintéticos.

Requisitos

• Node.js 20 o más reciente

• Chrome u otro navegador Chromium con Chrome DevTools Protocol (CDP)

• Una cuenta de docente de ClassDojo en la que inicies sesión tú mismo

• Un cliente MCP que admita servidores stdio locales

El servidor MCP nunca solicita contraseña, cookie o token de API de ClassDojo.

Iniciar el adaptador de navegador local

Usa un perfil de navegador dedicado e inicia sesión en ClassDojo en esa ventana.

macOS

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Linux

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Windows PowerShell

& "$env:ProgramFiles\\Google\\Chrome\\Application\\chrome.exe" \`
  --remote-debugging-port=9222 \`
  --user-data-dir="$env:LOCALAPPDATA\\classdojo-mcp-chrome"

Mantén el puerto de depuración en loopback. Cualquiera que pueda alcanzar un endpoint CDP podría controlar su sesión de navegador.

Instalar en un cliente MCP

Instala desde el paquete npm público con el mismo comando en cada cliente:

npx -y classdojo-mcp

Los contribuyentes pueden alternativamente clonar este repositorio, ejecutar npm ci && npm run build y reemplazar el comando con node más la ruta absoluta a dist/cli.js.

Claude Desktop y Cursor

{
  "mcpServers": {
    "classdojo": {
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

VS Code

{
  "servers": {
    "classdojo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Codex

Añade esto a ~/.codex/config.toml:

[mcp_servers.classdojo]
command = "npx"
args = ["-y", "classdojo-mcp"]

[mcp_servers.classdojo.env]
CLASSDOJO_CDP_URL = "http://127.0.0.1:9222"

La interfaz de usuario del cliente y las ubicaciones de configuración cambian con el tiempo; consulta la documentación actual del cliente. El transporte en sí es MCP stdio estándar y no es específico de Codex.

Ejemplos de entradas de herramientas

Inspecciona un libro de trabajo primero:

{
  "workbookPath": "/absolute/path/to/students.xlsx"
}

Crea una previsualización con asignaciones de clase sintéticas:

{
  "workbookPath": "/absolute/path/to/students.xlsx",
  "sheetNames": ["Grade 5"],
  "studentNameFormat": "seat_number_dot_name",
  "includeStudentDetails": false,
  "mappings": [
    {
      "classdojoClassName": "503",
      "sourceClassName": "Grade 5 Class 3"
    }
  ]
}

Aplica solo después de revisar la previsualización:

{
  "previewId": "00000000-0000-4000-8000-000000000000",
  "confirm": true
}

Los IDs de previsualización expiran después de 15 minutos, viven solo en el proceso MCP en ejecución y se consumen en el primer intento de aplicación. Esto reduce la reproducción accidental y las importaciones duplicadas. Si una clase falla, el resultado nombra las clases verificadas y las clases que se pueden reintentar después de generar una nueva previsualización.

Privacidad y seguridad

• El análisis de libros de trabajo y la automatización del navegador se ejecutan localmente en la computadora del docente.

• El proyecto no ejecuta un servicio MCP alojado y no persiste credenciales ni listas de estudiantes.

• Los nombres de los estudiantes pueden pasar a través del cliente MCP/proveedor de IA seleccionado. Revisa las políticas de retención y privacidad de ese proveedor antes de usar datos reales de estudiantes.

• Nunca adjuntes libros de trabajo reales, capturas de pantalla de estudiantes, perfiles de navegador, cookies o registros de diagnóstico que contengan datos personales a un problema público.

• Solo la importación de listas es escribible en v0.1.0. Puntos, asistencia, mensajería, invitaciones familiares y otras características de ClassDojo no están disponibles intencionalmente.

Consulta docs/PRIVACY.md, SECURITY.md y el modelo de amenazas.

Solución de problemas

Estado del proyecto y hoja de ruta

La versión 0.1.x es experimental. El adaptador de interfaz web está aislado intencionalmente para que una futura API oficial de ClassDojo pueda reemplazarlo sin cambiar el flujo de trabajo público de las herramientas MCP.

Trabajo planificado:

• diseños de libros de trabajo sintéticos adicionales y cobertura de locales

• matriz de compatibilidad de clientes MCP y pruebas de humo con Inspector

• adaptador de API oficial si ClassDojo otorga acceso anticipado

• herramientas opcionales de solo lectura solo después de una revisión de privacidad y permisos

Este proyecto no realizará ingeniería inversa ni prometerá endpoints REST no documentados de ClassDojo como una API pública estable.

Desarrollo

npm ci
npm test
npm run build
npm audit --omit=dev
npm pack --dry-run

El protocolo stdio usa stdout; nunca agregues llamadas console.log al servidor. Usa stderr para diagnósticos. Consulta CONTRIBUTING.md antes de abrir una solicitud de extracción.

Metadatos comunitarios y publicación

• Nombre del registro MCP: io.github.Eason0in/classdojo-mcp

• Paquete npm: classdojo-mcp

• transporte: stdio

• licencia: MIT

server.json y package.json#mcpName coinciden intencionalmente con el formato de propiedad del registro MCP. El flujo de trabajo de publicación está preparado para un entorno protegido de GitHub Actions, npm Trusted Publishing, procedencia y OIDC del registro MCP; no es utilizable hasta que el mantenedor configure explícitamente el entorno release y el editor npm. No debe haber ningún token npm de larga duración en este repositorio.

Licencia

MIT © Eason0in