brightspace

brightspace-mcp

📖 ドキュメントサイト全文 →

D2L Brightspace 用の MCP サーバーです。Claude（および MCP 対応クライアント）から、複数の認証方式、完全な MFA サポート、本番環境水準の耐障害性を備えた状態で、コース、成績、課題、コンテンツ、カレンダーなどにアクセスできます。

---

クイックスタート

npx brightspace-mcp@latest setup   # interactive wizard (recommended for first time)

対話型ウィザードですべてを設定できます。ベース URL、認証方式、MFA、認証情報の保存、Claude Desktop／Cursor／Windsurf への自動登録に対応しています。

CI パイプラインや TTY のない DevContainer では、代わりに非対話型の init コマンドを使用してください。

npx brightspace-mcp@latest init \
  --base-url https://yourschool.brightspace.com \
  --strategy api_token \
  --token-ref env:BRIGHTSPACE_API_TOKEN

---

ドキュメント

詳しいガイドは docs/ にあります。まずは docs/README.md をご覧ください。

トピック	ドキュメント
セットアップガイド	docs/setup-guide.md
認証方式	docs/auth-strategies.md
動作確認済みプリセット（Microsoft AAD など）	docs/presets.md
書き込み操作（提出、投稿、採点）	docs/writes.md
MCP ツールリファレンス	docs/tools.md
MCP リソース＋プロンプト	docs/tools.md#mcp-resources
トラブルシューティング	docs/troubleshooting.md
アーキテクチャ（DDD）	docs/architecture.md
MCP クライアントへの登録	docs/clients.md

AI アシスタントやコントリビューター向けに、AGENTS.md ではリポジトリの概要を1ページにまとめています。

---

目次

• インストール
• 認証方式
• MFA 方式
• 設定リファレンス
• 出力：タイムゾーンと言語
• Redis キャッシュ
• 書き込み操作
• 利用可能なツール
• MCP リソース
• MCP プロンプト
• TUI ダッシュボード
• MCP クライアントへの登録
• CLI リファレンス
• Docker

---

インストール

npx（推奨 — インストール不要）

npx brightspace-mcp@latest setup   # first-time wizard
npx brightspace-mcp@latest serve   # run the server

グローバルインストール

npm install -g brightspace-mcp
brightspace-mcp setup
brightspace-mcp serve

ソースからインストール

git clone https://github.com/JhostinAleck/brightspace-mcp.git
cd brightspace-mcp
npm install && npm run build
node build/cli/main.js serve

要件：Node.js ≥ 20。

最新の状態を保つ

• npx（推奨） — setup が書き込む MCP クライアント設定では npx --yes brightspace-mcp@latest serve を実行するため、クライアントを再起動するたびに最新リリースが使用されます。他に作業は必要ありません。
• グローバルインストール — npm install -g brightspace-mcp@latest（brightspace-mcp upgrade を実行すると npm を確認し、適切なコマンドを表示します）。
• Docker — 最新のイメージを docker pull し、コンテナを作り直してください。

サーバーは1日に最大1回 npm を確認します（タイムアウトは3秒、~/.brightspace-mcp/update-check.json にキャッシュ）。新しいバージョンがある場合、またはセキュリティ修正によりインストール済みバージョンが非推奨になった場合は、セッション中の最初のツール応答に通知が追加され、アシスタントから知らせてもらえます。この通知は get_diagnostics の update にも表示されます。確認を無効にするには BRIGHTSPACE_NO_UPDATE_CHECK=1 を設定してください。

---

認証方式

Brightspace の環境に合った方式を選んでください。npx brightspace-mcp@latest setup を実行すると、適切な方式を案内します。

API トークン（最も簡単）

Brightspace の管理パネルから取得した Valence API トークンが必要です。

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN

export BRIGHTSPACE_API_TOKEN="your-token"
npx brightspace-mcp@latest serve

ヘッドレス（ユーザー名＋パスワード）

ブラウザーウィンドウを表示せず、HTTP レベルのログインを自動化します。Duo Push を含む、すべての MFA 方式に対応しています。

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: headless
      headless:
        login_url: https://school.brightspace.com/d2l/login
        username_ref: env:BRIGHTSPACE_USERNAME
        password_ref: env:BRIGHTSPACE_PASSWORD
        mfa:
          strategy: duo_push     # or: totp, manual_prompt, none
          duo_push: {}           # uses defaults: poll every 1s, timeout 120s

ブラウザー（Playwright）

