canvas-bulk-grading

Canvas 一括採点

ルーブリックに基づくワークフローを使って、Canvas LMS の課題を効率的に採点します。このスキルを使用するには、Canvas MCP サーバーが起動しており、教員または TA のトークンで認証されている必要があります。

前提条件

• Canvas MCP サーバーが起動し、接続されていること
• 教育者（教員／TA）の Canvas API トークンで認証されていること
• 課題が存在し、採点対象の提出物があること
• ルーブリックが作成され、use_for_grading=true を指定して課題に関連付けられていること。作成には create_rubric、既存のルーブリックには associate_rubric を使用します。テキストや点数の編集には update_rubric（プレビューとトークンの 2 回呼び出し）を使用します。評価基準の追加や削除は Canvas UI で行います。

ワークフロー

ステップ 1：課題とルーブリックの情報を取得する

採点を始める前に、課題の詳細とルーブリックの評価基準を取得します。

get_assignment_details(course_identifier, assignment_id)

次にルーブリックを取得します。すでに課題にリンクされている場合は get_rubric を使用し、コース内のすべてのルーブリックを確認するには list_rubrics を使用します。

get_rubric(course_identifier, assignment_id=assignment_id)
list_rubrics(course_identifier)
get_rubric(course_identifier, rubric_id=rubric_id)

ルーブリックの応答に含まれる評価基準 ID（多くの場合、_8027 のようにアンダースコアが先頭に付きます）と評価レベル IDを記録します。これらはルーブリックに基づく採点に必要です。

ステップ 2：提出物を一覧表示する

すべての学生の提出物を取得し、採点が必要な数を確認します。

list_submissions(course_identifier, assignment_id)

各提出物の user_id と workflow_state（submitted、graded、pending_review）を確認します。採点が必要な提出物の数を数え、使用する戦略を決定します。

ステップ 3：採点戦略を選択する

採点対象の提出物数に応じて、次の判断ツリーを使用します。

How many submissions need grading?
|
+-- 1-9 submissions
|   Use grade_with_rubric (one call per submission)
|
+-- 10-29 submissions
|   Use bulk_grade_submissions (concurrent batch processing)
|   Set max_concurrent: 5, rate_limit_delay: 1.0
|   Run with dry_run: true first (Safety Rule 1)
|
+-- 30+ submissions OR custom grading logic needed
    Use execute_typescript with bulkGrade function
    Grading logic runs locally; only selected output returns to the model
    Pass dryRun: true on the first run

戦略 A：個別採点（提出物 1～9 件）

学生ごとに grade_with_rubric を 1 回呼び出します。

grade_with_rubric(
  course_identifier,
  assignment_id,
  user_id,
  rubric_assessment: {
    "criterion_id": {
      "points": <number>,
      "rating_id": "<string>",    // optional
      "comments": "<string>"      // optional per-criterion feedback
    }
  },
  comment: "Overall feedback"     // optional
)

戦略 B：一括採点（提出物 10～29 件）

必ず最初にドライランを実行してください。 各ユーザー ID を採点データに対応付ける grades ディクショナリを作成し、送信前に検証します。

bulk_grade_submissions(
  course_identifier,
  assignment_id,
  grades: {
    "user_id_1": {
      "rubric_assessment": {
        "criterion_id": {"points": 85, "comments": "Good analysis"}
      },
      "comment": "Overall feedback"
    },
    "user_id_2": {
      "grade": 92,
      "comment": "Excellent work"
    }
  },
  dry_run: true,          // VALIDATE FIRST
  max_concurrent: 5,
  rate_limit_delay: 1.0
)

ドライランの出力を確認します。すべて問題がなければ、dry_run: false を指定して再実行します。

戦略 C：コード実行（提出物 30 件以上）

大規模なクラスや独自の採点ロジックを使用する場合は、execute_typescript を使ってローカルで採点を実行します。これにより、すべての提出物データを会話コンテキストに読み込まずに済みます。

