[!IMPORTANT] 이 프로젝트는 D2L 또는 SMU가 부과한 인증 및 제한을 우회하거나 무력화하려고 시도하지 않습니다. Chrome을 통한 적절한 인증을 수행한 후 D2L API를 직접 사용하는 방식을 선택합니다. 이 프로젝트는 SMU 또는 D2L과 어떠한 연관도 없습니다. 문제가 있으면 저에게 직접 연락하거나 이슈를 생성해 주세요.

SMU eLearn MCP

SMU의 D2L Brightspace 배포를 위한 로컬, 읽기 전용 Model Context Protocol 서버입니다. 강좌, 고정된 강좌, 주별 모듈, 강좌 문서, 최근 업로드/변경 사항, 콘텐츠 검색, 메타데이터 및 파일 다운로드를 제공합니다.

로컬, 단일 사용자 stdio 서비스입니다. 네트워크 서버로 노출하거나 여러 사용자 간에 공유하도록 설계되지 않았습니다.

이 MCP를 사용하는 가장 좋은 방법은 Codex 또는 Claude를 통하는 것이며, 이를 위해 설치 가능한 플러그인을 plugin-package/ 폴더 아래에 패키징해 두었습니다.

기능

구현은 D2L의 문서화된 읽기 전용 API 경로를 사용합니다. 표시되는 홈페이지를 스크래핑하지 않으며 강좌, 고정 상태, 제출물, 성적, 메시지 또는 콘텐츠를 수정하지 않습니다.

Related MCP server: D2L Brightspace MCP Server

요구 사항

• Node.js 22 이상

• Google Chrome

• eLearn 접근 권한이 있는 SMU 계정

설치 및 인증

cd elearn-mcp
npm ci
npm run auth

npm run auth는 전용 Chrome 프로필을 엽니다. 일반적인 SMU Microsoft 로그인 및 MFA 절차를 완료하세요. 1분 후 명령이 자동으로 eLearn API를 확인하며, 로그인이 아직 진행 중이면 최대 5분 동안 15초마다 확인합니다. 성공하면 Playwright 브라우저 세션 상태를 저장하고, 상태 파일 권한을 소유자 전용(0600)으로 제한한 후 Chrome을 닫습니다. 터미널 입력은 필요하지 않습니다.

프로필은 기본적으로 ~/.elearn-mcp/browser-profile에, 저장된 상태는 기본적으로 ~/.elearn-mcp/storage-state.json에 생성됩니다. 상태에는 세션 쿠키가 포함되며 출처 범위의 웹 스토리지가 포함될 수 있으므로 두 위치 모두 비밀로 취급하세요. 커밋, 동기화 또는 공유하지 마십시오. MCP는 비밀번호나 MFA 응답을 요구하거나 저장하지 않습니다.

유형 안전성, 단위 테스트, 깨끗한 프로덕션 빌드를 확인하세요:

npm run check

인증 후 완전한 라이브 MCP 테스트를 실행하세요:

npm run test:full

전체 실행은 타입 검사와 단위 테스트를 수행하고, 프로덕션 서버를 빌드하며, MCP stdio를 통해 연결하여 11개 도구 전체를 라이브 eLearn 데이터로 검증합니다. 또한 실제 파일 하나를 격리된 운영체제 임시 디렉터리에 다운로드하고, 파일을 확인한 후 finally 정리에서 임시 디렉터리를 제거합니다. eLearn의 데이터를 제출하거나 변경하지 않습니다.

MCP 클라이언트 구성

먼저 프로젝트를 빌드한 다음, 컴파일된 stdio 서버를 시작하도록 MCP 클라이언트를 구성하세요:

{
  "mcpServers": {
    "smu-elearn": {
      "command": "node",
      "args": [
        "/absolute/path/to/elearn-mcp/dist/src/server.js"
      ],
      "env": {
        "ELEARN_BASE_URL": "https://elearn.smu.edu.sg",
        "ELEARN_LP_VERSION": "1.49",
        "ELEARN_LE_VERSION": "1.49",
        "ELEARN_COURSE_ORG_UNIT_TYPE_ID": "3"
      }
    }
  }
}

이 JSON의 정확한 위치는 MCP 클라이언트에 따라 다릅니다. 구성을 변경한 후 클라이언트를 다시 시작하세요.

프로덕션 런타임

서버는 고정된 의존성 집합으로 빌드됩니다. 테스트는 검증 중에 타입 검사되고 실행되지만 dist/ 및 배포 가능한 패키지에서는 제외됩니다.

