Gradescope MCP Server

Instructions

Returns current rubric items (with IDs), applied evaluations, score,
comments, point adjustment, navigation URLs (next/prev/ungraded),
and submission page images. Use this before applying grades.

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

Implementation Reference

• src/gradescope_mcp/server.py:380-394 (handler)

  The tool definition for `tool_get_submission_grading_context` which acts as an entry point in the MCP server.

  def tool_get_submission_grading_context(
      course_id: str, question_id: str, submission_id: str
  ) -> str:
      """Get full grading context for a question submission.
  
      Returns current rubric items (with IDs), applied evaluations, score,
      comments, point adjustment, navigation URLs (next/prev/ungraded),
      and submission page images. Use this before applying grades.
  
      Args:
          course_id: The Gradescope course ID.
          question_id: The question ID.
          submission_id: The question submission ID.
      """
      return get_submission_grading_context(course_id, question_id, submission_id)

• src/gradescope_mcp/tools/grading_ops.py:87-150 (handler)

  The core implementation function `get_submission_grading_context` that fetches and processes grading context from Gradescope.

  def get_submission_grading_context(
      course_id: str,
      question_id: str,
      submission_id: str,
      output_format: str = "markdown",
  ) -> str:
      """Get the full grading context for a specific question submission.
  
      Returns the current rubric items, applied evaluations, score, comments,
      navigation URLs, and student info. This is what you need before grading.
  
      Args:
          course_id: The Gradescope course ID.
          question_id: The question ID.
          submission_id: The question submission ID (NOT the assignment submission ID).
          output_format: "markdown" (default) or "json" for structured output.
      """
      if not course_id or not question_id or not submission_id:
          return "Error: course_id, question_id, and submission_id are required."
  
      try:
          ctx = _get_grading_context(course_id, question_id, submission_id)
      except AuthError as e:
          return f"Authentication error: {e}"
      except ValueError as e:
          return f"Error: {e}"
      except Exception as e:
          return f"Error fetching grading context: {e}"
  
      props = ctx["props"]
      question = props.get("question", {})
      submission = props.get("submission", {})
      evaluation = props.get("evaluation", {})
      nav = props.get("navigation_urls", {})
  
      # Rubric items + evaluations
      rubric_items = props.get("rubric_items", [])
      evaluations = props.get("rubric_item_evaluations", [])
      applied_ids = {e["rubric_item_id"] for e in evaluations if e.get("present")}
  
      # Navigation parsing — filter out self-referencing ungraded links
      # (Gradescope sets next_ungraded/previous_ungraded to the current
      # submission when it is itself ungraded, which misleads agents)
      nav_parsed = {}
      for label, key in [
          ("previous_ungraded", "previous_ungraded"),
          ("next_ungraded", "next_ungraded"),
          ("previous_submission", "previous_submission"),
          ("next_submission", "next_submission"),
          ("previous_question", "previous_question"),
          ("next_question", "next_question"),
      ]:
          url = nav.get(key, "")
          if url:
              qid_m = re.search(r"/questions/(\d+)", url)
              sid_m = re.search(r"/submissions/(\d+)", url)
              if qid_m and sid_m:
                  parsed_sid = sid_m.group(1)
                  # Skip self-referencing ungraded links
                  if key in ("previous_ungraded", "next_ungraded") and parsed_sid == submission_id:
                      continue
                  nav_parsed[label] = {
                      "question_id": qid_m.group(1),
                      "submission_id": parsed_sid,