refactor: Improve identity code structure and documentation

- Match mcpd code style with comprehensive godoc comments
- Add helper methods for better maintainability
- Improve error handling with proper context
- Add verbose logging option to CLI
- Follow existing manager patterns from codebase

Author: Anivar Aravind

cmd/identity.go

@@ -3,26 +3,50 @@ package cmd
 import (
 	"fmt"
 
+	"github.com/hashicorp/go-hclog"
 	"github.com/spf13/cobra"
 
 	"github.com/mozilla-ai/mcpd/v2/internal/identity"
 )
 
 var identityCmd = &cobra.Command{
 	Use:   "identity",
-	Short: "Manage MCP server identities (AGNTCY-compatible)",
-	Long:  `Optional identity management for MCP servers using AGNTCY standards.`,
+	Short: "Manage MCP server identities",
+	Long: `Manage AGNTCY-compliant identities for MCP servers.
+
+Identity support is optional and disabled by default. Enable with:
+  export MCPD_IDENTITY_ENABLED=true
+
+Identities follow the AGNTCY Identity specification:
+  https://spec.identity.agntcy.org/docs/id/definitions`,
 }
 
 var identityInitCmd = &cobra.Command{
 	Use:   "init [server-name]",
 	Short: "Initialize identity for an MCP server",
-	Args:  cobra.ExactArgs(1),
+	Long: `Initialize an AGNTCY-compliant identity for an MCP server.
+
+This creates a development identity with:
+  - DID format: did:agntcy:dev:{organization}:{server}
+  - ResolverMetadata with assertion methods
+  - Service endpoints for MCP
+
+The identity is stored in ~/.config/mcpd/identity/{server}.json`,
+	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		serverName := args[0]
 		organization, _ := cmd.Flags().GetString("org")
 
-		manager := identity.NewManager(nil)
+		// Create logger based on verbosity
+		logger := hclog.NewNullLogger()
+		if verbose, _ := cmd.Flags().GetBool("verbose"); verbose {
+			logger = hclog.New(&hclog.LoggerOptions{
+				Name:  "identity",
+				Level: hclog.Debug,
+			})
+		}
+		
+		manager := identity.NewManager(logger)
 		if err := manager.InitServer(serverName, organization); err != nil {
 			return err
 		}
@@ -36,5 +60,7 @@ func init() {
 	rootCmd.AddCommand(identityCmd)
 	identityCmd.AddCommand(identityInitCmd)
 
-	identityInitCmd.Flags().StringP("org", "o", "mcpd", "Organization name")
+	// Flags for identity init
+	identityInitCmd.Flags().StringP("org", "o", "mcpd", "Organization name for the identity")
+	identityInitCmd.Flags().BoolP("verbose", "v", false, "Enable verbose logging")
 }

internal/identity/identity.go

@@ -12,13 +12,16 @@ import (
 	"github.com/hashicorp/go-hclog"
 )
 
-// Manager handles identity verification with minimal complexity
+// Manager handles identity verification for MCP servers.
+// It supports AGNTCY Identity specifications with local file storage.
+// NewManager should be used to create instances of Manager.
 type Manager struct {
 	logger  hclog.Logger
 	enabled bool
 }
 
-// NewManager creates a new identity manager
+// NewManager creates a new identity manager instance.
+// Identity is disabled by default unless MCPD_IDENTITY_ENABLED is set to "true".
 func NewManager(logger hclog.Logger) *Manager {
 	if logger == nil {
 		logger = hclog.NewNullLogger()
@@ -30,46 +33,73 @@ func NewManager(logger hclog.Logger) *Manager {
 	}
 }
 
-// IsEnabled returns if identity is enabled
+// IsEnabled returns whether identity verification is enabled.
+// This method is safe for concurrent use.
 func (m *Manager) IsEnabled() bool {
 	return m.enabled
 }
 
-// VerifyServer checks if a server has valid identity credentials
+// VerifyServer checks if a server has valid identity credentials.
+// If identity is disabled or no credentials exist, it returns nil (non-blocking).
+// This method logs verification status but never fails to maintain backward compatibility.
 func (m *Manager) VerifyServer(ctx context.Context, serverName string) error {
 	if !m.enabled {
 		return nil
 	}
 
-	// For now, just check if credential file exists
-	homeDir, _ := os.UserHomeDir()
-	credPath := filepath.Join(homeDir, ".config", "mcpd", "identity", serverName+".json")
+	credPath, err := m.getCredentialPath(serverName)
+	if err != nil {
+		m.logger.Debug("Failed to get credential path", "server", serverName, "error", err)
+		return nil
+	}
 
 	if _, err := os.Stat(credPath); os.IsNotExist(err) {
-		m.logger.Debug("No identity credentials found", "server", serverName)
-		// Don't fail - identity is optional
+		m.logger.Debug("No identity credentials found", "server", serverName, "path", credPath)
 		return nil
 	}
 
 	m.logger.Info("Identity verified", "server", serverName)
 	return nil
 }
 
-// InitServer creates AGNTCY-spec identity with ResolverMetadata
+// InitServer creates an AGNTCY-compliant identity for the specified server.
+// The identity follows the AGNTCY Identity specification with ResolverMetadata.
+// Returns an error if identity is disabled or if file operations fail.
 func (m *Manager) InitServer(serverName, organization string) error {
 	if !m.enabled {
 		return fmt.Errorf("identity not enabled (set MCPD_IDENTITY_ENABLED=true)")
 	}
 
-	homeDir, _ := os.UserHomeDir()
-	identityDir := filepath.Join(homeDir, ".config", "mcpd", "identity")
-	if err := os.MkdirAll(identityDir, 0700); err != nil {
+	identity := m.createIdentity(serverName, organization)
+	
+	credPath, err := m.getCredentialPath(serverName)
+	if err != nil {
+		return fmt.Errorf("failed to get credential path: %w", err)
+	}
+	
+	// Ensure directory exists
+	if err := os.MkdirAll(filepath.Dir(credPath), 0700); err != nil {
 		return fmt.Errorf("failed to create identity directory: %w", err)
 	}
 
-	// AGNTCY identity format with ResolverMetadata
+	data, err := json.MarshalIndent(identity, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal identity: %w", err)
+	}
+	
+	if err := os.WriteFile(credPath, data, 0600); err != nil {
+		return fmt.Errorf("failed to write identity: %w", err)
+	}
+	
+	m.logger.Info("Created identity", "server", serverName, "path", credPath)
+	return nil
+}
+
+// createIdentity builds the AGNTCY-compliant identity structure.
+func (m *Manager) createIdentity(serverName, organization string) map[string]interface{} {
 	id := fmt.Sprintf("did:agntcy:dev:%s:%s", organization, serverName)
-	identity := map[string]interface{}{
+	
+	return map[string]interface{}{
 		"id": id,
 		"resolverMetadata": map[string]interface{}{
 			"id": id,
@@ -92,13 +122,14 @@ func (m *Manager) InitServer(serverName, organization string) error {
 			},
 		},
 	}
-	
-	data, _ := json.MarshalIndent(identity, "", "  ")
-	credPath := filepath.Join(identityDir, serverName+".json")
-	
-	if err := os.WriteFile(credPath, data, 0600); err != nil {
-		return fmt.Errorf("failed to write identity: %w", err)
+}
+
+// getCredentialPath returns the file path for a server's identity credentials.
+func (m *Manager) getCredentialPath(serverName string) (string, error) {
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("failed to get home directory: %w", err)
 	}
 
-	return nil
+	return filepath.Join(homeDir, ".config", "mcpd", "identity", serverName+".json"), nil
 }