feat(mcp): expose mutations as tools (gated on confirm=true)

Adds seven mutating MCP tools that wrap the same primitives the CLI
mutation subcommands use, so a single MCP server gives an agent the
full read+write surface:

  cordon_node       k8s.SetCordon(want=true)
  uncordon_node     k8s.SetCordon(want=false)
  drain_node        k8s.DrainNode
  reboot_node       actions.SoftResetInstance   (--ocid bypass)
  terminate_node    actions.TerminateInstance   (--ocid bypass, DESTRUCTIVE)
  scale_gpu_pool    actions.IncreasePoolSize    (Terraform sourced)
  delete_dac        actions.DeleteDedicatedAICluster (DESTRUCTIVE, polls)

Each tool requires `confirm: true` to execute. The field is optional
at the JSON-Schema level (omitempty) so the SDK invokes the handler
even when confirm is missing — letting us audit-log the refused
attempt and emit a notifications/message explaining the contract,
in addition to surfacing a tool error. Both signals reach the
client whether it watches tool results or notifications.

Resolver flows mirror the CLI:
  - resolveNodeForOCIAction synthesizes a *GpuNode from --ocid or
    walks LoadGpuNodes for name lookup.
  - resolveGpuPoolForOCIAction does the LoadGpuPools +
    PopulateGpuPools dance to fill the OCID before scaling.

All upstream calls go through seam variables (mcpSetCordonFn etc.)
so tests don't touch a live cluster or OCI tenancy. The tests
mark the file non-parallel because seam swapping is inherently
shared state.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jingle2008

internal/mcp/integration_test.go

