Canvas MCP Server

Instructions

    Args:
        course_identifier: Canvas course code (e.g., badm_554_120251_246794) or ID
        assignment_id: Canvas assignment ID
        priority_filter: Priority filter (urgent, medium, low, all)
        include_contact_info: Include email addresses if available
        days_threshold: Days since assignment for urgency calculation
    

Implementation Reference

• src/canvas_mcp/tools/peer_reviews.py:153-194 (handler)

  The primary handler function for the get_peer_review_followup_list MCP tool. Decorated with @mcp.tool() for registration and @validate_params for input validation. Handles course resolution, analyzer instantiation, calls the core logic, and formats JSON response or error.

  @mcp.tool()
  @validate_params
  async def get_peer_review_followup_list(
      course_identifier: str | int,
      assignment_id: str | int,
      priority_filter: str = "all",
      include_contact_info: bool = False,
      days_threshold: int = 3
  ) -> str:
      """Get prioritized list of students requiring instructor follow-up based on peer review completion status.
  
      Args:
          course_identifier: Canvas course code (e.g., badm_554_120251_246794) or ID
          assignment_id: Canvas assignment ID
          priority_filter: Priority filter (urgent, medium, low, all)
          include_contact_info: Include email addresses if available
          days_threshold: Days since assignment for urgency calculation
      """
      try:
          # Validate priority filter
          valid_priorities = ["urgent", "medium", "low", "all"]
          if priority_filter not in valid_priorities:
              return f"Error: priority_filter must be one of {valid_priorities}, got '{priority_filter}'"
  
          course_id = await get_course_id(course_identifier)
          analyzer = PeerReviewAnalyzer()
  
          result = await analyzer.get_followup_list(
              course_id=course_id,
              assignment_id=int(assignment_id),
              priority_filter=priority_filter,
              include_contact_info=include_contact_info,
              days_threshold=days_threshold
          )
  
          if "error" in result:
              return f"Error getting peer review followup list: {result['error']}"
  
          return json.dumps(result, indent=2)
  
      except Exception as e:
          return f"Error in get_peer_review_followup_list: {str(e)}"

• src/canvas_mcp/core/peer_reviews.py:467-582 (helper)

  Core implementation logic in PeerReviewAnalyzer.get_followup_list method. Computes prioritized followup lists by calling completion analytics, categorizes students by priority (urgent, medium, low), generates recommended actions, and handles contact info.

  async def get_followup_list(
      self,
      course_id: int,
      assignment_id: int,
      priority_filter: str = "all",
      include_contact_info: bool = False,
      days_threshold: int = 3
  ) -> dict[str, Any]:
      """Get prioritized list of students requiring instructor follow-up."""
  
      try:
          # Get completion analytics
          analytics = await self.get_completion_analytics(
              course_id, assignment_id, include_student_details=True
          )
  
          if "error" in analytics:
              return analytics
  
          # Get assignment info
          assignments_data = await self.get_assignments(course_id, assignment_id)
          if "error" in assignments_data:
              return assignments_data
  
          assignment_info = assignments_data["assignment_info"]
          completion_groups = analytics.get("completion_groups", {})
  
          # Calculate days since assignment
          days_since_assigned = days_threshold  # Default value
  
          # Process followup categories
          followup_categories = {
              "urgent": {
                  "description": "Students with 0 peer reviews completed",
                  "count": len(completion_groups.get("none_complete", [])),
                  "students": []
              },
              "medium": {
                  "description": "Students with partial completion",
                  "count": len(completion_groups.get("partial_complete", [])),
                  "students": []
              },
              "low": {
                  "description": "Students with all reviews completed - no action needed",
                  "count": len(completion_groups.get("all_complete", []))
              }
          }
  
          # Add urgent students
          for student in completion_groups.get("none_complete", []):
              student_data = {
                  "student_id": student["student_id"],
                  "student_name": student["student_name"],
                  "assigned_count": student["assigned_count"],
                  "completed_count": student["completed_count"],
                  "completion_rate": student["completion_rate"],
                  "days_since_assigned": days_since_assigned,
                  "pending_reviews": student.get("pending_reviews", []),
                  "recommended_action": "Send urgent reminder email"
              }
  
              if include_contact_info:
                  student_data["contact_email"] = "student@illinois.edu"  # Placeholder
  
              followup_categories["urgent"]["students"].append(student_data)
  
          # Add medium priority students
          for student in completion_groups.get("partial_complete", []):
              student_data = {
                  "student_id": student["student_id"],
                  "student_name": student["student_name"],
                  "assigned_count": student["assigned_count"],
                  "completed_count": student["completed_count"],
                  "completion_rate": student["completion_rate"],
                  "pending_reviews": student.get("pending_reviews", []),
                  "recommended_action": "Send gentle reminder"
              }
  
              if include_contact_info:
                  student_data["contact_email"] = "student@illinois.edu"  # Placeholder
  
              followup_categories["medium"]["students"].append(student_data)
  
          # Filter by priority if specified
          if priority_filter != "all":
              filtered_categories = {priority_filter: followup_categories.get(priority_filter, {})}
              followup_categories = filtered_categories
  
          # Generate recommended actions
          recommended_actions = {
              "immediate": [
                  f"Send urgent emails to {followup_categories.get('urgent', {}).get('count', 0)} students with zero completion"
              ],
              "this_week": [
                  f"Send automated reminder to {followup_categories.get('medium', {}).get('count', 0)} partial completion students",
                  "Review peer review timing for future assignments"
              ],
              "next_assignment": [
                  "Implement 48-hour buffer between due date and peer review assignment",
                  "Add peer review completion tracking to gradebook"
              ]
          }
  
          return {
              "generated_at": datetime.datetime.now().isoformat(),
              "assignment_info": {
                  "id": assignment_info["id"],
                  "name": assignment_info["name"],
                  "days_since_assigned": days_since_assigned
              },
              "followup_categories": followup_categories,
              "recommended_actions": recommended_actions
          }
  
      except Exception as e:
          return {"error": f"Exception in get_followup_list: {str(e)}"}

• src/canvas_mcp/server.py:52-52 (registration)

  Registration call to register_peer_review_tools(mcp) within the register_all_tools function, which triggers the @mcp.tool() decorators to register the get_peer_review_followup_list tool.

  register_peer_review_tools(mcp)