ClassDojo Roster MCP

Неофициальный, локально-ориентированный сервер Model Context Protocol (MCP) для учителей, которым нужно просматривать списки учеников в Excel/XLSX, предварительно просматривать изменения, импортировать учеников в ClassDojo и проверять сохранённый список после этого. Он работает с любым MCP-клиентом, который может запустить локальный stdio-сервер, включая Claude Desktop, Codex, Cursor и VS Code.

[!ВАЖНО] Этот проект сообщества не связан с ClassDojo, не одобрен и не поддерживается им. Он использует сайт учителя ClassDojo с выполненным входом через локальный браузерный адаптер, поскольку официальный публичный API/MCP ClassDojo пока недоступен. Изменения в интерфейсе ClassDojo могут потребовать обновления адаптера.

Традиционный китайский документ: docs/README.zh-TW.md

Зачем нужен этот MCP-сервер

Поток массовой вставки ClassDojo может интерпретировать ведущее число как нумерацию списка, а не как часть отображаемого имени ученика. Этот сервер делает изменения списка проверяемыми и поддерживает два явных формата:

• seat_number_dot_name: создаёт имена, такие как 1.Student A, по одному, чтобы номер места сохранялся.

• name_only: использует более быстрый поток массовой вставки ClassDojo, когда номера мест не нужны; он отклоняется, если исходный класс содержит повторяющиеся имена.

Каждая запись требует свежий 15-минутный идентификатор предпросмотра и confirm: true. После сохранения сервер считывает класс обратно и сравнивает имена и количество.

Related MCP server: excel-mcp-server

Что он умеет

Инспектор рабочей книги не предполагает фиксированных имён листов или позиций столбцов. Он сканирует всю рабочую книгу на предмет распространённых китайских и английских заголовков класса/места/имени. Предпросмотр и проверка затем требуют явного непустого выбора sheetNames плюс сопоставления классов, что предотвращает молчаливое объединение агентом дублирующихся или несвязанных листов.

Безопасный рабочий процесс

1. Запустите classdojo_doctor.

2. Запустите classdojo_inspect_workbook и выберите нужный лист и обнаруженные блоки классов.

3. Запустите classdojo_preview_roster_import с явным studentNameFormat.

4. Проверьте сопоставления классов, количества, отсутствующие номера мест и добавления.

5. Только после одобрения человеком вызовите classdojo_apply_roster_import с возвращённым previewId и confirm: true.

6. Запустите classdojo_verify_roster_against_workbook для независимой проверки чтения обратно.

Все скриншоты содержат только синтетические данные.

Требования

• Node.js 20 или новее

• Chrome или другой браузер на Chromium с Chrome DevTools Protocol (CDP)

• Учётная запись учителя ClassDojo, в которую вы входите сами

• MCP-клиент, поддерживающий локальные stdio-серверы

MCP-сервер никогда не запрашивает пароль, cookie или API-токен ClassDojo.

Запуск локального браузерного адаптера

Используйте выделенный профиль браузера и войдите в ClassDojo в этом окне.

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"

Держите порт отладки на loopback. Любой, кто может получить доступ к конечной точке CDP, может управлять сессией браузера.

Установка в MCP-клиенте

Установите из публичного npm-пакета той же командой в каждом клиенте:

npx -y classdojo-mcp

Участники могут также клонировать этот репозиторий, выполнить npm ci && npm run build и заменить команду на node с абсолютным путём к dist/cli.js.

Claude Desktop и 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

Добавьте это в ~/.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"

Интерфейс клиента и расположение конфигурации меняются со временем; обратитесь к текущей документации клиента. Сам транспорт — стандартный MCP stdio и не специфичен для Codex.

Примеры входных данных инструментов

Сначала проверьте рабочую книгу:

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

Создайте предпросмотр с синтетическими сопоставлениями классов:

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

Применяйте только после просмотра предпросмотра:

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

Идентификаторы предпросмотра истекают через 15 минут, живут только в работающем процессе MCP и потребляются первой попыткой применения. Это снижает случайное повторное воспроизведение и дублирование импорта. Если один класс не удаётся, результат называет проверенные классы и классы, которые можно повторить после генерации нового предпросмотра.

Конфиденциальность и безопасность

• Разбор рабочей книги и автоматизация браузера выполняются локально на компьютере учителя.

• Проект не запускает размещённый MCP-сервис и не сохраняет учётные данные или списки учеников.

• Имена учеников могут проходить через выбранного MCP-клиента/поставщика ИИ. Изучите условия хранения и конфиденциальности этого поставщика перед использованием реальных данных учеников.

• Никогда не прикрепляйте реальные рабочие книги, скриншоты учеников, профили браузера, cookie или диагностические журналы, содержащие личные данные, к публичным проблемам.

• В v0.1.0 доступен только импорт списка. Баллы, посещаемость, сообщения, приглашения семей и другие функции ClassDojo намеренно недоступны.

См. docs/PRIVACY.md, SECURITY.md и модель угроз.

Устранение неполадок

Статус проекта и дорожная карта

Версия 0.1.x экспериментальная. Адаптер веб-интерфейса намеренно изолирован, чтобы будущий официальный API ClassDojo мог заменить его без изменения публичного рабочего процесса инструментов MCP.

Планируемые работы:

• дополнительные синтетические макеты рабочих книг и языковое покрытие

• матрица совместимости MCP-клиентов и смоук-тесты Inspector

• адаптер официального API, если ClassDojo предоставит ранний доступ

• дополнительные инструменты только для чтения только после проверки конфиденциальности и разрешений

Этот проект не будет реверс-инжинирить или обещать недокументированные REST-конечные точки ClassDojo как стабильный публичный API.

Разработка

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

Протокол stdio использует stdout; никогда не добавляйте вызовы console.log в сервер. Используйте stderr для диагностики. См. CONTRIBUTING.md перед открытием pull request.

Метаданные сообщества и релиз

• Имя в реестре MCP: io.github.Eason0in/classdojo-mcp

• npm-пакет: classdojo-mcp

• транспорт: stdio

• лицензия: MIT

server.json и package.json#mcpName намеренно соответствуют формату владения реестром MCP. Рабочий процесс релиза подготовлен для защищённой среды GitHub Actions, npm Trusted Publishing, provenance и MCP Registry OIDC; он не будет работать, пока сопровождающий явно не настроит среду release и издателя npm. В этом репозитории не должно быть долгоживущих npm-токенов.

Лицензия

MIT © Eason0in