godoc

Author: ezynda3

cmd/auth.go

@@ -10,6 +10,10 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// authCmd represents the auth command for managing AI provider authentication.
+// This command provides subcommands for login, logout, and status checking
+// of authentication credentials for various AI providers, with OAuth support
+// for providers like Anthropic.
 var authCmd = &cobra.Command{
 	Use:   "auth",
 	Short: "Manage authentication credentials for AI providers",
@@ -27,6 +31,9 @@ Examples:
   mcphost auth status`,
 }
 
+// authLoginCmd represents the login subcommand for authenticating with AI providers.
+// It handles OAuth flow for supported providers, opening a browser for authentication
+// and securely storing the resulting credentials for future use.
 var authLoginCmd = &cobra.Command{
 	Use:   "login [provider]",
 	Short: "Authenticate with an AI provider using OAuth",
@@ -45,6 +52,9 @@ Example:
 	RunE: runAuthLogin,
 }
 
+// authLogoutCmd represents the logout subcommand for removing stored authentication credentials.
+// This command removes stored API keys or OAuth tokens for specified providers,
+// requiring the user to authenticate again or use environment variables.
 var authLogoutCmd = &cobra.Command{
 	Use:   "logout [provider]",
 	Short: "Remove stored authentication credentials for a provider",
@@ -62,6 +72,9 @@ Example:
 	RunE: runAuthLogout,
 }
 
+// authStatusCmd represents the status subcommand for checking authentication status.
+// It displays which providers have stored credentials, their types (OAuth vs API key),
+// creation dates, and expiration status without revealing the actual credentials.
 var authStatusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Show authentication status for all providers",

cmd/hooks.go

@@ -10,12 +10,18 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
+// hooksCmd represents the hooks command for managing MCPHost hook configurations.
+// Hooks allow users to execute custom scripts or commands at various points
+// during MCPHost execution, such as before/after tool use or when prompts are submitted.
 var hooksCmd = &cobra.Command{
 	Use:   "hooks",
 	Short: "Manage MCPHost hooks",
 	Long:  "Commands for managing and testing MCPHost hooks configuration",
 }
 
+// hooksListCmd represents the list subcommand for displaying all configured hooks.
+// It shows a formatted table of hook events, matchers, commands, and timeouts
+// to help users understand their current hook configuration.
 var hooksListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all configured hooks",
@@ -45,6 +51,9 @@ var hooksListCmd = &cobra.Command{
 	},
 }
 
+// hooksValidateCmd represents the validate subcommand for checking hook configuration validity.
+// It loads and validates the hooks configuration file, ensuring proper syntax,
+// valid event types, and correct matcher patterns before use.
 var hooksValidateCmd = &cobra.Command{
 	Use:   "validate",
 	Short: "Validate hooks configuration",
@@ -64,6 +73,9 @@ var hooksValidateCmd = &cobra.Command{
 	},
 }
 
+// hooksInitCmd represents the init subcommand for generating an example hooks configuration.
+// It creates a .mcphost/hooks.yml file with sample hook configurations demonstrating
+// various hook events and common use cases like logging commands and tool usage.
 var hooksInitCmd = &cobra.Command{
 	Use:   "init",
 	Short: "Generate example hooks configuration",

cmd/root.go

@@ -84,6 +84,10 @@ func (a *agentUIAdapter) GetLoadedServerNames() []string {
 	return a.agent.GetLoadedServerNames()
 }
 
+// rootCmd represents the base command when called without any subcommands.
+// This is the main entry point for the MCPHost CLI application, providing
+// an interface to interact with various AI models through a unified interface
+// with support for MCP servers and tool integration.
 var rootCmd = &cobra.Command{
 	Use:   "mcphost",
 	Short: "Chat with AI models through a unified interface",
@@ -120,12 +124,21 @@ Examples:
 	},
 }
 
-// GetRootCommand returns the root command with the version set
+// GetRootCommand returns the root command with the version set.
+// This function is the main entry point for the MCPHost CLI and should be
+// called from main.go with the appropriate version string.
 func GetRootCommand(v string) *cobra.Command {
 	rootCmd.Version = v
 	return rootCmd
 }
 
+// InitConfig initializes the configuration for MCPHost by loading config files,
+// environment variables, and hooks configuration. It follows this priority order:
+// 1. Command-line specified config file (--config flag)
+// 2. Current directory config file (.mcphost or .mcp)
+// 3. Home directory config file (~/.mcphost or ~/.mcp)
+// 4. Environment variables (MCPHOST_* prefix)
+// This function is automatically called by cobra before command execution.
 func InitConfig() {
 	if configFile != "" {
 		// Use config file from the flag
@@ -202,7 +215,12 @@ func InitConfig() {
 
 }
 
-// LoadConfigWithEnvSubstitution loads a config file with environment variable substitution
+// LoadConfigWithEnvSubstitution loads a config file with environment variable substitution.
+// It reads the config file, replaces any ${ENV_VAR} patterns with their corresponding
+// environment variable values, and then parses the resulting configuration using viper.
+// The function automatically detects JSON or YAML format based on file extension.
+// Returns an error if the file cannot be read, environment variable substitution fails,
+// or the configuration cannot be parsed.
 func LoadConfigWithEnvSubstitution(configPath string) error {
 	// Read raw config file content
 	rawContent, err := os.ReadFile(configPath)
@@ -728,7 +746,9 @@ func runNormalMode(ctx context.Context) error {
 	return runInteractiveMode(ctx, mcpAgent, cli, serverNames, toolNames, modelName, messages, sessionManager, hookExecutor)
 }
 
-// AgenticLoopConfig configures the behavior of the unified agentic loop
+// AgenticLoopConfig configures the behavior of the unified agentic loop.
+// This struct controls how the main interaction loop operates, whether in
+// interactive or non-interactive mode, and manages various UI and session options.
 type AgenticLoopConfig struct {
 	// Mode configuration
 	IsInteractive    bool   // true for interactive mode, false for non-interactive

cmd/script.go

@@ -21,6 +21,10 @@ import (
 	"github.com/spf13/viper"
 )
 
+// scriptCmd represents the script command for executing MCPHost script files.
+// Script files can contain YAML frontmatter configuration followed by a prompt,
+// allowing for reproducible AI interactions with custom configurations and
+// variable substitution support.
 var scriptCmd = &cobra.Command{
 	Use:   "script <script-file>",
 	Short: "Execute a script file with YAML frontmatter configuration",
@@ -413,11 +417,13 @@ func parseScriptContent(content string, variables map[string]string) (*config.Co
 	return &scriptConfig, nil
 }
 
-// Variable represents a script variable with optional default value
+// Variable represents a script variable with optional default value.
+// Variables can be declared in scripts using ${variable} syntax for required variables
+// or ${variable:-default} syntax for variables with default values.
 type Variable struct {
-	Name         string
-	DefaultValue string
-	HasDefault   bool
+	Name         string // The name of the variable as it appears in the script
+	DefaultValue string // The default value if specified using ${variable:-default} syntax
+	HasDefault   bool   // Whether this variable has a default value
 }
 
 // findVariables extracts all unique variable names from ${variable} patterns in content

internal/agent/agent.go

@@ -16,35 +16,49 @@ import (
 	"time"
 )
 
-// AgentConfig is the config for agent.
+// AgentConfig holds configuration options for creating a new Agent.
+// It includes model configuration, MCP settings, and various behavioral options.
 type AgentConfig struct {
-	ModelConfig      *models.ProviderConfig
-	MCPConfig        *config.Config
-	SystemPrompt     string
-	MaxSteps         int
+	// ModelConfig specifies the LLM provider and model to use
+	ModelConfig *models.ProviderConfig
+	// MCPConfig contains MCP server configurations
+	MCPConfig *config.Config
+	// SystemPrompt is the initial system message for the agent
+	SystemPrompt string
+	// MaxSteps limits the number of tool calls (0 for unlimited)
+	MaxSteps int
+	// StreamingEnabled controls whether responses are streamed
 	StreamingEnabled bool
-	DebugLogger      tools.DebugLogger // Optional debug logger
+	// DebugLogger is an optional logger for debugging MCP communications
+	DebugLogger tools.DebugLogger // Optional debug logger
 }
 
-// ToolCallHandler is a function type for handling tool calls as they happen
+// ToolCallHandler is a function type for handling tool calls as they happen.
+// It receives the tool name and its arguments when a tool is about to be invoked.
 type ToolCallHandler func(toolName, toolArgs string)
 
-// ToolExecutionHandler is a function type for handling tool execution start/end
+// ToolExecutionHandler is a function type for handling tool execution start/end events.
+// The isStarting parameter indicates whether the tool is starting (true) or finished (false).
 type ToolExecutionHandler func(toolName string, isStarting bool)
 
-// ToolResultHandler is a function type for handling tool results
+// ToolResultHandler is a function type for handling tool results.
+// It receives the tool name, arguments, result, and whether the result is an error.
 type ToolResultHandler func(toolName, toolArgs, result string, isError bool)
 
-// ResponseHandler is a function type for handling LLM responses
+// ResponseHandler is a function type for handling LLM responses.
+// It receives the complete response content from the model.
 type ResponseHandler func(content string)
 
-// StreamingResponseHandler is a function type for handling streaming LLM responses
+// StreamingResponseHandler is a function type for handling streaming LLM responses.
+// It receives content chunks as they are streamed from the model.
 type StreamingResponseHandler func(content string)
 
-// ToolCallContentHandler is a function type for handling content that accompanies tool calls
+// ToolCallContentHandler is a function type for handling content that accompanies tool calls.
+// It receives any text content that the model generates alongside tool calls.
 type ToolCallContentHandler func(content string)
 
-// Agent is the agent with real-time tool call display.
+// Agent represents an AI agent with MCP tool integration and real-time tool call display.
+// It manages the interaction between an LLM and various tools through the MCP protocol.
 type Agent struct {
 	toolManager      *tools.MCPToolManager
 	model            model.ToolCallingChatModel
@@ -55,7 +69,10 @@ type Agent struct {
 	streamingEnabled bool   // Whether streaming is enabled
 }
 
-// NewAgent creates an agent with MCP tool integration and real-time tool call display
+// NewAgent creates a new Agent with MCP tool integration and streaming support.
+// It initializes the LLM provider, loads MCP tools, and configures the agent
+// based on the provided configuration. Returns an error if provider creation
+// or tool loading fails.
 func NewAgent(ctx context.Context, config *AgentConfig) (*Agent, error) {
 	// Create the LLM provider
 	providerResult, err := models.CreateProvider(ctx, config.ModelConfig)
@@ -98,20 +115,27 @@ func NewAgent(ctx context.Context, config *AgentConfig) (*Agent, error) {
 	}, nil
 }
 
-// GenerateWithLoopResult contains the result and conversation history
+// GenerateWithLoopResult contains the result and conversation history from an agent interaction.
+// It includes both the final response and the complete message history with tool interactions.
 type GenerateWithLoopResult struct {
-	FinalResponse        *schema.Message
+	// FinalResponse is the last message generated by the model
+	FinalResponse *schema.Message
+	// ConversationMessages contains all messages in the conversation including tool calls and results
 	ConversationMessages []*schema.Message // All messages in the conversation (including tool calls and results)
 }
 
-// GenerateWithLoop processes messages with a custom loop that displays tool calls in real-time
+// GenerateWithLoop processes messages with a custom loop that displays tool calls in real-time.
+// It handles the conversation flow, executing tools as needed and invoking callbacks for various events.
+// This method does not support streaming responses; use GenerateWithLoopAndStreaming for streaming support.
 func (a *Agent) GenerateWithLoop(ctx context.Context, messages []*schema.Message,
 	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler, onResponse ResponseHandler, onToolCallContent ToolCallContentHandler) (*GenerateWithLoopResult, error) {
 
 	return a.GenerateWithLoopAndStreaming(ctx, messages, onToolCall, onToolExecution, onToolResult, onResponse, onToolCallContent, nil)
 }
 
-// GenerateWithLoopAndStreaming processes messages with a custom loop that displays tool calls in real-time and supports streaming callbacks
+// GenerateWithLoopAndStreaming processes messages with a custom loop that displays tool calls in real-time and supports streaming callbacks.
+// It handles the conversation flow, executing tools as needed and invoking callbacks for various events including streaming chunks.
+// The onStreamingResponse callback is invoked for each content chunk during streaming if streaming is enabled.
 func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []*schema.Message,
 	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler, onResponse ResponseHandler, onToolCallContent ToolCallContentHandler, onStreamingResponse StreamingResponseHandler) (*GenerateWithLoopResult, error) {
 
@@ -256,17 +280,20 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []*sc
 	}, nil
 }
 
-// GetTools returns the list of available tools
+// GetTools returns the list of available tools loaded in the agent.
+// These tools are available for the model to use during interactions.
 func (a *Agent) GetTools() []tool.BaseTool {
 	return a.toolManager.GetTools()
 }
 
-// GetLoadingMessage returns the loading message from provider creation (e.g., GPU fallback info)
+// GetLoadingMessage returns the loading message from provider creation.
+// This may contain information about GPU fallback or other provider-specific initialization details.
 func (a *Agent) GetLoadingMessage() string {
 	return a.loadingMessage
 }
 
-// GetLoadedServerNames returns the names of successfully loaded MCP servers
+// GetLoadedServerNames returns the names of successfully loaded MCP servers.
+// This includes both builtin servers and external MCP server configurations.
 func (a *Agent) GetLoadedServerNames() []string {
 	return a.toolManager.GetLoadedServerNames()
 }
@@ -486,7 +513,8 @@ func (a *Agent) listenForESC(stopChan chan bool, readyChan chan bool) bool {
 	}
 }
 
-// Close closes the agent and cleans up resources
+// Close closes the agent and cleans up resources.
+// It ensures all MCP connections are properly closed and resources are released.
 func (a *Agent) Close() error {
 	return a.toolManager.Close()
 }

internal/agent/factory.go

@@ -10,23 +10,36 @@ import (
 	"github.com/mark3labs/mcphost/internal/tools"
 )
 
-// SpinnerFunc is a function type for showing spinners during agent creation
+// SpinnerFunc is a function type for showing spinners during agent creation.
+// It executes the provided function while displaying a spinner with the given message.
 type SpinnerFunc func(message string, fn func() error) error
 
-// AgentCreationOptions contains options for creating an agent
+// AgentCreationOptions contains options for creating an agent.
+// It extends AgentConfig with UI-related options for showing progress during creation.
 type AgentCreationOptions struct {
-	ModelConfig      *models.ProviderConfig
-	MCPConfig        *config.Config
-	SystemPrompt     string
-	MaxSteps         int
+	// ModelConfig specifies the LLM provider and model to use
+	ModelConfig *models.ProviderConfig
+	// MCPConfig contains MCP server configurations
+	MCPConfig *config.Config
+	// SystemPrompt is the initial system message for the agent
+	SystemPrompt string
+	// MaxSteps limits the number of tool calls (0 for unlimited)
+	MaxSteps int
+	// StreamingEnabled controls whether responses are streamed
 	StreamingEnabled bool
-	ShowSpinner      bool              // For Ollama models
-	Quiet            bool              // Skip spinner if quiet
-	SpinnerFunc      SpinnerFunc       // Function to show spinner (provided by caller)
-	DebugLogger      tools.DebugLogger // Optional debug logger
+	// ShowSpinner indicates whether to show a spinner for Ollama models during loading
+	ShowSpinner bool // For Ollama models
+	// Quiet suppresses the spinner even if ShowSpinner is true
+	Quiet bool // Skip spinner if quiet
+	// SpinnerFunc is the function to show spinner, provided by the caller
+	SpinnerFunc SpinnerFunc // Function to show spinner (provided by caller)
+	// DebugLogger is an optional logger for debugging MCP communications
+	DebugLogger tools.DebugLogger // Optional debug logger
 }
 
-// CreateAgent creates an agent with optional spinner for Ollama models
+// CreateAgent creates an agent with optional spinner for Ollama models.
+// It shows a loading spinner for Ollama models if ShowSpinner is true and not in quiet mode.
+// Returns the created agent or an error if creation fails.
 func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error) {
 	agentConfig := &AgentConfig{
 		ModelConfig:      opts.ModelConfig,
@@ -57,7 +70,9 @@ func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error
 	return agent, nil
 }
 
-// ParseModelName extracts provider and model name from model string
+// ParseModelName extracts provider and model name from a model string.
+// Model strings are formatted as "provider:model" (e.g., "anthropic:claude-3-5-sonnet-20241022").
+// If the string doesn't contain a colon, returns "unknown" for both provider and model.
 func ParseModelName(modelString string) (provider, model string) {
 	parts := strings.SplitN(modelString, ":", 2)
 	if len(parts) == 2 {

internal/agent/streaming.go

@@ -8,7 +8,8 @@ import (
 	"github.com/cloudwego/eino/schema"
 )
 
-// StreamWithCallback streams content with real-time callbacks and returns complete response
+// StreamWithCallback streams content with real-time callbacks and returns the complete response.
+// It accumulates content and tool calls from the stream, invoking the callback for each content chunk.
 // IMPORTANT: Tool calls are only processed after EOF is reached to ensure we have the complete
 // and final tool call information. This prevents premature tool execution on partial data.
 // Handles different provider streaming patterns: