feat(scheduler-agent): Phase 1 write operations — submit/cancel/hold/release + templates

Add write operations to the scheduler-agent MCP server (Phase 1):

- schedulerclient: SubmitJob/CancelJob/HoldJob/ReleaseJob + JobSpec/
  SubmitJobResult/JobControlRequest/ControlResult types + doPost helper
  (HTTP 200 + envelope-code dual check). TDD: 12 new tests.
- mcp-server: 4 write tools (scheduler_submit/cancel/hold/release) with
  destructive annotations; scheduler_submit has dry_run review mode +
  general_serial (通用串行脚本) job template registry. Fix the 6 read-only
  tools' misleading destructive annotations. TDD: 14 new tests.

Co-Authored-By: Claude <noreply@anthropic.com>

src/frontend/mcp-server/cmd/main.go

@@ -29,11 +29,14 @@ func main() {
 
 	s := mcps.NewMCPServer(
 		"scheduler-agent",
-		"0.1.0",
+		"0.2.0",
 		mcps.WithResourceCapabilities(true, true),
 		mcps.WithLogging(),
 	)
 
+	// Read-only tools are annotated as such so the MCP client does not prompt
+	// for confirmation on them (NewTool defaults to destructive=true).
+
 	// ── scheduler_list_jobs ──
 	s.AddTool(mcp.NewTool("scheduler_list_jobs",
 		mcp.WithDescription("List jobs in the cluster. Supports filtering by queue, owner, status, and pagination."),
@@ -42,6 +45,8 @@ func main() {
 		mcp.WithString("status", mcp.Description("Filter by status: pending|running|succeeded|failed|cancelled|suspended|unknown")),
 		mcp.WithNumber("limit", mcp.Description("Max results to return")),
 		mcp.WithString("page_token", mcp.Description("Pagination token from a prior response")),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleListJobs)
 
 	// ── scheduler_get_job ──
@@ -51,16 +56,22 @@ func main() {
 			mcp.Description("Job ID"),
 			mcp.Required(),
 		),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleGetJob)
 
 	// ── scheduler_list_queues ──
 	s.AddTool(mcp.NewTool("scheduler_list_queues",
 		mcp.WithDescription("List all queues/partitions and their current state (active, inactive, draining)."),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleListQueues)
 
 	// ── scheduler_list_nodes ──
 	s.AddTool(mcp.NewTool("scheduler_list_nodes",
 		mcp.WithDescription("List all compute nodes with their resource usage and status."),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleListNodes)
 
 	// ── scheduler_job_logs ──
@@ -72,13 +83,68 @@ func main() {
 		),
 		mcp.WithNumber("tail", mcp.Description("Number of lines from the end to return (0 = all)")),
 		mcp.WithNumber("offset_bytes", mcp.Description("Byte offset to start reading from")),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleJobLogs)
 
 	// ── scheduler_cluster_metrics ──
 	s.AddTool(mcp.NewTool("scheduler_cluster_metrics",
 		mcp.WithDescription("Get a snapshot of overall cluster resource usage and utilization."),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithDestructiveHintAnnotation(false),
 	), app.HandleClusterMetrics)
 
+	// ── write tools (Phase 1) ──
+	// Write tools are annotated destructive so the MCP client (e.g. Claude
+	// Code) prompts the user for confirmation before executing them — the
+	// design doc's "写操作默认 require confirm" at the layer MCP supports it.
+
+	// ── scheduler_submit ──
+	s.AddTool(mcp.NewTool("scheduler_submit",
+		mcp.WithDescription("Submit a job. REVIEW REQUIRED: call with dry_run=true first to inspect the resolved job spec, then re-call with dry_run=false to actually submit."),
+		mcp.WithString("template", mcp.Description("Job template (default 'general_serial' 通用串行脚本)."),
+			mcp.Enum(internal.TemplateGeneralSerial), mcp.DefaultString(internal.TemplateGeneralSerial)),
+		mcp.WithBoolean("dry_run", mcp.Description("Review mode: validate and return the resolved job spec without submitting."), mcp.DefaultBool(false)),
+		mcp.WithString("command", mcp.Description("Shell command to run (required)."), mcp.Required()),
+		mcp.WithString("name", mcp.Description("Job name; array syntax 'myjob[1-10]' supported.")),
+		mcp.WithString("queue", mcp.Description("Queue (default 'normal').")),
+		mcp.WithString("project", mcp.Description("Project name.")),
+		mcp.WithNumber("cores", mcp.Description("Number of processors.")),
+		mcp.WithString("walltime", mcp.Description("Walltime limit 'HH:MM', e.g. '02:30'.")),
+		mcp.WithString("memory", mcp.Description("Memory limit, e.g. '4 GB', '2048 MB'.")),
+		mcp.WithString("cwd", mcp.Description("Working directory.")),
+		mcp.WithString("env", mcp.Description("Comma-separated KEY=VALUE environment variables.")),
+		mcp.WithString("out_file", mcp.Description("Standard output file.")),
+		mcp.WithString("err_file", mcp.Description("Standard error file.")),
+		mcp.WithString("description", mcp.Description("Job description.")),
+		mcp.WithReadOnlyHintAnnotation(false),
+		mcp.WithDestructiveHintAnnotation(true),
+	), app.HandleSubmitJob)
+
+	// ── scheduler_cancel ──
+	s.AddTool(mcp.NewTool("scheduler_cancel",
+		mcp.WithDescription("Cancel (kill) a job by ID. Destructive — you will be asked to confirm before execution."),
+		mcp.WithString("id", mcp.Description("Job ID to cancel"), mcp.Required()),
+		mcp.WithReadOnlyHintAnnotation(false),
+		mcp.WithDestructiveHintAnnotation(true),
+	), app.HandleCancelJob)
+
+	// ── scheduler_hold ──
+	s.AddTool(mcp.NewTool("scheduler_hold",
+		mcp.WithDescription("Hold (suspend/stop) a job by ID. Destructive — you will be asked to confirm before execution."),
+		mcp.WithString("id", mcp.Description("Job ID to hold"), mcp.Required()),
+		mcp.WithReadOnlyHintAnnotation(false),
+		mcp.WithDestructiveHintAnnotation(true),
+	), app.HandleHoldJob)
+
+	// ── scheduler_release ──
+	s.AddTool(mcp.NewTool("scheduler_release",
+		mcp.WithDescription("Release (resume) a held job by ID. Destructive — you will be asked to confirm before execution."),
+		mcp.WithString("id", mcp.Description("Job ID to release"), mcp.Required()),
+		mcp.WithReadOnlyHintAnnotation(false),
+		mcp.WithDestructiveHintAnnotation(true),
+	), app.HandleReleaseJob)
+
 	log.Printf("Starting scheduler-agent MCP server (base-url: %s)", baseURL)
 	if err := mcps.ServeStdio(s); err != nil {
 		log.Fatalf("server error: %v", err)