Gradescope MCP Server

Instructions

Returns a table of pending and completed regrade requests with student name,
question, grader, status, and identifiers for fetching details.
Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

Implementation Reference

• src/gradescope_mcp/tools/regrades.py:16-104 (handler)

  The handler function `get_regrade_requests` which fetches and parses the regrade requests page for an assignment.

  def get_regrade_requests(course_id: str, assignment_id: str) -> str:
      """List all regrade requests for an assignment.
  
      Returns a table of pending and completed regrade requests with student name,
      question, grader, and status. Requires instructor/TA access.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
      """
      if not course_id or not assignment_id:
          return "Error: course_id and assignment_id are required."
  
      try:
          conn = get_connection()
          url = (
              f"{conn.gradescope_base_url}/courses/{course_id}"
              f"/assignments/{assignment_id}/regrade_requests"
          )
          resp = conn.session.get(url)
      except AuthError as e:
          return f"Authentication error: {e}"
      except Exception as e:
          return f"Error fetching regrade requests: {e}"
  
      if resp.status_code != 200:
          return f"Error: Cannot access regrade requests (status {resp.status_code})."
  
      soup = BeautifulSoup(resp.text, "html.parser")
      table = soup.find("table")
      if not table:
          return f"No regrade requests found for assignment `{assignment_id}`. (Regrade requests may not be enabled.)"
  
      rows = table.find_all("tr")
      if len(rows) <= 1:
          return f"No regrade requests for assignment `{assignment_id}`."
  
      lines = [f"## Regrade Requests — Assignment {assignment_id}\n"]
      lines.append("| # | Status | Student | Question | Grader | Review Link |")
      lines.append("|---|--------|---------|----------|--------|-------------|")
  
      pending_count = 0
      completed_count = 0
  
      for i, row in enumerate(rows[1:], 1):
          cells = row.find_all("td")
          if len(cells) < 5:
              continue
  
          student = cells[0].text.strip()
          section = cells[1].text.strip()
          question = cells[2].text.strip()
          grader = cells[3].text.strip()
          completed = cells[4].text.strip()
  
          # Extract links for question_id and submission_id
          review_link = ""
          for a in row.find_all("a"):
              href = a.get("href", "")
              if "/grade" in href:
                  review_link = href
                  break
  
          # Extract IDs from review link
          qid_match = re.search(r"/questions/(\d+)", review_link)
          sid_match = re.search(r"/submissions/(\d+)", review_link)
          qid = qid_match.group(1) if qid_match else ""
          sid = sid_match.group(1) if sid_match else ""
  
          status = "✅" if completed else "⏳"
          if completed:
              completed_count += 1
          else:
              pending_count += 1
  
          id_info = f"qid={qid}, sid={sid}" if qid else ""
          lines.append(
              f"| {i} | {status} | {student} | {question} | {grader} | {id_info} |"
          )
  
      lines.append("")
      lines.append(f"**Pending:** {pending_count} | **Completed:** {completed_count} | **Total:** {pending_count + completed_count}")
      lines.append("")
      lines.append(
          "_Use `get_regrade_detail(course_id, question_id, submission_id)` to see "
          "the student's message and rubric for a specific request._"
      )
  
      return "\n".join(lines)

• src/gradescope_mcp/server.py:331-342 (registration)

  The MCP tool registration for `tool_get_regrade_requests`.

  def tool_get_regrade_requests(course_id: str, assignment_id: str) -> str:
      """List all regrade requests for an assignment.
  
      Returns a table of pending and completed regrade requests with student name,
      question, grader, status, and identifiers for fetching details.
      Requires instructor/TA access.
  
      Args:
          course_id: The Gradescope course ID.
          assignment_id: The assignment ID.
      """
      return get_regrade_requests(course_id, assignment_id)