execute_typescript(code: `
  import { bulkGrade } from './canvas/grading/bulkGrade.js';

  await bulkGrade({
    courseIdentifier: "COURSE_ID",
    assignmentId: "ASSIGNMENT_ID",
    dryRun: true,  // preview first; re-run with false after review
    gradingFunction: (submission) => {
      // Custom grading logic runs locally -- no token cost
      const notebook = submission.attachments?.find(
        f => f.filename.endsWith('.ipynb')
      );

      if (!notebook) return null; // skip ungraded

      return {
        points: 100,
        rubricAssessment: { "_8027": { points: 100 } }
        // No `comment` here on purpose -- see Safety Rule 6. Add one only when
        // the instructor asked for written feedback, and make it feedback.
      };
    }
  });
`)

コードを作成する前に、search_canvas_tools("grading", "signatures") を使用して、利用可能な TypeScript モジュールと関数シグネチャを確認します。

トークン効率

3 つの戦略では、トークンコストが大きく異なります。

戦略	対象	トークンコスト	理由
grade_with_rubric	提出物 1～9 件	低	往復が少なく、ペイロードも小さい
bulk_grade_submissions	提出物 10～29 件	中	バッチデータを使った 1 回の呼び出し
execute_typescript	提出物 30 件以上	作業量に依存	採点ロジックはローカルで実行され、コードと選択した出力だけをモデルコンテキストに含めればよい

重要なポイントは、提出物数が増えるほど、すべての提出物データを会話に取り込むより、採点ロジックをサーバーに送るほうがモデルコンテキストを少なくできることです。

安全ルール

1. 必ず最初にドライランを実行してください。 bulk_grade_submissions では、本番実行前に dry_run: true を設定します。出力が正しいことを確認してください。
2. 採点前にルーブリックを確認してください。 基準 ID、配点範囲、評価 ID が課題のルーブリックと一致していることを確認します。ID が一致していないと、エラーが通知されないまま失敗したり、誤った採点になったりします。
3. 一括処理の前に抜き取り確認を行ってください。 Strategy B と C では、まず grade_with_rubric を使って 1〜2 件を手動で採点します。Canvas で、評点とルーブリックのフィードバックが正しく表示されることを確認してください。
4. レート制限を守ってください。 max_concurrent: 5 と rate_limit_delay: 1.0（バッチ間隔は 1 秒）を使用します。Canvas のレート制限は、10 分あたり約 700 リクエストです。
5. 講師から明示的な確認を得ずに採点しないでください。 採点計画（ルーブリックの対応付け、配点、影響を受ける学生の人数）を必ず提示し、採点を送信する前に承認を待ってください。
6. 講師が求めていないコメントを添付しないでください。 提出物へのコメントは SpeedGrader で学生に表示されます。コメントは置き換えではなく呼び出しのたびに追加され、送信後に取り消すことはできません。「評点を 8 にする」という指示は、評点のみを意味します。評点を言い直したり、採点したことを説明したりするコメント（例：「自動レビューで採点しました」）は決して生成しないでください。これは学生には自分の提出物にボットの印を付けられたように受け取られ、フィードバックにもなりません。コメントを含めるのは、講師が文章によるフィードバックを求めた場合に限り、その際は提出物の内容についてのフィードバックにしてください。

プロンプト例

• 「ルーブリックを使って課題 5 を採点してください」
• 「中間プロジェクトのルーブリックを見せて、すべての提出物を採点してください」
• 「課題 3 の未採点の提出物をすべて一括採点してください。基準 1 は満点、基準 2 は 80% にしてください」
• 「期末レポートで、まだ採点が必要な提出物はいくつありますか？」
• 「提出前に確認できるよう、課題 7 の一括採点をドライランしてください」
• 「コード実行を使って、カスタムロジックで宿題の提出物 150 件をすべて採点してください」

エラーからの復旧

エラー	原因	対処
401 Unauthorized	トークンの期限切れまたは無効	Canvas API トークンを再生成します
403 Forbidden	このコースの講師または TA ではない	Canvas のロールを確認します
404 Not Found	コース、課題、またはルーブリック ID が間違っている	list_assignments または list_rubrics で ID を再確認します
422 Unprocessable	ルーブリック評価の形式が無効	基準 ID と配点範囲がルーブリックと一致していることを確認します
一括処理で部分的に失敗	一部の評点は送信されたが、残りは失敗した	各ステータスを確認します。確認できていない評価はすでに保存されている可能性があります。コメントの重複を避けるため、再試行する前に Canvas を確認してください。保存されていないことが確認できた失敗のみ再試行します