Canvas MCP Server

Instructions

    Create instructor-ready reports on peer review quality.

    Args:
        course_identifier: Canvas course code or ID
        assignment_id: Canvas assignment ID
        report_type: Report type (comprehensive, summary, individual)
        include_student_names: Whether to include student names
        format_type: Output format (markdown, html, text)
    

Implementation Reference

• src/canvas_mcp/tools/peer_review_comments.py:266-320 (handler)

  Main handler function implementing the 'generate_peer_review_feedback_report' tool. It fetches peer review analytics and problematic reviews using PeerReviewCommentAnalyzer, retrieves assignment info from Canvas API, and generates a markdown report.

  @mcp.tool()
  @validate_params
  async def generate_peer_review_feedback_report(
      course_identifier: str | int,
      assignment_id: str | int,
      report_type: str = "comprehensive",
      include_student_names: bool = False,
      format_type: str = "markdown"
  ) -> str:
      """
      Create instructor-ready reports on peer review quality.
  
      Args:
          course_identifier: Canvas course code or ID
          assignment_id: Canvas assignment ID
          report_type: Report type (comprehensive, summary, individual)
          include_student_names: Whether to include student names
          format_type: Output format (markdown, html, text)
      """
      try:
          course_id = await get_course_id(course_identifier)
          analyzer = PeerReviewCommentAnalyzer()
  
          # Get analytics data
          analytics_data = await analyzer.analyze_peer_review_quality(
              course_id=course_id,
              assignment_id=int(assignment_id)
          )
  
          if "error" in analytics_data:
              return f"Error getting analytics data: {analytics_data['error']}"
  
          # Get problematic reviews
          problematic_data = await analyzer.identify_problematic_peer_reviews(
              course_id=course_id,
              assignment_id=int(assignment_id)
          )
  
          # Get assignment info
          assignment_response = await make_canvas_request(
              "get",
              f"/courses/{course_id}/assignments/{assignment_id}"
          )
          assignment_name = assignment_response.get("name", "Unknown Assignment") if "error" not in assignment_response else "Unknown Assignment"
  
          # Generate report based on type
          if format_type.lower() == "markdown":
              return _generate_markdown_report(
                  analytics_data, problematic_data, assignment_name, report_type
              )
          else:
              return f"Error: Unsupported format '{format_type}'. Currently only 'markdown' is supported."
  
      except Exception as e:
          return f"Error in generate_peer_review_feedback_report: {str(e)}"

