ClassDojo Roster MCP

Excel/XLSX 학생 명단을 검사하고, 변경 사항을 미리 확인하고, 학생을 ClassDojo에 가져오고, 저장된 명단을 사후 검증해야 하는 교사를 위한 비공식, 로컬 우선 Model Context Protocol (MCP) 서버입니다. Claude Desktop, Codex, Cursor, VS Code를 포함하여 로컬 stdio 서버를 실행할 수 있는 모든 MCP 클라이언트에서 작동합니다.

[!IMPORTANT] 이 커뮤니티 프로젝트는 ClassDojo와 제휴, 보증, 지원 관계가 없습니다. 공식 공개 ClassDojo API/MCP가 아직 없기 때문에 로컬 브라우저 어댑터를 통해 로그인된 ClassDojo 교사 웹사이트를 사용합니다. ClassDojo UI 변경 시 어댑터 업데이트가 필요할 수 있습니다.

繁體中文文件：docs/README.zh-TW.md

이 MCP 서버가 존재하는 이유

ClassDojo의 대량 붙여넣기 흐름은 앞에 오는 숫자를 학생 표시 이름의 일부가 아닌 목록 번호로 해석할 수 있습니다. 이 서버는 명단 변경 사항을 검토 가능하게 유지하며 두 가지 명시적 형식을 지원합니다:

• seat_number_dot_name: 좌석 번호가 보존되도록 1.Student A와 같은 이름을 한 번에 하나씩 생성합니다.

• name_only: 좌석 번호가 필요하지 않을 때 ClassDojo의 더 빠른 대량 붙여넣기 흐름을 사용합니다. 소스 클래스에 중복 이름이 포함된 경우 거부됩니다.

모든 쓰기 작업에는 새로운 15분 미리보기 ID와 confirm: true가 필요합니다. 저장 후 서버는 클래스를 다시 읽어 이름과 수를 비교합니다.

Related MCP server: excel-mcp-server

할 수 있는 작업

워크북 검사기는 고정된 시트 이름이나 열 위치를 가정하지 않습니다. 전체 워크북에서 일반적인 중국어 및 영어 클래스/좌석/이름 헤더를 검사합니다. 그런 다음 미리보기와 검증에는 명시적인 비어 있지 않은 sheetNames 선택과 클래스 매핑이 필요하므로 에이전트가 중복되거나 관련 없는 시트를 조용히 결합하는 것을 방지합니다.

안전한 워크플로우

1. classdojo_doctor를 실행합니다.

2. classdojo_inspect_workbook을 실행하고 의도한 시트와 감지된 클래스 블록을 선택합니다.

3. 명시적인 studentNameFormat으로 classdojo_preview_roster_import를 실행합니다.

4. 클래스 매핑, 수, 누락된 좌석 번호, 추가 사항을 검토합니다.

5. 사람의 승인 후에만 반환된 previewId와 confirm: true로 classdojo_apply_roster_import를 호출합니다.

6. 독립적인 재읽기 확인을 위해 classdojo_verify_roster_against_workbook을 실행합니다.

모든 스크린샷에는 합성 데이터만 포함되어 있습니다.

요구 사항

• Node.js 20 이상

• Chrome DevTools Protocol (CDP)을 지원하는 Chrome 또는 다른 Chromium 브라우저

• 직접 로그인하는 ClassDojo 교사 계정

• 로컬 stdio 서버를 지원하는 MCP 클라이언트

MCP 서버는 ClassDojo 비밀번호, 쿠키, API 토큰을 요청하지 않습니다.

로컬 브라우저 어댑터 시작

전용 브라우저 프로필을 사용하고 해당 창에서 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"

디버깅 포트를 루프백에 유지하세요. 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"

클라이언트 UI와 구성 위치는 시간이 지남에 따라 변경됩니다. 클라이언트의 현재 문서를 참조하세요. 전송 방식 자체는 표준 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
}

미리보기 ID는 15분 후 만료되며 실행 중인 MCP 프로세스에서만 유효하고 첫 번째 적용 시도에서 소비됩니다. 이는 우발적인 재생 및 중복 가져오기를 줄입니다. 한 클래스가 실패하면 결과는 검증된 클래스와 새 미리보기를 생성한 후 재시도할 수 있는 클래스를 명명합니다.

개인정보 및 보안

• 워크북 파싱과 브라우저 자동화는 교사의 컴퓨터에서 로컬로 실행됩니다.

• 이 프로젝트는 호스팅된 MCP 서비스를 실행하지 않으며 자격 증명이나 학생 명단을 저장하지 않습니다.

• 학생 이름은 선택한 MCP 클라이언트/AI 제공업체를 통해 전달될 수 있습니다. 실제 학생 데이터를 사용하기 전에 해당 제공업체의 보존 및 개인정보 처리 방침을 검토하세요.

• 실제 워크북, 학생 스크린샷, 브라우저 프로필, 쿠키, 개인 데이터가 포함된 진단 로그를 공개 이슈에 첨부하지 마세요.

• v0.1.0에서는 명단 가져오기만 쓰기가 가능합니다. 포인트, 출석, 메시징, 가족 초대 및 기타 ClassDojo 기능은 의도적으로 사용할 수 없습니다.

docs/PRIVACY.md, SECURITY.md 및 위협 모델을 참조하세요.

문제 해결

프로젝트 상태 및 로드맵

버전 0.1.x는 실험적입니다. 웹 UI 어댑터는 의도적으로 격리되어 있어 향후 공식 ClassDojo API가 공개 MCP 도구 워크플로우를 변경하지 않고 대체할 수 있습니다.

계획된 작업:

• 추가 합성 워크북 레이아웃 및 로케일 지원

• MCP 클라이언트 호환성 매트릭스 및 Inspector 스모크 테스트

• ClassDojo가 Early Access를 승인하는 경우 공식 API 어댑터

• 개인정보 및 권한 검토 후에만 선택적 읽기 전용 도구

이 프로젝트는 문서화되지 않은 ClassDojo REST 엔드포인트를 안정적인 공개 API로 리버스 엔지니어링하거나 약속하지 않습니다.

개발

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

stdio 프로토콜은 stdout을 사용합니다. 서버에 console.log 호출을 추가하지 마세요. 진단에는 stderr를 사용하세요. 풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 참조하세요.

커뮤니티 메타데이터 및 릴리스

• MCP Registry 이름: io.github.Eason0in/classdojo-mcp

• npm 패키지: classdojo-mcp

• 전송 방식: stdio

• 라이선스: MIT

server.json과 package.json#mcpName은 의도적으로 MCP Registry 소유권 형식과 일치합니다. 릴리스 워크플로우는 보호된 GitHub Actions 환경, npm Trusted Publishing, provenance, MCP Registry OIDC를 위해 준비되어 있습니다. 유지관리자가 release 환경과 npm 게시자를 명시적으로 구성할 때까지 사용할 수 없습니다. 이 저장소에는 장기 npm 토큰이 없습니다.

라이선스

MIT © Eason0in