From 4ab909f391ba8b9255074b232955b0ae711ec85a Mon Sep 17 00:00:00 2001 From: Virgil Date: Thu, 2 Apr 2026 14:54:37 +0000 Subject: [PATCH] docs(mcp): add usage examples to agentic DTOs --- pkg/mcp/agentic/plan.go | 33 +++++++++++++++++++++++++++++++++ pkg/mcp/agentic/resume.go | 4 ++++ pkg/mcp/agentic/status.go | 15 +++++++++++++++ pkg/mcp/mcp.go | 2 +- 4 files changed, 53 insertions(+), 1 deletion(-) diff --git a/pkg/mcp/agentic/plan.go b/pkg/mcp/agentic/plan.go index 677e84b..5635b6b 100644 --- a/pkg/mcp/agentic/plan.go +++ b/pkg/mcp/agentic/plan.go @@ -17,6 +17,11 @@ import ( ) // Plan represents an implementation plan for agent work. +// +// plan := Plan{ +// Title: "Add notifications", +// Status: "draft", +// } type Plan struct { ID string `json:"id"` Title string `json:"title"` @@ -32,6 +37,8 @@ type Plan struct { } // Phase represents a phase within an implementation plan. +// +// phase := Phase{Name: "Implementation", Status: "pending"} type Phase struct { Number int `json:"number"` Name string `json:"name"` @@ -43,6 +50,8 @@ type Phase struct { } // Checkpoint records phase progress or completion details. +// +// cp := Checkpoint{Notes: "Implemented transport hooks", Done: true} type Checkpoint struct { Notes string `json:"notes,omitempty"` Done bool `json:"done,omitempty"` @@ -52,6 +61,8 @@ type Checkpoint struct { // --- Input/Output types --- // PlanCreateInput is the input for agentic_plan_create. +// +// input := PlanCreateInput{Title: "Add notifications", Objective: "Broadcast MCP events"} type PlanCreateInput struct { Title string `json:"title"` Objective string `json:"objective"` @@ -62,6 +73,8 @@ type PlanCreateInput struct { } // PlanCreateOutput is the output for agentic_plan_create. +// +// // out.Success == true, out.ID != "" type PlanCreateOutput struct { Success bool `json:"success"` ID string `json:"id"` @@ -69,17 +82,23 @@ type PlanCreateOutput struct { } // PlanReadInput is the input for agentic_plan_read. +// +// input := PlanReadInput{ID: "add-notifications"} type PlanReadInput struct { ID string `json:"id"` } // PlanReadOutput is the output for agentic_plan_read. +// +// // out.Plan.Title == "Add notifications" type PlanReadOutput struct { Success bool `json:"success"` Plan Plan `json:"plan"` } // PlanUpdateInput is the input for agentic_plan_update. +// +// input := PlanUpdateInput{ID: "add-notifications", Status: "ready"} type PlanUpdateInput struct { ID string `json:"id"` Status string `json:"status,omitempty"` @@ -91,29 +110,39 @@ type PlanUpdateInput struct { } // PlanUpdateOutput is the output for agentic_plan_update. +// +// // out.Plan.Status == "ready" type PlanUpdateOutput struct { Success bool `json:"success"` Plan Plan `json:"plan"` } // PlanDeleteInput is the input for agentic_plan_delete. +// +// input := PlanDeleteInput{ID: "add-notifications"} type PlanDeleteInput struct { ID string `json:"id"` } // PlanDeleteOutput is the output for agentic_plan_delete. +// +// // out.Deleted == "add-notifications" type PlanDeleteOutput struct { Success bool `json:"success"` Deleted string `json:"deleted"` } // PlanListInput is the input for agentic_plan_list. +// +// input := PlanListInput{Status: "draft"} type PlanListInput struct { Status string `json:"status,omitempty"` Repo string `json:"repo,omitempty"` } // PlanListOutput is the output for agentic_plan_list. +// +// // len(out.Plans) >= 1 type PlanListOutput struct { Success bool `json:"success"` Count int `json:"count"` @@ -121,6 +150,8 @@ type PlanListOutput struct { } // PlanCheckpointInput is the input for agentic_plan_checkpoint. +// +// input := PlanCheckpointInput{ID: "add-notifications", Phase: 1, Done: true} type PlanCheckpointInput struct { ID string `json:"id"` Phase int `json:"phase"` @@ -129,6 +160,8 @@ type PlanCheckpointInput struct { } // PlanCheckpointOutput is the output for agentic_plan_checkpoint. +// +// // out.Plan.Phases[0].Status == "done" type PlanCheckpointOutput struct { Success bool `json:"success"` Plan Plan `json:"plan"` diff --git a/pkg/mcp/agentic/resume.go b/pkg/mcp/agentic/resume.go index c14e7bb..5f7a463 100644 --- a/pkg/mcp/agentic/resume.go +++ b/pkg/mcp/agentic/resume.go @@ -18,6 +18,8 @@ import ( ) // ResumeInput is the input for agentic_resume. +// +// input := ResumeInput{Workspace: "go-mcp-1700000000", Answer: "Use the shared notifier"} type ResumeInput struct { Workspace string `json:"workspace"` // workspace name (e.g. "go-scm-1773581173") Answer string `json:"answer,omitempty"` // answer to the blocked question (written to ANSWER.md) @@ -26,6 +28,8 @@ type ResumeInput struct { } // ResumeOutput is the output for agentic_resume. +// +// // out.Success == true, out.PID > 0 type ResumeOutput struct { Success bool `json:"success"` Workspace string `json:"workspace"` diff --git a/pkg/mcp/agentic/status.go b/pkg/mcp/agentic/status.go index 45fe361..de41cc7 100644 --- a/pkg/mcp/agentic/status.go +++ b/pkg/mcp/agentic/status.go @@ -28,6 +28,12 @@ import ( // running → failed (agent crashed / non-zero exit) // WorkspaceStatus represents the current state of an agent workspace. +// +// status := WorkspaceStatus{ +// Status: "blocked", +// Agent: "claude", +// Repo: "go-mcp", +// } type WorkspaceStatus struct { Status string `json:"status"` // running, completed, blocked, failed Agent string `json:"agent"` // gemini, claude, codex @@ -67,15 +73,24 @@ func readStatus(wsDir string) (*WorkspaceStatus, error) { // --- agentic_status tool --- +// StatusInput is the input for agentic_status. +// +// input := StatusInput{Workspace: "go-mcp-1700000000"} type StatusInput struct { Workspace string `json:"workspace,omitempty"` // specific workspace name, or empty for all } +// StatusOutput is the output for agentic_status. +// +// // out.Count == 2, len(out.Workspaces) == 2 type StatusOutput struct { Workspaces []WorkspaceInfo `json:"workspaces"` Count int `json:"count"` } +// WorkspaceInfo summarizes a tracked workspace. +// +// // ws.Name == "go-mcp-1700000000", ws.Status == "running" type WorkspaceInfo struct { Name string `json:"name"` Status string `json:"status"` diff --git a/pkg/mcp/mcp.go b/pkg/mcp/mcp.go index d6bee82..5f0982e 100644 --- a/pkg/mcp/mcp.go +++ b/pkg/mcp/mcp.go @@ -33,7 +33,7 @@ type Service struct { *core.ServiceRuntime[struct{}] // Core access via s.Core() server *mcp.Server - workspaceRoot string // Root directory for file operations (empty = unrestricted) + workspaceRoot string // Root directory for file operations (empty = cwd unless Unrestricted) medium io.Medium // Filesystem medium for sandboxed operations subsystems []Subsystem // Additional subsystems registered via Options.Subsystems logger *log.Logger // Logger for tool execution auditing