최소한의 로컬 런타임을 위해서는:

npm ci
npm run check
npm prune --omit=dev
npm start

개발 의존성을 정리한 후에는 다시 빌드하거나 단위 테스트를 실행하기 전에 npm ci를 다시 실행하세요. 포함된 GitHub Actions 워크플로는 Node.js 22에서 동일한 고정 설치 및 검증을 수행합니다. 인증된 라이브 테스트는 대화형 SMU 계정과 MFA가 필요하므로 CI에서 제외됩니다.

Codex 및 Claude 플러그인 빌드

src/ 아래의 TypeScript 파일은 MCP 구현의 유일한 진실 소스입니다. Codex와 Claude Code는 별도의 플러그인 매니페스트와 MCP 실행 메타데이터를 사용하지만, 둘 다 동일하게 생성된 런타임을 받습니다:

plugin-package/
├── codex/smu-elearn/
│   ├── .codex-plugin/plugin.json
│   ├── .mcp.json
│   └── mcp/
└── claude/smu-elearn/
    ├── .claude-plugin/plugin.json
    ├── .mcp.json
    └── mcp/

두 개의 새롭고 자체 포함된 플러그인 패키지를 빌드하려면 다음 명령을 실행하세요:

npm run build:plugins

npm run build:plugin은 동일한 명령의 별칭으로 유지됩니다. 빌드는 src/를 한 번 컴파일하고, 루트 잠금 파일에서 정확한 프로덕션 의존성 버전을 파생시키며, 격리된 스테이징 디렉터리에 프로덕션 의존성을 한 번 설치합니다. 그런 다음 각 mcp/ 디렉터리의 전체 스테이징 복사본이 검증된 후에만 해당 디렉터리를 교체합니다. 생성된 두 런타임을 수동으로 편집하지 마세요.

Claude Code 개발을 위해서는 패키지를 직접 검증하고 로드하세요:

claude plugin validate ./plugin-package/claude/smu-elearn --strict
claude --plugin-dir ./plugin-package/claude/smu-elearn

Claude Code 내부에서 /mcp를 실행하여 번들된 서버를 확인하세요. 영구적인 로컬 설치를 위해서는 패키지를 빌드한 다음 이 저장소의 마켓플레이스를 추가하세요:

claude plugin marketplace add /absolute/path/to/elearn-mcp
claude plugin install smu-elearn@smu-local --scope user

마켓플레이스 카탈로그는 .claude-plugin/marketplace.json에 저장됩니다. Claude는 완전한 패키지를 플러그인 캐시로 복사하므로 설치 전에 생성된 mcp/ 런타임이 존재해야 합니다. 개발 중에는 캐시를 피하고 패키지를 제자리에서 로드하려면 --plugin-dir을 사용하세요.

구성

주차 해석 방법

• elearn_get_week_documents는 week를 강좌의 학사 콘텐츠 모듈(예: Week 3)로 해석합니다. 중첩된 하위 모듈의 파일을 재귀적으로 포함합니다.

• elearn_get_recent_documents는 한 주를 달력 날짜 범위로 해석하고 토픽의 D2L LastModifiedDate로 필터링합니다. since와 until이 생략되면 현재 로컬 기준 월요일부터 일요일까지를 사용합니다.

이러한 구분은 의도적인 것입니다. "Week 3"에 저장된 파일은 다른 달력 주차에 업로드되었을 수도 있기 때문입니다.

인증 수명 주기

elearn_authenticate MCP 도구와 npm run auth 명령은 사용자 제어 SSO 및 MFA를 위해 전용 Chrome 프로필을 실행합니다. 첫 자동 확인 전에 1분간 기다리고, 필요하면 잠시 폴링한 후 D2L API를 검증하고 0600 권한의 Playwright 스토리지 상태 파일을 작성합니다. 서버는 해당 상태로 별도의 헤드리스 Chrome 컨텍스트를 실행하고 이를 통해 동일 출처 API 요청을 보냅니다. 이렇게 하면 SMU와 Microsoft의 대화형 인증 제어를 유지하면서 MCP 프로세스가 다시 시작될 수 있습니다. 기관 세션이 만료되면 elearn_authenticate를 호출하거나 npm run auth를 다시 실행하세요.

로컬 배포 경계, 자격 증명 처리 지침 및 릴리스 확인에 대해서는 SECURITY.md를 참조하세요.