ヘッドレスの Chromium インスタンスを起動し、ログイン UI を自動操作します。ログインページに複雑な JavaScript がある SSO フロー（Microsoft Azure AD、SAML）に最適です。

npm install playwright && npx playwright install chromium

auth:
  strategy: browser
  browser:
    login_url: https://school.brightspace.com/d2l/login
    headless: true
    username_ref: env:BRIGHTSPACE_USERNAME
    password_ref: env:BRIGHTSPACE_PASSWORD
    selectors:
      username: "#i0116"
      password: "#i0118"
      submit: "#idSIButton9"
      password_submit: "#idSIButton9"
      mfa_input: "#idTxtBx_SAOTCC_OTC"
      mfa_submit: "#idSubmit_SAOTCC_Continue"
      post_login: "d2l-labs-navigation"
    mfa:
      strategy: totp
      totp:
        secret_ref: env:BRIGHTSPACE_TOTP_SECRET

セットアップウィザードには、すべてのセレクターを自動入力する Microsoft SSO プリセットが含まれています。

セッション Cookie

ブラウザーの DevTools から D2L セッション Cookie を貼り付けます。他の方式がブロックされる場合に便利です。

auth:
  strategy: session_cookie
  session_cookie:
    cookie_ref: env:BRIGHTSPACE_COOKIE
    session_ttl_seconds: 3600

# Cookie format: "d2lSessionVal=XXX; d2lSecureSessionVal=YYY"
export BRIGHTSPACE_COOKIE="d2lSessionVal=...; d2lSecureSessionVal=..."

---

MFA 方式

方式	使用する場面
none	アカウントで MFA を使用していない場合
totp	認証アプリ（Google Authenticator、Authy など）
duo_push	Duo Security — サーバーがモバイル端末での承認を自動的にポーリングします
manual_prompt	TOTP/OTP 全般 — サーバーが一時停止し、コードの貼り付けを求めます

TOTP の例

mfa:
  strategy: totp
  totp:
    secret_ref: env:BRIGHTSPACE_TOTP_SECRET   # base32 secret from QR code setup
    digits: 6       # 6 or 8
    period: 30      # seconds
    algorithm: SHA1 # SHA1, SHA256, or SHA512

Duo Push の例

mfa:
  strategy: duo_push
  duo_push:
    poll_interval_ms: 1000   # how often to check (default: 1000)
    timeout_ms: 120000       # give up after this many ms (default: 120000)

---

設定リファレンス

設定ファイル全体（~/.brightspace-mcp/config.yaml）：

default_profile: my_school

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token          # api_token | browser | headless | session_cookie | oauth
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN
    session:
      cache_backend: memory        # memory | file | redis
      preemptive_refresh_seconds: 300

output:
  tz: America/Bogota               # IANA timezone; default: auto-detected from system
  locale: es-419                   # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown                 # markdown (default) | plain
  include_meta_footer: true

logging:
  level: info                      # debug | info | warn | error

writes:
  enabled: false
  dry_run: false

# Optional — required when session.cache_backend: redis
redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"

認証情報の参照

秘密の値がプレーンテキストで保存されることはありません。実際の値を参照するには ref: 表記を使用してください。

プレフィックス	例	説明
env:NAME	env:BRIGHTSPACE_API_TOKEN	環境変数から読み込みます
keychain:service/account	keychain:brightspace-mcp/token	OS のキーチェーン（macOS Keychain、GNOME Keyring、Windows Credential Manager）
file:label	file:api_token	暗号化ファイル（~/.brightspace-mcp/credentials.enc、AES-256-GCM）

---

出力：タイムゾーンと言語

すべてのツール応答は、設定したタイムゾーンと言語でフォーマットされます。

output:
  tz: America/Bogota       # IANA name; default: auto-detected from system
  locale: es-419           # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown         # markdown (default) | plain
  include_meta_footer: true

brightspace-mcp setup を実行し、タイムゾーンと言語を選択してください。または、~/.brightspace-mcp/config.yaml で設定してください。

---

Redis キャッシュ

複数のインスタンスを実行する場合や、再起動後もキャッシュを保持する場合は、Redis を有効にしてください。

1. 設定に redis セクションを追加します：

redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"

profiles:
  my_school:
    session:
      cache_backend: redis

2. ioredis をインストールします（オプションの依存関係）：

npm install ioredis

3. Redis とサーバーを起動します：

docker run -d -p 6379:6379 redis:7-alpine
npx brightspace-mcp@latest serve

設定に redis: セクションがある場合、ドメインキャッシュ（コース、成績、課題など）は永続化レイヤーとして Redis を自動的に使用します。セッショントークンは、トークンの有効期限から算出した TTL とともに保存されます。

