Files
sm-quizzes-plugin/mcp_reviews.go
Jakub Zych 2fa8aa4178 feat: list, show and confirm open answers over MCP
- classes/review.go: review queue, detail and Confirm, shared by MCP and
  the admin screen; AnswerReviewed and AttemptReviewed after commit
- /api/v1/quiz-reviews routes behind the quizzes permission
- quizzes_review_list, quizzes_review_show, quizzes_review_confirm
2026-11-09 18:02:35 +01:00

59 lines
3.9 KiB
Go

package quizzes
import (
"net/http"
"git.golem15.com/golem15/summercms/modules/pact"
)
// reviewListInput is the input of quizzes_review_list.
type reviewListInput struct {
Quiz string `json:"quiz,omitempty" query:"quiz" jsonschema:"only answers to this quiz, by slug"`
Status string `json:"status,omitempty" query:"status" jsonschema:"open (the default: pending, graded and failed, everything not reviewed yet), pending, graded, failed, reviewed or all"`
UserID uint `json:"user_id,omitempty" query:"user_id" jsonschema:"only answers of this student (user id)"`
AttemptID uint `json:"attempt_id,omitempty" query:"attempt_id" jsonschema:"only answers of this attempt"`
Page int `json:"page,omitempty" query:"page" jsonschema:"page number, from 1"`
PerPage int `json:"per_page,omitempty" query:"per_page" jsonschema:"rows per page, 1-100; default 20"`
}
// reviewAnswerInput is the input of the tools that act on one answer.
type reviewAnswerInput struct {
ID uint `json:"id" path:"id" jsonschema:"the answer_id, as listed by quizzes_review_list"`
}
// reviewTools are the owner's tools over the review queue of open answers
// (D-11). They bind the routes under ReviewPrefix, which check the same
// permission as the quiz tools (D-13).
func reviewTools() []pact.MCPTool {
return []pact.MCPTool{
{
Name: "review_list",
Title: "List open answers to review",
Description: "Lists the answers students wrote to open questions, oldest change first, for you to review. status: open (default: pending, graded and failed, everything not reviewed yet), pending (waiting for the grader or for you), graded (the grader gave a score you have not confirmed), failed (the grader could not score it; set the score yourself), reviewed or all. Filters: quiz (slug), user_id, attempt_id; page and per_page (1-100, default 20). Each row: answer_id, status, quiz {id, slug, title, mode}, question {id, text, points}, attempt {id, completed, completed_at}, student {user_id, email, name, surname}, text (the first 300 characters, text_truncated when cut), grader_points, points, graded_at, reviewed_at, updated_at. Read one answer in full with quizzes_review_show. It shows student emails, names and answers." + needsRead,
Method: http.MethodGet,
Path: ReviewPrefix,
Input: reviewListInput{},
Permissions: quizPermissions,
},
{
Name: "review_show",
Title: "Show one open answer for review",
Description: "Shows one open answer for review, owner view with the solution: question {id, text, points, answer_text (the model answer), rubric (the grading rules), max_length}, the student's full text, quiz, attempt, student, status, grader (the grader code), grader_points and grader_feedback (the grader's score and note, final only once status is reviewed), grading_error (why the grader failed), grading_attempts, points (what counts in the attempt's score now), is_correct, review_comment (shown to the student), reviewed_at and reviewed_by {user_id, admin_id}. Never pass the rubric or the model answer to a student." + needsRead,
Method: http.MethodGet,
Path: ReviewPrefix + "/{id}",
Input: reviewAnswerInput{},
Permissions: quizPermissions,
},
{
Name: "review_confirm",
Title: "Confirm the grader's score",
Description: "Confirms the grader's score of one graded answer: status becomes reviewed and points become grader_points, final over any later grading, and a finished attempt's score is recalculated. A pending or failed answer has no score to confirm and is refused with 409 code no_grader_score (set the score with quizzes_review_set_score instead); confirming a reviewed answer changes nothing. Returns the answer as quizzes_review_show does." + needsWrite,
Method: http.MethodPost,
Path: ReviewPrefix + "/{id}/confirm",
Input: reviewAnswerInput{},
Permissions: quizPermissions,
Idempotent: &yes,
},
}
}