• src/canvas_mcp/tools/peer_review_comments.py:325-418 (helper)

  Supporting helper function that formats the peer review feedback into a comprehensive markdown report, including summaries, statistics, flagged issues, and recommendations.

  def _generate_markdown_report(
      analytics_data: dict[str, Any],
      problematic_data: dict[str, Any],
      assignment_name: str,
      report_type: str
  ) -> str:
      """Generate a markdown report from analytics data."""
  
      overall = analytics_data.get("overall_analysis", {})
      metrics = analytics_data.get("detailed_metrics", {})
      flagged = analytics_data.get("flagged_reviews", [])
      recommendations = analytics_data.get("recommendations", [])
  
      word_stats = metrics.get("word_count_stats", {})
      constructiveness = metrics.get("constructiveness_analysis", {})
      sentiment = metrics.get("sentiment_analysis", {})
  
      problematic_summary = problematic_data.get("flag_summary", {})
  
      report_lines = [
          f"# Peer Review Quality Report: {assignment_name}",
          "",
          f"**Generated on:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
          f"**Report Type:** {report_type.title()}",
          "",
          "## Executive Summary",
          "",
          f"- **Total Reviews Analyzed:** {overall.get('total_reviews_analyzed', 0)}",
          f"- **Average Quality Score:** {overall.get('average_quality_score', 0)}/5.0",
          f"- **High Quality Reviews:** {overall.get('quality_distribution', {}).get('high_quality', 0)}",
          f"- **Medium Quality Reviews:** {overall.get('quality_distribution', {}).get('medium_quality', 0)}",
          f"- **Low Quality Reviews:** {overall.get('quality_distribution', {}).get('low_quality', 0)}",
          "",
          "## Word Count Statistics",
          "",
          f"- **Average Words per Comment:** {word_stats.get('mean', 0)}",
          f"- **Median Words:** {word_stats.get('median', 0)}",
          f"- **Range:** {word_stats.get('min', 0)} - {word_stats.get('max', 0)} words",
          f"- **Standard Deviation:** {word_stats.get('std_dev', 0)}",
          "",
          "## Comment Quality Analysis",
          "",
          f"- **Constructive Feedback:** {constructiveness.get('constructive_feedback_count', 0)} reviews",
          f"- **Generic Comments:** {constructiveness.get('generic_comments', 0)} reviews",
          f"- **Specific Suggestions:** {constructiveness.get('specific_suggestions', 0)} reviews",
          "",
          "## Sentiment Distribution",
          "",
          f"- **Positive Sentiment:** {sentiment.get('positive_sentiment', 0)*100:.1f}%",
          f"- **Neutral Sentiment:** {sentiment.get('neutral_sentiment', 0)*100:.1f}%",
          f"- **Negative Sentiment:** {sentiment.get('negative_sentiment', 0)*100:.1f}%",
          ""
      ]
  
      if problematic_summary:
          report_lines.extend([
              "## Flagged Issues",
              "",
          ])
          for flag_type, count in problematic_summary.items():
              flag_name = flag_type.replace("_", " ").title()
              report_lines.append(f"- **{flag_name}:** {count} reviews")
          report_lines.append("")
  
      if flagged and report_type == "comprehensive":
          report_lines.extend([
              "## Sample Low-Quality Reviews",
              "",
          ])
          for i, review in enumerate(flagged[:5]):  # Show top 5
              report_lines.extend([
                  f"### Review {i+1}",
                  f"- **Quality Score:** {review.get('quality_score', 0)}/5.0",
                  f"- **Word Count:** {review.get('word_count', 0)}",
                  f"- **Flag Reason:** {review.get('flag_reason', 'Unknown')}",
                  f"- **Comment Preview:** \"{review.get('comment', 'No comment')}\"",
                  ""
              ])
  
      if recommendations:
          report_lines.extend([
              "## Recommendations",
              "",
          ])
          for i, rec in enumerate(recommendations, 1):
              report_lines.append(f"{i}. {rec}")
          report_lines.append("")
  
      report_lines.extend([
          "---",
          "*Generated by Canvas MCP Peer Review Comment Analyzer*"
      ])
  
      return "\n".join(report_lines)

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

  Invocation of the registration function that adds the 'generate_peer_review_feedback_report' tool (among others) to the MCP server during startup.

  register_peer_review_comment_tools(mcp)