---

書き込み操作

書き込みツール（submit_assignment、post_discussion_reply、mark_announcement_read）はデフォルトで無効になっており、個別に 2 つのオプトインが必要です。

1. 設定ファイル：

writes:
  enabled: true
  dry_run: false   # set true to preview without mutating D2L

2. CLI フラグ：

npx brightspace-mcp@latest serve --enable-writes

すべての書き込み操作：

• クライアントが指定する idempotency_key（8～128 文字）が必要です。同じキーで繰り返し呼び出すと、再実行せずにキャッシュ済みの応答を返します。
• 相関 ID、ツール名、機密情報を伏せた引数を含む WARN レベルの監査ログを出力します。
• dry_run: true を指定すると、D2L に変更を加えずにプレビュー応答を返します。

---

利用可能なツール

読み取りツール（常に利用可能）

ツール	説明
check_auth	認証を確認し、現在のユーザー ID を表示します
list_my_courses	登録済みのすべてのコースを一覧表示します
get_my_grades	コースの成績を取得します
get_assignments	課題とドロップボックスフォルダーを一覧表示します
get_assignment_files	講師が投稿した課題ファイルをダウンロードして読み取ります
get_upcoming_due_dates	今後 N 日以内に期限を迎える課題を一覧表示します
get_feedback	課題の成績、講師のコメント、評価基準ごとのルーブリック結果を読み取ります
get_assignment_rubric	課題の採点ルーブリック（評価基準、レベル、点数、説明）を表示します
get_my_submissions	フォルダーの受付終了後も、自分（またはグループ）が提出したファイルを一覧表示してダウンロードします
get_syllabus	コースのシラバスを取得します
get_course_content	モジュールとトピックを参照します（トピック ID を含みます）
get_topic_file	コンテンツのトピックファイル（DOCX、PDF、HTML、プレーンテキスト）をダウンロードして読み取ります
get_announcements	コースのお知らせ（抜粋、作成者、添付ファイル）を一覧表示します
get_announcement	お知らせ全体、または添付ファイルのいずれかを読み取ります
get_discussions	ディスカッションフォーラムとスレッドを参照します
get_calendar_events	指定した期間のカレンダーイベントを一覧表示します
get_roster	コースの全受講者名簿を取得します
get_classlist_emails	クラスメートのメールアドレスを取得します
get_my_groups	コースごとのグループ登録情報とメンバー名簿を一覧表示します
list_quizzes	クイズを受験回数、制限時間、期限とともに一覧表示します
get_quiz_attempts	クイズの受験履歴をスコアとタイムスタンプとともに表示します
list_notifications	ユーザーのアクティビティフィード（お知らせ、期限のリマインダー、成績の公開）を表示します
search_course	コンテンツ、お知らせ、ディスカッションを全文検索します
get_audit_log	書き込み操作のローカル履歴（相関 ID、マスキング済み引数）を表示します
get_diagnostics	キャッシュ統計、サーキットブレーカーの状態、バージョン情報を表示します
clear_cache	メモリおよび永続キャッシュのバックエンドを消去します

書き込みツール（--enable-writes が必要）

ツール	説明
submit_assignment	Brightspace のドロップボックスフォルダーにファイルをアップロードします
post_discussion_reply	ディスカッションスレッドに返信します
mark_announcement_read	お知らせを既読にします

---

MCP リソース

Brightspace コンテンツ用の安定した URI が 4 つあります（resources/read を介して、あらゆる MCP クライアントが読み取れます）。

URI	内容
brightspace://{courseId}/syllabus	コースのシラバス。HTML を除去済み
brightspace://{courseId}/content/topics/{topicId}	トピックファイル（PDF からテキストを抽出。抽出できない場合は Base64 にフォールバック）
brightspace://{courseId}/assignments/{assignmentId}/files	すべての課題添付ファイルをテキストとして取得
brightspace://{courseId}/announcements/{announcementId}	お知らせのテキスト

list_my_courses、get_assignments、get_announcements などのツールから ID を取得できます。

---

MCP プロンプト

MCP クライアントのプロンプト選択画面で利用できる、事前構築済みのプロンプトテンプレートが 4 つあります。

プロンプト	引数	用途
weekly_briefing	なし	7 日間の概要：期限、お知らせ、最近の成績
grade_audit	course_id?	成績分析と、合格に必要な条件
study_planner	days_ahead?（デフォルト 7）	期限とカレンダーに基づく学習計画
course_summary	course_id（必須）	コースの全体概要

