Gradescope MCP Server

Instructions

Returns page URLs in priority order:
- Tier 1: Crop region only (read FIRST)
- Tier 2: Full page (if answer overflows crop)
- Tier 3: Adjacent pages (if still incomplete)

Also returns confidence score and recommended action.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    question_id: The question ID.
    submission_id: The question submission ID.

Implementation Reference

• src/gradescope_mcp/tools/grading_workflow.py:726-761 (handler)

  The core implementation of the smart_read_submission tool logic.

  def smart_read_submission(
      course_id: str,
      assignment_id: str,
      question_id: str,
      submission_id: str,
  ) -> str:
      """Get a smart, tiered reading plan for a student's submission.
  
      Returns page image URLs in priority order:
      1. **Tier 1 (Crop Only):** The crop region URLs for the question's designated area.
         Agent should read ONLY this first. If the answer is fully contained, grade it.
      2. **Tier 2 (Full Page):** If handwriting exits the crop boundary or reasoning
         appears truncated, read the full page(s) containing the crop.
      3. **Tier 3 (Adjacent Pages):** If the answer still appears incomplete, read the
         previous and next pages.
  
      Also returns the confidence score to decide whether to auto-grade or skip.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
          question_id: The question ID.
          submission_id: The question submission ID.
      """
      if not course_id or not assignment_id or not question_id or not submission_id:
          return "Error: all four IDs are required."
  
      try:
          questions = _fetch_assignment_questions(course_id, assignment_id)
          ctx = _get_grading_context(course_id, question_id, submission_id)
          prompt_text, explanation = _extract_outline_prompt_and_reference(
              course_id, assignment_id, question_id,
          )
      except AuthError as e:
          return f"Authentication error: {e}"
      except (ValueError, Exception) as e:

• src/gradescope_mcp/server.py:704-728 (registration)

  Tool registration for tool_smart_read_submission, which wraps the smart_read_submission helper function.

  @mcp.tool()
  def tool_smart_read_submission(
      course_id: str,
      assignment_id: str,
      question_id: str,
      submission_id: str,
  ) -> str:
      """Get a smart, tiered reading plan for a student's submission.
  
      Returns page URLs in priority order:
      - Tier 1: Crop region only (read FIRST)
      - Tier 2: Full page (if answer overflows crop)
      - Tier 3: Adjacent pages (if still incomplete)
  
      Also returns confidence score and recommended action.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
          question_id: The question ID.
          submission_id: The question submission ID.
      """
      return smart_read_submission(
          course_id, assignment_id, question_id, submission_id
      )