• src/canvas_mcp/tools/peer_review_comments.py:17-322 (registration)

  Module-level registration function that defines and registers multiple peer review tools using @mcp.tool() decorators, including the target tool.

  def register_peer_review_comment_tools(mcp: FastMCP):
      """Register all peer review comment analysis MCP tools."""
  
      @mcp.tool()
      @validate_params
      async def get_peer_review_comments(
          course_identifier: str | int,
          assignment_id: str | int,
          include_reviewer_info: bool = True,
          include_reviewee_info: bool = True,
          include_submission_context: bool = False,
          anonymize_students: bool = False
      ) -> str:
          """
          Retrieve actual comment text for peer reviews on a specific assignment.
  
          Args:
              course_identifier: Canvas course code (e.g., badm_554_120251_246794) or ID
              assignment_id: Canvas assignment ID
              include_reviewer_info: Include reviewer student information
              include_reviewee_info: Include reviewee student information
              include_submission_context: Include original submission details
              anonymize_students: Replace student names with anonymous IDs
          """
          try:
              course_id = await get_course_id(course_identifier)
              analyzer = PeerReviewCommentAnalyzer()
  
              result = await analyzer.get_peer_review_comments(
                  course_id=course_id,
                  assignment_id=int(assignment_id),
                  include_reviewer_info=include_reviewer_info,
                  include_reviewee_info=include_reviewee_info,
                  include_submission_context=include_submission_context,
                  anonymize_students=anonymize_students
              )
  
              if "error" in result:
                  return f"Error getting peer review comments: {result['error']}"
  
              return json.dumps(result, indent=2)
  
          except Exception as e:
              return f"Error in get_peer_review_comments: {str(e)}"
  
      @mcp.tool()
      @validate_params
      async def analyze_peer_review_quality(
          course_identifier: str | int,
          assignment_id: str | int,
          analysis_criteria: str | None = None,
          generate_report: bool = True
      ) -> str:
          """
          Analyze the quality and content of peer review comments.
  
          Args:
              course_identifier: Canvas course code or ID
              assignment_id: Canvas assignment ID
              analysis_criteria: JSON string of custom analysis criteria (optional)
              generate_report: Whether to generate detailed analysis report
          """
          try:
              course_id = await get_course_id(course_identifier)
              analyzer = PeerReviewCommentAnalyzer()
  
              # Parse analysis criteria if provided
              criteria = None
              if analysis_criteria:
                  try:
                      criteria = json.loads(analysis_criteria)
                  except json.JSONDecodeError:
                      return "Error: analysis_criteria must be valid JSON"
  
              result = await analyzer.analyze_peer_review_quality(
                  course_id=course_id,
                  assignment_id=int(assignment_id),
                  analysis_criteria=criteria,
                  generate_report=generate_report
              )
  
              if "error" in result:
                  return f"Error analyzing peer review quality: {result['error']}"
  
              return json.dumps(result, indent=2)
  
          except Exception as e:
              return f"Error in analyze_peer_review_quality: {str(e)}"
  
      @mcp.tool()
      @validate_params
      async def identify_problematic_peer_reviews(
          course_identifier: str | int,
          assignment_id: str | int,
          criteria: str | None = None
      ) -> str:
          """
          Flag reviews that may need instructor attention.
  
          Args:
              course_identifier: Canvas course code or ID
              assignment_id: Canvas assignment ID
              criteria: JSON string of custom flagging criteria (optional)
          """
          try:
              course_id = await get_course_id(course_identifier)
              analyzer = PeerReviewCommentAnalyzer()
  
              # Parse criteria if provided
              parsed_criteria = None
              if criteria:
                  try:
                      parsed_criteria = json.loads(criteria)
                  except json.JSONDecodeError:
                      return "Error: criteria must be valid JSON"
  
              result = await analyzer.identify_problematic_peer_reviews(
                  course_id=course_id,
                  assignment_id=int(assignment_id),
                  criteria=parsed_criteria
              )
  
              if "error" in result:
                  return f"Error identifying problematic reviews: {result['error']}"
  
              return json.dumps(result, indent=2)
  
          except Exception as e:
              return f"Error in identify_problematic_peer_reviews: {str(e)}"
  
      @mcp.tool()
      @validate_params
      async def extract_peer_review_dataset(
          course_identifier: str | int,
          assignment_id: str | int,
          output_format: str = "csv",
          include_analytics: bool = True,
          anonymize_data: bool = True,
          save_locally: bool = True,
          filename: str | None = None
      ) -> str:
          """
          Export all peer review data in various formats for analysis.
  
          Args:
              course_identifier: Canvas course code or ID
              assignment_id: Canvas assignment ID
              output_format: Output format (csv, json, xlsx)
              include_analytics: Include quality analytics in output
              anonymize_data: Anonymize student data
              save_locally: Save file locally
              filename: Custom filename (optional)
          """
          try:
              course_id = await get_course_id(course_identifier)
              analyzer = PeerReviewCommentAnalyzer()
  
              # Get the comment data
              comments_data = await analyzer.get_peer_review_comments(
                  course_id=course_id,
                  assignment_id=int(assignment_id),
                  include_reviewer_info=True,
                  include_reviewee_info=True,
                  include_submission_context=True,
                  anonymize_students=anonymize_data
              )
  
              if "error" in comments_data:
                  return f"Error getting comments data: {comments_data['error']}"
  
              # Generate filename if not provided
              if not filename:
                  assignment_name = comments_data.get("assignment_info", {}).get("assignment_name", "assignment")
                  safe_name = "".join(c for c in assignment_name if c.isalnum() or c in (' ', '-', '_')).rstrip()
                  filename = f"peer_reviews_{safe_name}_{assignment_id}"
  
              # Include analytics if requested
              if include_analytics:
                  analytics_data = await analyzer.analyze_peer_review_quality(
                      course_id=course_id,
                      assignment_id=int(assignment_id)
                  )
                  if "error" not in analytics_data:
                      comments_data["quality_analytics"] = analytics_data
  
              # Export based on format
              if output_format.lower() == "json":
                  output_filename = f"{filename}.json"
                  if save_locally:
                      with open(output_filename, 'w', encoding='utf-8') as f:
                          json.dump(comments_data, f, indent=2, ensure_ascii=False)
                      return f"Data exported to {output_filename}"
                  else:
                      return json.dumps(comments_data, indent=2)
  
              elif output_format.lower() == "csv":
                  output_filename = f"{filename}.csv"
                  if save_locally:
                      with open(output_filename, 'w', newline='', encoding='utf-8') as f:
                          writer = csv.writer(f)
  
                          # Write header
                          writer.writerow([
                              'review_id', 'reviewer_id', 'reviewer_name', 'reviewee_id', 'reviewee_name',
                              'comment_text', 'word_count', 'character_count', 'timestamp'
                          ])
  
                          # Write data
                          for review in comments_data.get("peer_reviews", []):
                              reviewer = review.get("reviewer", {})
                              reviewee = review.get("reviewee", {})
                              content = review.get("review_content", {})
  
                              writer.writerow([
                                  review.get("review_id", ""),
                                  reviewer.get("student_id", ""),
                                  reviewer.get("student_name", ""),
                                  reviewee.get("student_id", ""),
                                  reviewee.get("student_name", ""),
                                  content.get("comment_text", ""),
                                  content.get("word_count", 0),
                                  content.get("character_count", 0),
                                  content.get("timestamp", "")
                              ])
  
                      return f"Data exported to {output_filename}"
                  else:
                      # Return CSV as string
                      csv_lines = []
                      csv_lines.append("review_id,reviewer_id,reviewer_name,reviewee_id,reviewee_name,comment_text,word_count,character_count,timestamp")
  
                      for review in comments_data.get("peer_reviews", []):
                          reviewer = review.get("reviewer", {})
                          reviewee = review.get("reviewee", {})
                          content = review.get("review_content", {})
  
                          # Escape quotes in comment text
                          comment_text = content.get("comment_text", "").replace('"', '""')
  
                          csv_lines.append(f'"{review.get("review_id", "")}","{reviewer.get("student_id", "")}","{reviewer.get("student_name", "")}","{reviewee.get("student_id", "")}","{reviewee.get("student_name", "")}","{comment_text}",{content.get("word_count", 0)},{content.get("character_count", 0)},"{content.get("timestamp", "")}"')
  
                      return "\n".join(csv_lines)
  
              else:
                  return f"Error: Unsupported output format '{output_format}'. Supported formats: csv, json"
  
          except Exception as e:
              return f"Error in extract_peer_review_dataset: {str(e)}"
  
      @mcp.tool()
      @validate_params
      async def generate_peer_review_feedback_report(
          course_identifier: str | int,
          assignment_id: str | int,
          report_type: str = "comprehensive",
          include_student_names: bool = False,
          format_type: str = "markdown"
      ) -> str:
          """
          Create instructor-ready reports on peer review quality.
  
          Args:
              course_identifier: Canvas course code or ID
              assignment_id: Canvas assignment ID
              report_type: Report type (comprehensive, summary, individual)
              include_student_names: Whether to include student names
              format_type: Output format (markdown, html, text)
          """
          try:
              course_id = await get_course_id(course_identifier)
              analyzer = PeerReviewCommentAnalyzer()
  
              # Get analytics data
              analytics_data = await analyzer.analyze_peer_review_quality(
                  course_id=course_id,
                  assignment_id=int(assignment_id)
              )
  
              if "error" in analytics_data:
                  return f"Error getting analytics data: {analytics_data['error']}"
  
              # Get problematic reviews
              problematic_data = await analyzer.identify_problematic_peer_reviews(
                  course_id=course_id,
                  assignment_id=int(assignment_id)
              )
  
              # Get assignment info
              assignment_response = await make_canvas_request(
                  "get",
                  f"/courses/{course_id}/assignments/{assignment_id}"
              )
              assignment_name = assignment_response.get("name", "Unknown Assignment") if "error" not in assignment_response else "Unknown Assignment"
  
              # Generate report based on type
              if format_type.lower() == "markdown":
                  return _generate_markdown_report(
                      analytics_data, problematic_data, assignment_name, report_type
                  )
              else:
                  return f"Error: Unsupported format '{format_type}'. Currently only 'markdown' is supported."
  
          except Exception as e:
              return f"Error in generate_peer_review_feedback_report: {str(e)}"
  
      print("Peer review comment analysis tools registered successfully!", file=sys.stderr)