@@ -257,6 +257,7 @@ func TestIntegration_ToolsListAndCall(t *testing.T) {
 		got[tool.Name] = true
 	}
 	want := []string{
+		// Read-only list_* tools.
 		"list_tenants",
 		"list_base_models",
 		"list_gpu_pools",
@@ -269,6 +270,14 @@ func TestIntegration_ToolsListAndCall(t *testing.T) {
 		"list_tenancy_overrides",
 		"list_regional_overrides",
 		"list_aliases",
+		// Mutation tools (all gated on confirm=true; see mutations.go).
+		"cordon_node",
+		"uncordon_node",
+		"drain_node",
+		"reboot_node",
+		"terminate_node",
+		"scale_gpu_pool",
+		"delete_dac",
 	}
 	for _, name := range want {
 		assert.True(t, got[name], "tools/list missing %q (got %d tools total)", name, len(listRes.Tools))

internal/mcp/mutations.go

@@ -0,0 +1,323 @@
+package mcp
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	sdk "github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/jingle2008/toolkit/internal/infra/k8s"
+	"github.com/jingle2008/toolkit/internal/infra/terraform"
+	"github.com/jingle2008/toolkit/internal/ui/tui/actions"
+	"github.com/jingle2008/toolkit/pkg/infra/logging"
+	"github.com/jingle2008/toolkit/pkg/models"
+)
+
+// Seam variables — overrideable in tests so handlers don't reach a
+// live cluster or OCI tenancy. Production callers go through the
+// upstream packages directly.
+var (
+	mcpSetCordonFn          = k8s.SetCordon
+	mcpDrainNodeFn          = k8s.DrainNode
+	mcpSoftResetFn          = actions.SoftResetInstance
+	mcpTerminateFn          = actions.TerminateInstance
+	mcpIncreasePoolSizeFn   = actions.IncreasePoolSize
+	mcpDeleteDACFn          = actions.DeleteDedicatedAICluster
+	mcpPopulateGpuPoolsFn   = actions.PopulateGpuPools
+	mcpResolveCompartmentFn = mcpResolveCompartmentID
+)
+
+// confirmGate is embedded in every mutating tool's input. The field
+// is OPTIONAL at the JSON-Schema level (omitempty) so the SDK passes
+// the call to the handler even when confirm is missing — that way we
+// can audit-log the attempt and emit a notifications/message
+// explaining the contract. Only confirm=true triggers execution.
+type confirmGate struct {
+	Confirm bool `json:"confirm,omitempty" jsonschema:"set true to execute; otherwise the tool refuses without acting"`
+}
+
+// requireConfirm short-circuits with a uniform tool error when the
+// caller forgot to set confirm: true. Audit log captures the intent
+// so the refusal is visible alongside successful mutations.
+//
+// Returns (response, _, err, gated). When gated is true the caller
+// must return the first three values immediately.
+func (s *Server) requireConfirm(ctx context.Context, req *sdk.CallToolRequest, action, kind, target string, confirm bool) (*sdk.CallToolResult, struct{}, error, bool) {
+	if confirm {
+		return nil, struct{}{}, nil, false
+	}
+	s.logger.Infow("mutation refused (confirm=false)",
+		"action", action, "kind", kind, "target", target, "surface", "mcp",
+	)
+	notify(ctx, req.Session, "info",
+		fmt.Sprintf("%s %s/%s refused: set confirm=true to execute", action, kind, target))
+	res, _, err := failTool(ctx, req, action,
+		fmt.Errorf("mutating tool requires confirm=true (target %s/%s)", kind, target))
+	return res, struct{}{}, err, true
+}
+
+// runMutationTool wraps the audit+notify+execute flow that every
+// mutating handler shares. Mirrors cli.runMutation but adapted to the
+// MCP response shape — no stdout/prompt; success becomes a structured
+// jsonResult.
+func (s *Server) runMutationTool(ctx context.Context, req *sdk.CallToolRequest, action, kind, target string, perform func() error) (*sdk.CallToolResult, struct{}, error) {
+	s.logger.Infow("mutation",
+		"action", action, "kind", kind, "target", target, "surface", "mcp",
+		"phase", "begin",
+	)
+	if err := perform(); err != nil {
+		return failTool(ctx, req, action+" "+kind+"/"+target, err)
+	}
+	s.logger.Infow("mutation",
+		"action", action, "kind", kind, "target", target, "surface", "mcp",
+		"phase", "done",
+	)
+	notify(ctx, req.Session, "info",
+		fmt.Sprintf("%s %s/%s: OK", action, kind, target))
+	return jsonResult(map[string]string{
+		"status": "OK",
+		"action": action,
+		"kind":   kind,
+		"target": target,
+	}, nil)
+}
+
+// --- Input types --------------------------------------------------
+
+type cordonNodeInput struct {
+	Node string `json:"node" jsonschema:"the node name as reported by kubectl get nodes"`
+	confirmGate
+}
+
+type drainNodeInput struct {
+	Node string `json:"node" jsonschema:"the node name as reported by kubectl get nodes"`
+	confirmGate
+}
+
+type rebootNodeInput struct {
+	Node string `json:"node" jsonschema:"the node name as reported by kubectl get nodes"`
+	OCID string `json:"ocid,omitempty" jsonschema:"skip k8s lookup and target this instance OCID directly"`
+	confirmGate
+}
+
+type terminateNodeInput struct {
+	Node string `json:"node" jsonschema:"the node name as reported by kubectl get nodes"`
+	OCID string `json:"ocid,omitempty" jsonschema:"skip k8s lookup and target this instance OCID directly"`
+	confirmGate
+}
+
+type scaleGpuPoolInput struct {
+	Name string `json:"name" jsonschema:"the pool name from the Terraform repo (same as toolkit get gpupool)"`
+	confirmGate
+}
+
+type deleteDACInput struct {
+	Name string `json:"name" jsonschema:"the DAC name (same identifier as toolkit get dac shows)"`
+	confirmGate
+}
+
+// --- Handlers -----------------------------------------------------
+
+func (s *Server) handleCordonNode(ctx context.Context, req *sdk.CallToolRequest, in cordonNodeInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "cordon", "node", in.Node, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "cordon", "node", in.Node, func() error {
+		_, err := mcpSetCordonFn(ctx, s.cfg.KubeConfig, env.GetKubeContext(), in.Node, true)
+		return err
+	})
+}
+
+func (s *Server) handleUncordonNode(ctx context.Context, req *sdk.CallToolRequest, in cordonNodeInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "uncordon", "node", in.Node, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "uncordon", "node", in.Node, func() error {
+		_, err := mcpSetCordonFn(ctx, s.cfg.KubeConfig, env.GetKubeContext(), in.Node, false)
+		return err
+	})
+}
+
+func (s *Server) handleDrainNode(ctx context.Context, req *sdk.CallToolRequest, in drainNodeInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "drain", "node", in.Node, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "drain", "node", in.Node, func() error {
+		return mcpDrainNodeFn(ctx, s.cfg.KubeConfig, env.GetKubeContext(), in.Node)
+	})
+}
+
+func (s *Server) handleRebootNode(ctx context.Context, req *sdk.CallToolRequest, in rebootNodeInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "reboot", "node", in.Node, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "reboot", "node", in.Node, func() error {
+		node, err := s.resolveNodeForOCIAction(ctx, env, in.Node, in.OCID)
+		if err != nil {
+			return err
+		}
+		return mcpSoftResetFn(ctx, node, env, logging.FromContext(ctx))
+	})
+}
+
+func (s *Server) handleTerminateNode(ctx context.Context, req *sdk.CallToolRequest, in terminateNodeInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "terminate", "node", in.Node, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "terminate", "node", in.Node, func() error {
+		node, err := s.resolveNodeForOCIAction(ctx, env, in.Node, in.OCID)
+		if err != nil {
+			return err
+		}
+		return mcpTerminateFn(ctx, node, env, logging.FromContext(ctx))
+	})
+}
+
+func (s *Server) handleScaleGpuPool(ctx context.Context, req *sdk.CallToolRequest, in scaleGpuPoolInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "scale", "gpu_pool", in.Name, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "scale", "gpu_pool", in.Name, func() error {
+		pool, err := s.resolveGpuPoolForOCIAction(ctx, env, in.Name)
+		if err != nil {
+			return err
+		}
+		return mcpIncreasePoolSizeFn(ctx, pool, env, logging.FromContext(ctx))
+	})
+}
+
+func (s *Server) handleDeleteDAC(ctx context.Context, req *sdk.CallToolRequest, in deleteDACInput) (*sdk.CallToolResult, struct{}, error) {
+	if res, _, err, gated := s.requireConfirm(ctx, req, "delete", "dac", in.Name, in.Confirm); gated {
+		return res, struct{}{}, err
+	}
+	env := s.envFor(envOverride{})
+	return s.runMutationTool(ctx, req, "delete", "dac", in.Name, func() error {
+		dac := &models.DedicatedAICluster{Name: in.Name}
+		return mcpDeleteDACFn(ctx, dac, env, logging.FromContext(ctx))
+	})
+}
+
+// --- Resolvers ----------------------------------------------------
+
+// resolveNodeForOCIAction synthesizes a *GpuNode for OCI compute
+// actions. With ocid set, the cluster isn't consulted; otherwise the
+// loader is asked for all GPU nodes and the named one is returned.
+func (s *Server) resolveNodeForOCIAction(ctx context.Context, env models.Environment, name, ocid string) (*models.GpuNode, error) {
+	if ocid != "" {
+		return &models.GpuNode{Name: name, ID: ocid}, nil
+	}
+	grouped, err := s.loader.LoadGpuNodes(ctx, s.cfg.KubeConfig, env)
+	if err != nil {
+		return nil, fmt.Errorf("load gpu nodes: %w", err)
+	}
+	for _, nodes := range grouped {
+		for i := range nodes {
+			if nodes[i].Name == name {
+				return &nodes[i], nil
+			}
+		}
+	}
+	return nil, fmt.Errorf("gpu node %q not found in any pool", name)
+}
+
+// resolveGpuPoolForOCIAction loads pools from Terraform, finds the
+// named one, then enriches with OCI ID/ActualSize via
+// PopulateGpuPools. Mirrors the CLI's realResolveGpuPool.
+func (s *Server) resolveGpuPoolForOCIAction(ctx context.Context, env models.Environment, name string) (*models.GpuPool, error) {
+	pools, err := s.loader.LoadGpuPools(ctx, s.cfg.RepoPath, env)
+	if err != nil {
+		if _, ok := errors.AsType[*terraform.PartialLoadError](err); !ok {
+			return nil, fmt.Errorf("load gpu pools: %w", err)
+		}
+		s.logger.Infow("gpu pools loaded with partial failures (mcp)", "error", err)
+	}
+	idx := -1
+	for i := range pools {
+		if pools[i].Name == name {
+			idx = i
+			break
+		}
+	}
+	if idx < 0 {
+		return nil, fmt.Errorf("gpu pool %q not found in repo", name)
+	}
+	compartmentID, err := mcpResolveCompartmentFn(ctx, s, env)
+	if err != nil {
+		return nil, fmt.Errorf("resolve compartment ID: %w", err)
+	}
+	enriched := []models.GpuPool{pools[idx]}
+	if err := mcpPopulateGpuPoolsFn(ctx, enriched, env, compartmentID); err != nil {
+		return nil, fmt.Errorf("populate gpu pool: %w", err)
+	}
+	if enriched[0].ID == "" {
+		return nil, fmt.Errorf("gpu pool %q has no OCID after OCI lookup; may not be applied yet", name)
+	}
+	return &enriched[0], nil
+}
+
+// mcpResolveCompartmentID queries the cluster for any GPU node and
+// returns its CompartmentID. Default value of mcpResolveCompartmentFn.
+func mcpResolveCompartmentID(ctx context.Context, s *Server, env models.Environment) (string, error) {
+	clientset, err := k8s.NewClientsetFromKubeConfig(s.cfg.KubeConfig, env.GetKubeContext())
+	if err != nil {
+		return "", err
+	}
+	nodes, err := k8s.ListGpuNodes(ctx, clientset, 1)
+	if err != nil {
+		return "", err
+	}
+	if len(nodes) == 0 {
+		return "", fmt.Errorf("no GPU nodes in cluster (cannot resolve compartment ID)")
+	}
+	return nodes[0].CompartmentID, nil
+}
+
+// --- Registration -------------------------------------------------
+
+// registerMutationTools adds the seven mutating tools. Each requires
+// confirm=true at the input level; the tool description tells the
+// agent explicitly so the contract is discoverable without running
+// the tool to see the refusal.
+func registerMutationTools(s *Server) {
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "cordon_node",
+		Description: "Cordon (mark unschedulable) a Kubernetes node. Idempotent. Mutating: requires confirm=true to execute, otherwise refuses without acting.",
+	}, s.handleCordonNode)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "uncordon_node",
+		Description: "Uncordon (mark schedulable) a Kubernetes node. Idempotent. Mutating: requires confirm=true.",
+	}, s.handleUncordonNode)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "drain_node",
+		Description: "Drain pods from a node (cordon + evict). Use before terminate. Mutating: requires confirm=true.",
+	}, s.handleDrainNode)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "reboot_node",
+		Description: "Soft-reset the OCI instance backing a GPU node. Fire-and-forget. Mutating: requires confirm=true.",
+	}, s.handleRebootNode)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "terminate_node",
+		Description: "Terminate the OCI instance backing a GPU node (boot volume destroyed). DESTRUCTIVE. Mutating: requires confirm=true.",
+	}, s.handleTerminateNode)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "scale_gpu_pool",
+		Description: "Push the Terraform-declared pool.Size to OCI for the named GPU pool. No size override: Terraform is the source of truth. Mutating: requires confirm=true.",
+	}, s.handleScaleGpuPool)
+
+	sdk.AddTool(s.server, &sdk.Tool{
+		Name:        "delete_dac",
+		Description: "Delete a dedicated AI cluster and its endpoints (synchronous, polls the work request). DESTRUCTIVE. Mutating: requires confirm=true.",
+	}, s.handleDeleteDAC)
+}