---

TUI ダッシュボード

brightspace-mcp tui            # launch full-screen terminal dashboard
brightspace-mcp tui --profile work  # use a specific profile

フルスクリーンのインタラクティブなターミナル UI（Ink + React）です。Tab / → / ← で 6 つのタブを切り替えます。

タブ	内容
Inicio	3 列のダッシュボード：今後の課題、7 日間のカレンダー予定、最近のお知らせ
Cursos	コース一覧をリアルタイム検索 → コースの詳細表示 → サブタブ「Tareas」／「Notas」／「Anuncios」
Calendario	すべてのアクティブなコースを対象とした、30 日間のイベント予定
Config	プロフィールの概要、項目ごとのフォームエディター（スキーマからドロップダウンを表示）、または使用するエディターで編集する設定ファイルのパスと検証
Caché	ヒット率、ミス数、クリアボタン
Logs	監査ログ（直近 50 件。ツール名で絞り込むには / を押します）

終了するには Ctrl+C を押します。

---

MCP クライアントへの登録

Claude Desktop、Cursor、Windsurf の設定例は docs/clients.md をご覧ください。または brightspace-mcp setup を実行すると、自動検出して登録できます。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "brightspace": {
      "command": "npx",
      "args": ["--yes", "brightspace-mcp@latest", "serve"],
      "env": {
        "BRIGHTSPACE_CONFIG": "/Users/you/.brightspace-mcp/config.yaml"
      }
    }
  }
}

---

CLI リファレンス

npx brightspace-mcp@latest setup                      Interactive first-time setup wizard (detects system language)
npx brightspace-mcp@latest init [flags]               Non-interactive config writer (CI/scripts, no TTY)
npx brightspace-mcp@latest serve                      Start the MCP server (stdio transport)
npx brightspace-mcp@latest serve --enable-writes      Start with write tools enabled
npx brightspace-mcp@latest tui                        Full-screen terminal dashboard (Ink TUI)
npx brightspace-mcp@latest auth                       Re-authenticate and test the config
npx brightspace-mcp@latest record-auth                Open browser for manual login, capture session cookies
npx brightspace-mcp@latest doctor                     End-to-end smoke test: config → auth → API → list_my_courses
npx brightspace-mcp@latest profile list               List profiles (* marks the default)
npx brightspace-mcp@latest profile use <name>         Switch the default profile
npx brightspace-mcp@latest config show                Print config (secrets redacted)
npx brightspace-mcp@latest config show --resolved     Show all secret refs as [redacted]
npx brightspace-mcp@latest config validate            Validate config schema without running
npx brightspace-mcp@latest config set <path> <value>  Edit a nested config value
npx brightspace-mcp@latest cache clear                Clear memory + file/Redis cache
npx brightspace-mcp@latest cache clear --context <n>  Clear a specific cache context
npx brightspace-mcp@latest upgrade                    Check npm and print the upgrade command

---

Docker

単体構成

docker pull ghcr.io/jhostinaleck/brightspace-mcp:latest
docker run --rm -i \
  -v "$HOME/.brightspace-mcp:/config:ro" \
  -e BRIGHTSPACE_CONFIG=/config/config.yaml \
  ghcr.io/jhostinaleck/brightspace-mcp:latest serve

Redis との併用（docker-compose）

# Start server + Redis
docker compose --profile redis up

# Or standalone (in-memory cache)
docker compose up

compose プロファイルを使用する場合、~/.brightspace-mcp/ 内の config.yaml で redis: セクションを redis://redis:6379 に設定する必要があります。

---

アーキテクチャの主な特徴

• 耐障害性：指数バックオフとジッターによる再試行、サーキットブレーカー（5 回失敗すると 30 秒間クールダウン）、リクエストの集約、バルクヘッド（同時リクエスト数は最大 5 件）
• キャッシュ層：HTTP レスポンスキャッシュ（L1、インメモリ、TTL は 60 秒）+ ドメインキャッシュ（L2、メモリからファイルまたは Redis へレイヤー化）
• セキュリティ：HTTPS のみのトランスポート、すべてのログ出力でシークレットを秘匿、OS キーチェーンとの統合、AES-256-GCM で暗号化された認証情報ファイル、セッショントークンは D2L トークンとともに失効
• DDD 構造：境界づけられたコンテキスト（assignments、authentication、calendar、communications、content、courses、grades、groups、notifications、quizzes）を設け、ドメイン／アプリケーション／インフラストラクチャを明確に分離

---

ライセンス

MIT © Jhostin Aleck