Gradescope MCP Server

Instructions

Returns the full grading context for the next ungraded submission,
or a message that all submissions are graded.

Args:
    course_id: The current course ID.
    question_id: The current question ID.
    submission_id: The current Question Submission ID (optional).
        If omitted or invalid (e.g. a Global Submission ID), the tool
        will auto-discover a valid submission to navigate from.
    output_format: "markdown" (default) or "json".

Implementation Reference

• src/gradescope_mcp/tools/grading_ops.py:684-730 (handler)

  The core implementation of the get_next_ungraded logic.

  def get_next_ungraded(
      course_id: str, question_id: str, submission_id: str = "",
      output_format: str = "markdown",
  ) -> str:
      """Navigate to the next ungraded submission for the same question.
  
      Returns the grading context for the next ungraded submission,
      or a message if all submissions are graded.
  
      Args:
          course_id: The Gradescope course ID.
          question_id: The current question ID.
          submission_id: The current Question Submission ID (optional).
              If omitted or invalid, auto-discovers a valid submission.
              NOTE: This must be a Question Submission ID, not a Global
              Submission ID from get_assignment_submissions.
          output_format: "markdown" (default) or "json".
      """
      if not course_id or not question_id:
          return "Error: course_id and question_id are required."
  
      # Try the provided submission_id first; fall back to auto-discovery
      ctx = None
      if submission_id:
          try:
              ctx = _get_grading_context(course_id, question_id, submission_id)
          except ValueError as e:
              if "404" in str(e):
                  # Likely a Global Submission ID — fall back to auto-discovery
                  ctx = None
              else:
                  return f"Error: {e}"
          except AuthError as e:
              return f"Authentication error: {e}"
          except Exception as e:
              return f"Error: {e}"
  
      if ctx is None:
          # Auto-discover a valid question submission ID
          try:
              auto_sid = _find_question_submission_id(course_id, question_id)
              ctx = _get_grading_context(course_id, question_id, auto_sid)
          except AuthError as e:
              return f"Authentication error: {e}"
          except ValueError as e:
              return f"Error: {e}"
          except Exception as e:

• src/gradescope_mcp/server.py:483-501 (registration)

  The MCP tool registration and wrapper function for get_next_ungraded.

  @mcp.tool()
  def tool_get_next_ungraded(
      course_id: str, question_id: str, submission_id: str = "",
      output_format: str = "markdown",
  ) -> str:
      """Navigate to the next ungraded submission.
  
      Returns the full grading context for the next ungraded submission,
      or a message that all submissions are graded.
  
      Args:
          course_id: The current course ID.
          question_id: The current question ID.
          submission_id: The current Question Submission ID (optional).
              If omitted or invalid (e.g. a Global Submission ID), the tool
              will auto-discover a valid submission to navigate from.
          output_format: "markdown" (default) or "json".
      """
      return get_next_ungraded(course_id, question_id, submission_id, output_format)