From af3cf3c8e3b624cfc7ee753208ee5ab2bee23eda Mon Sep 17 00:00:00 2001 From: Virgil Date: Thu, 2 Apr 2026 14:17:47 +0000 Subject: [PATCH] docs(mcp): add usage examples to remaining public DTOs Align the IDE bridge and brain subsystem public types with the repo's AX-style comment convention by adding concrete usage examples for bridge messages, DTOs, and helper callbacks. Co-Authored-By: Virgil --- pkg/mcp/brain/direct.go | 2 ++ pkg/mcp/brain/tools.go | 20 ++++++++++++++++++++ pkg/mcp/ide/bridge.go | 26 +++++++++++++++++++++++++- pkg/mcp/ide/tools_build.go | 14 ++++++++++++++ pkg/mcp/ide/tools_chat.go | 26 ++++++++++++++++++++++++++ pkg/mcp/ide/tools_dashboard.go | 18 ++++++++++++++++++ 6 files changed, 105 insertions(+), 1 deletion(-) diff --git a/pkg/mcp/brain/direct.go b/pkg/mcp/brain/direct.go index 3812bb9..463d9c2 100644 --- a/pkg/mcp/brain/direct.go +++ b/pkg/mcp/brain/direct.go @@ -21,6 +21,8 @@ import ( ) // channelSender is the callback for pushing channel events. +// +// fn := func(ctx context.Context, channel string, data any) { ... } type channelSender func(ctx context.Context, channel string, data any) // DirectSubsystem implements mcp.Subsystem for OpenBrain via direct HTTP calls. diff --git a/pkg/mcp/brain/tools.go b/pkg/mcp/brain/tools.go index 784fd2a..4a9ca81 100644 --- a/pkg/mcp/brain/tools.go +++ b/pkg/mcp/brain/tools.go @@ -22,6 +22,8 @@ func (s *Subsystem) emitChannel(ctx context.Context, channel string, data any) { // -- Input/Output types ------------------------------------------------------- // RememberInput is the input for brain_remember. +// +// input := RememberInput{Content: "Use Qdrant for vector search", Type: "decision"} type RememberInput struct { Content string `json:"content"` Type string `json:"type"` @@ -33,6 +35,8 @@ type RememberInput struct { } // RememberOutput is the output for brain_remember. +// +// // out.Success == true type RememberOutput struct { Success bool `json:"success"` MemoryID string `json:"memoryId,omitempty"` @@ -40,6 +44,8 @@ type RememberOutput struct { } // RecallInput is the input for brain_recall. +// +// input := RecallInput{Query: "vector search", TopK: 5} type RecallInput struct { Query string `json:"query"` TopK int `json:"top_k,omitempty"` @@ -47,6 +53,8 @@ type RecallInput struct { } // RecallFilter holds optional filter criteria for brain_recall. +// +// filter := RecallFilter{Project: "core/mcp", MinConfidence: 0.5} type RecallFilter struct { Project string `json:"project,omitempty"` Type any `json:"type,omitempty"` @@ -55,6 +63,8 @@ type RecallFilter struct { } // RecallOutput is the output for brain_recall. +// +// // out.Memories contains ranked matches type RecallOutput struct { Success bool `json:"success"` Count int `json:"count"` @@ -62,6 +72,8 @@ type RecallOutput struct { } // Memory is a single memory entry returned by recall or list. +// +// mem := Memory{ID: "m1", Type: "bug", Content: "Fix timeout handling"} type Memory struct { ID string `json:"id"` AgentID string `json:"agent_id"` @@ -77,12 +89,16 @@ type Memory struct { } // ForgetInput is the input for brain_forget. +// +// input := ForgetInput{ID: "m1"} type ForgetInput struct { ID string `json:"id"` Reason string `json:"reason,omitempty"` } // ForgetOutput is the output for brain_forget. +// +// // out.Forgotten contains the deleted memory ID type ForgetOutput struct { Success bool `json:"success"` Forgotten string `json:"forgotten"` @@ -90,6 +106,8 @@ type ForgetOutput struct { } // ListInput is the input for brain_list. +// +// input := ListInput{Project: "core/mcp", Limit: 50} type ListInput struct { Project string `json:"project,omitempty"` Type string `json:"type,omitempty"` @@ -98,6 +116,8 @@ type ListInput struct { } // ListOutput is the output for brain_list. +// +// // out.Count reports how many memories were returned type ListOutput struct { Success bool `json:"success"` Count int `json:"count"` diff --git a/pkg/mcp/ide/bridge.go b/pkg/mcp/ide/bridge.go index 2392630..b700ce2 100644 --- a/pkg/mcp/ide/bridge.go +++ b/pkg/mcp/ide/bridge.go @@ -12,7 +12,13 @@ import ( "github.com/gorilla/websocket" ) -// BridgeMessage is the wire format between the IDE and Laravel. +// BridgeMessage is the wire format between the IDE bridge and Laravel. +// +// msg := BridgeMessage{ +// Type: "chat_send", +// SessionID: "sess-42", +// Data: "hello", +// } type BridgeMessage struct { Type string `json:"type"` Channel string `json:"channel,omitempty"` @@ -23,6 +29,8 @@ type BridgeMessage struct { // Bridge maintains a WebSocket connection to the Laravel core-agentic // backend and forwards responses to a local ws.Hub. +// +// bridge := NewBridge(hub, cfg) type Bridge struct { cfg Config hub *ws.Hub @@ -43,6 +51,10 @@ func NewBridge(hub *ws.Hub, cfg Config) *Bridge { } // SetObserver registers a callback for inbound bridge messages. +// +// bridge.SetObserver(func(msg BridgeMessage) { +// fmt.Println(msg.Type) +// }) func (b *Bridge) SetObserver(fn func(BridgeMessage)) { b.mu.Lock() defer b.mu.Unlock() @@ -55,6 +67,8 @@ func (b *Bridge) SetObserver(fn func(BridgeMessage)) { // AddObserver registers an additional bridge observer. // Observers are invoked in registration order after each inbound message. +// +// bridge.AddObserver(func(msg BridgeMessage) { log.Println(msg.Type) }) func (b *Bridge) AddObserver(fn func(BridgeMessage)) { if fn == nil { return @@ -66,12 +80,16 @@ func (b *Bridge) AddObserver(fn func(BridgeMessage)) { // Start begins the connection loop in a background goroutine. // Call Shutdown to stop it. +// +// bridge.Start(ctx) func (b *Bridge) Start(ctx context.Context) { ctx, b.cancel = context.WithCancel(ctx) go b.connectLoop(ctx) } // Shutdown cleanly closes the bridge. +// +// bridge.Shutdown() func (b *Bridge) Shutdown() { if b.cancel != nil { b.cancel() @@ -86,6 +104,10 @@ func (b *Bridge) Shutdown() { } // Connected reports whether the bridge has an active connection. +// +// if bridge.Connected() { +// fmt.Println("online") +// } func (b *Bridge) Connected() bool { b.mu.Lock() defer b.mu.Unlock() @@ -93,6 +115,8 @@ func (b *Bridge) Connected() bool { } // Send sends a message to the Laravel backend. +// +// err := bridge.Send(BridgeMessage{Type: "dashboard_overview"}) func (b *Bridge) Send(msg BridgeMessage) error { b.mu.Lock() defer b.mu.Unlock() diff --git a/pkg/mcp/ide/tools_build.go b/pkg/mcp/ide/tools_build.go index f162912..f72f931 100644 --- a/pkg/mcp/ide/tools_build.go +++ b/pkg/mcp/ide/tools_build.go @@ -10,11 +10,15 @@ import ( // Build tool input/output types. // BuildStatusInput is the input for ide_build_status. +// +// input := BuildStatusInput{BuildID: "build-123"} type BuildStatusInput struct { BuildID string `json:"buildId"` } // BuildInfo represents a single build. +// +// info := BuildInfo{ID: "build-123", Repo: "go-io", Status: "running"} type BuildInfo struct { ID string `json:"id"` Repo string `json:"repo"` @@ -25,28 +29,38 @@ type BuildInfo struct { } // BuildStatusOutput is the output for ide_build_status. +// +// // out.Build.Status == "running" type BuildStatusOutput struct { Build BuildInfo `json:"build"` } // BuildListInput is the input for ide_build_list. +// +// input := BuildListInput{Repo: "go-io", Limit: 20} type BuildListInput struct { Repo string `json:"repo,omitempty"` Limit int `json:"limit,omitempty"` } // BuildListOutput is the output for ide_build_list. +// +// // out.Builds holds the local build snapshot type BuildListOutput struct { Builds []BuildInfo `json:"builds"` } // BuildLogsInput is the input for ide_build_logs. +// +// input := BuildLogsInput{BuildID: "build-123", Tail: 200} type BuildLogsInput struct { BuildID string `json:"buildId"` Tail int `json:"tail,omitempty"` } // BuildLogsOutput is the output for ide_build_logs. +// +// // out.Lines contains the captured build log lines type BuildLogsOutput struct { BuildID string `json:"buildId"` Lines []string `json:"lines"` diff --git a/pkg/mcp/ide/tools_chat.go b/pkg/mcp/ide/tools_chat.go index 4a7a3e5..fafedd0 100644 --- a/pkg/mcp/ide/tools_chat.go +++ b/pkg/mcp/ide/tools_chat.go @@ -11,12 +11,16 @@ import ( // Chat tool input/output types. // ChatSendInput is the input for ide_chat_send. +// +// input := ChatSendInput{SessionID: "sess-42", Message: "hello"} type ChatSendInput struct { SessionID string `json:"sessionId"` Message string `json:"message"` } // ChatSendOutput is the output for ide_chat_send. +// +// // out.Sent == true, out.SessionID == "sess-42" type ChatSendOutput struct { Sent bool `json:"sent"` SessionID string `json:"sessionId"` @@ -24,12 +28,16 @@ type ChatSendOutput struct { } // ChatHistoryInput is the input for ide_chat_history. +// +// input := ChatHistoryInput{SessionID: "sess-42", Limit: 50} type ChatHistoryInput struct { SessionID string `json:"sessionId"` Limit int `json:"limit,omitempty"` } // ChatMessage represents a single message in history. +// +// msg := ChatMessage{Role: "user", Content: "hello"} type ChatMessage struct { Role string `json:"role"` Content string `json:"content"` @@ -37,15 +45,21 @@ type ChatMessage struct { } // ChatHistoryOutput is the output for ide_chat_history. +// +// // out.Messages contains the stored chat transcript type ChatHistoryOutput struct { SessionID string `json:"sessionId"` Messages []ChatMessage `json:"messages"` } // SessionListInput is the input for ide_session_list. +// +// input := SessionListInput{} type SessionListInput struct{} // Session represents an agent session. +// +// session := Session{ID: "sess-42", Name: "draft", Status: "running"} type Session struct { ID string `json:"id"` Name string `json:"name"` @@ -54,32 +68,44 @@ type Session struct { } // SessionListOutput is the output for ide_session_list. +// +// // out.Sessions contains every locally tracked session type SessionListOutput struct { Sessions []Session `json:"sessions"` } // SessionCreateInput is the input for ide_session_create. +// +// input := SessionCreateInput{Name: "draft"} type SessionCreateInput struct { Name string `json:"name"` } // SessionCreateOutput is the output for ide_session_create. +// +// // out.Session.ID is assigned by the backend or local store type SessionCreateOutput struct { Session Session `json:"session"` } // PlanStatusInput is the input for ide_plan_status. +// +// input := PlanStatusInput{SessionID: "sess-42"} type PlanStatusInput struct { SessionID string `json:"sessionId"` } // PlanStep is a single step in an agent plan. +// +// step := PlanStep{Name: "prep", Status: "done"} type PlanStep struct { Name string `json:"name"` Status string `json:"status"` } // PlanStatusOutput is the output for ide_plan_status. +// +// // out.Steps contains the current plan breakdown type PlanStatusOutput struct { SessionID string `json:"sessionId"` Status string `json:"status"` diff --git a/pkg/mcp/ide/tools_dashboard.go b/pkg/mcp/ide/tools_dashboard.go index da97405..80923a5 100644 --- a/pkg/mcp/ide/tools_dashboard.go +++ b/pkg/mcp/ide/tools_dashboard.go @@ -10,9 +10,13 @@ import ( // Dashboard tool input/output types. // DashboardOverviewInput is the input for ide_dashboard_overview. +// +// input := DashboardOverviewInput{} type DashboardOverviewInput struct{} // DashboardOverview contains high-level platform stats. +// +// overview := DashboardOverview{Repos: 12, ActiveSessions: 3} type DashboardOverview struct { Repos int `json:"repos"` Services int `json:"services"` @@ -22,16 +26,22 @@ type DashboardOverview struct { } // DashboardOverviewOutput is the output for ide_dashboard_overview. +// +// // out.Overview.BridgeOnline reports bridge connectivity type DashboardOverviewOutput struct { Overview DashboardOverview `json:"overview"` } // DashboardActivityInput is the input for ide_dashboard_activity. +// +// input := DashboardActivityInput{Limit: 25} type DashboardActivityInput struct { Limit int `json:"limit,omitempty"` } // ActivityEvent represents a single activity feed item. +// +// event := ActivityEvent{Type: "build", Message: "build finished"} type ActivityEvent struct { Type string `json:"type"` Message string `json:"message"` @@ -39,16 +49,22 @@ type ActivityEvent struct { } // DashboardActivityOutput is the output for ide_dashboard_activity. +// +// // out.Events contains the recent activity feed type DashboardActivityOutput struct { Events []ActivityEvent `json:"events"` } // DashboardMetricsInput is the input for ide_dashboard_metrics. +// +// input := DashboardMetricsInput{Period: "24h"} type DashboardMetricsInput struct { Period string `json:"period,omitempty"` // "1h", "24h", "7d" } // DashboardMetrics contains aggregate metrics. +// +// metrics := DashboardMetrics{BuildsTotal: 42, SuccessRate: 0.95} type DashboardMetrics struct { BuildsTotal int `json:"buildsTotal"` BuildsSuccess int `json:"buildsSuccess"` @@ -60,6 +76,8 @@ type DashboardMetrics struct { } // DashboardMetricsOutput is the output for ide_dashboard_metrics. +// +// // out.Metrics summarises the selected time window type DashboardMetricsOutput struct { Period string `json:"period"` Metrics DashboardMetrics `json:"metrics"`