feat(cursor): Manage agent entry in Cursor's mcp.json for auto-discovery

michiosw · michiosw · commit 05f864caa3c0 · 2025-04-17T18:58:48.000-07:00
Introduces a new `CursorConfigManager` component responsible for managing the Agent Browser's entry within the `~/.cursor/mcp.json` configuration file.

On application startup (`InitModule`), the manager ensures the "Agent Browser" entry exists with the correct local URL (`https://localhost:8087/sse`) and rewrites the file to potentially trigger a refresh in Cursor.

Defines a new `LocalToolsRefreshedEvent`, published by the `ConnectionManager` after its own toolset is updated (`refreshMCPServerTools`). The `CursorConfigManager` subscribes to this event and rewrites the `mcp.json` file upon receiving it.

This allows the Agent Browser to automatically register itself and update its status/tools within the Cursor application without requiring manual configuration or refreshes by the user.
diff --git a/internal/app/app.go b/internal/app/app.go
@@ -7,6 +7,7 @@ import (
 
 	"github.com/co-browser/agent-browser/internal/backend"
 	"github.com/co-browser/agent-browser/internal/backend/database"
+	"github.com/co-browser/agent-browser/internal/cursor"
 	"github.com/co-browser/agent-browser/internal/events"
 	"github.com/co-browser/agent-browser/internal/log"
 	"github.com/co-browser/agent-browser/internal/mcp"
@@ -168,12 +169,24 @@ var WebModule = fx.Module("web",
 	// fx.Invoke(func(sse *handlers.SSEHandler) { /* SSE Listener already started in New */ }),
 )
 
+// CursorModule manages interaction with the ~/.cursor/mcp.json file.
+var CursorModule = fx.Module("cursor",
+	fx.Provide(cursor.NewCursorConfigManager),
+	fx.Invoke(cursor.RegisterEventHandlers),
+)
+
 // InitModule performs initial setup tasks, like seeding the database with default servers
 // and triggering connections for existing servers.
 var InitModule = fx.Module("init",
 	// Use fx.Invoke to run initialization logic after dependencies are ready.
-	fx.Invoke(func(bs backend.Service, bus events.Bus, logger log.Logger) {
-		logger.Info().Msg("Running initialization logic...")
+	fx.Invoke(func(bs backend.Service, bus events.Bus, logger log.Logger, cursorManager *cursor.CursorConfigManager) {
+		// Ensure Agent Browser entry is present in Cursor config on startup
+		if err := cursorManager.EnsureAgentEntry(); err != nil {
+			logger.Error().Err(err).Msg("Failed to ensure Agent Browser entry in Cursor config")
+			// Log error but don't block startup
+		}
+
+		logger.Info().Msg("Running initialization logic for MCP servers...")
 		// Check if any servers already exist in the database.
 		servers, err := bs.ListMCPServers()
 		if err != nil {
@@ -245,6 +258,9 @@ var CoreModules = fx.Options(
 	WebModule,       // Provides the API/UI server (depends on Backend)
 	MCPClientModule, // Connects *out* to other MCPs (depends on Backend, WebClient, Log, Config)
 
+	// Cursor Integration
+	CursorModule, // Manages ~/.cursor/mcp.json
+
 	// Initialization Logic (runs after dependencies are ready)
 	InitModule,
 )
diff --git a/internal/cursor/manager.go b/internal/cursor/manager.go
@@ -0,0 +1,193 @@
+package cursor
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/user"
+	"path/filepath"
+	"sync"
+
+	"github.com/co-browser/agent-browser/internal/events"
+	"github.com/co-browser/agent-browser/internal/log"
+)
+
+const (
+	agentBrowserEntryName = "Agent Browser"
+	agentBrowserURL       = "https://localhost:8087/sse" // Default local agent MCP URL
+	cursorConfigDir       = ".cursor"
+	cursorMCPFile         = "mcp.json"
+)
+
+// ServerEntry defines the structure for server entries within mcp.json
+type ServerEntry struct {
+	URL string `json:"url"`
+}
+
+// MCPServersConfig represents the structure of the mcp.json file
+type MCPServersConfig struct {
+	MCPServers map[string]ServerEntry `json:"mcpServers"`
+}
+
+// CursorConfigManager handles reading and writing the Cursor mcp.json file.
+type CursorConfigManager struct {
+	logger   log.Logger
+	filePath string
+	mu       sync.Mutex // Mutex to protect file writes
+}
+
+// NewCursorConfigManager creates a new manager instance.
+func NewCursorConfigManager(logger log.Logger) (*CursorConfigManager, error) {
+	usr, err := user.Current()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get current user: %w", err)
+	}
+	homeDir := usr.HomeDir
+	if homeDir == "" {
+		return nil, errors.New("failed to get home directory")
+	}
+
+	filePath := filepath.Join(homeDir, cursorConfigDir, cursorMCPFile)
+	logger.Info().Str("path", filePath).Msg("Cursor MCP config path determined")
+
+	return &CursorConfigManager{
+		logger:   logger,
+		filePath: filePath,
+	}, nil
+}
+
+// readConfig reads and parses the mcp.json file.
+// Returns an empty config if the file doesn't exist.
+func (m *CursorConfigManager) readConfig() (*MCPServersConfig, error) {
+	config := &MCPServersConfig{
+		MCPServers: make(map[string]ServerEntry),
+	}
+
+	data, err := os.ReadFile(m.filePath)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			m.logger.Info().Str("path", m.filePath).Msg("Cursor mcp.json not found, will create.")
+			return config, nil // File not found is okay, return empty config
+		}
+		return nil, fmt.Errorf("failed to read %s: %w", m.filePath, err)
+	}
+
+	if len(data) == 0 {
+		// File exists but is empty
+		return config, nil
+	}
+
+	err = json.Unmarshal(data, config)
+	if err != nil {
+		// Log the error but return an empty config to attempt overwrite
+		m.logger.Error().Err(err).Str("path", m.filePath).Msg("Failed to parse existing mcp.json, attempting to overwrite.")
+		return &MCPServersConfig{MCPServers: make(map[string]ServerEntry)}, nil
+	}
+
+	// Ensure the map is initialized if JSON was null/empty map
+	if config.MCPServers == nil {
+		config.MCPServers = make(map[string]ServerEntry)
+	}
+
+	return config, nil
+}
+
+// writeConfig writes the configuration back to mcp.json.
+// It ensures the directory exists.
+func (m *CursorConfigManager) writeConfig(config *MCPServersConfig) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	// Ensure directory exists
+	dir := filepath.Dir(m.filePath)
+	if err := os.MkdirAll(dir, 0750); err != nil { // Use 0750 for permissions
+		return fmt.Errorf("failed to create directory %s: %w", dir, err)
+	}
+
+	// Marshal with indentation for readability
+	data, err := json.MarshalIndent(config, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal mcp.json data: %w", err)
+	}
+
+	// Write file
+	err = os.WriteFile(m.filePath, data, 0640) // Use 0640 for permissions
+	if err != nil {
+		return fmt.Errorf("failed to write %s: %w", m.filePath, err)
+	}
+
+	return nil
+}
+
+// EnsureAgentEntry checks if the Agent Browser entry exists and is correct,
+// adding/updating it if necessary, and then writes the file back.
+func (m *CursorConfigManager) EnsureAgentEntry() error {
+	m.logger.Info().Msg("Ensuring Agent Browser entry in Cursor mcp.json...")
+	config, err := m.readConfig()
+	if err != nil {
+		// Errors during read (other than file not found) are problematic
+		return fmt.Errorf("failed to read cursor config before ensuring entry: %w", err)
+	}
+
+	needsWrite := false
+	entry, exists := config.MCPServers[agentBrowserEntryName]
+
+	if !exists {
+		m.logger.Info().Str("name", agentBrowserEntryName).Msg("Agent Browser entry missing, adding.")
+		config.MCPServers[agentBrowserEntryName] = ServerEntry{URL: agentBrowserURL}
+		needsWrite = true
+	} else if entry.URL != agentBrowserURL {
+		m.logger.Info().Str("name", agentBrowserEntryName).Str("oldURL", entry.URL).Str("newURL", agentBrowserURL).Msg("Agent Browser entry has incorrect URL, updating.")
+		config.MCPServers[agentBrowserEntryName] = ServerEntry{URL: agentBrowserURL}
+		needsWrite = true
+	} else {
+		m.logger.Debug().Str("name", agentBrowserEntryName).Msg("Agent Browser entry already exists and is correct.")
+		// We still rewrite the file to potentially trigger Cursor's refresh mechanism
+		needsWrite = true
+	}
+
+	if needsWrite {
+		m.logger.Info().Msg("Rewriting Cursor mcp.json file...")
+		err = m.writeConfig(config)
+		if err != nil {
+			return fmt.Errorf("failed to write cursor config after ensuring entry: %w", err)
+		}
+		m.logger.Info().Msg("Successfully rewrote Cursor mcp.json file.")
+	} else {
+		m.logger.Info().Msg("No changes needed, but still rewriting Cursor mcp.json file to trigger refresh.")
+		err = m.writeConfig(config)
+		if err != nil {
+			return fmt.Errorf("failed to rewrite cursor config: %w", err)
+		}
+		m.logger.Info().Msg("Successfully rewrote Cursor mcp.json file.")
+	}
+	return nil
+}
+
+// HandleLocalToolsRefreshed handles the event indicating local tools may have changed.
+// It triggers a rewrite of the mcp.json file.
+func (m *CursorConfigManager) HandleLocalToolsRefreshed(event events.Event) {
+	_, ok := event.(*events.LocalToolsRefreshedEvent)
+	if !ok {
+		m.logger.Error().Str("eventType", string(event.Type())).Msg("Received event of unexpected type in HandleLocalToolsRefreshed")
+		return
+	}
+
+	m.logger.Info().Msg("Local tools refreshed event received, triggering Cursor mcp.json rewrite.")
+
+	// Reuse EnsureAgentEntry which handles read/check/write logic
+	if err := m.EnsureAgentEntry(); err != nil {
+		m.logger.Error().Err(err).Msg("Error rewriting mcp.json on LocalToolsRefreshed event")
+	}
+}
+
+// RegisterEventHandlers subscribes the manager to relevant events.
+func RegisterEventHandlers(bus events.Bus, manager *CursorConfigManager) {
+	if manager == nil {
+		// Log or handle error: manager should not be nil
+		return
+	}
+	bus.Subscribe(events.LocalToolsRefreshed, manager.HandleLocalToolsRefreshed)
+	manager.logger.Info().Msg("CursorConfigManager subscribed to LocalToolsRefreshed event.")
+}
diff --git a/internal/events/events.go b/internal/events/events.go
@@ -22,6 +22,8 @@ const (
 	ServerStatusChanged EventType = "server.status.changed"
 	// ToolsProcessedInDB indicates that the backend service has finished processing tools from an update event.
 	ToolsProcessedInDB EventType = "tools.processed.db"
+	// LocalToolsRefreshed indicates the agent's own exposed toolset was potentially updated.
+	LocalToolsRefreshed EventType = "local.tools.refreshed"
 	// Add more event types as needed
 )
 
@@ -138,3 +140,17 @@ func NewToolsProcessedInDBEvent(serverID int64, serverURL string) *ToolsProcesse
 		ServerURL: serverURL,
 	}
 }
+
+// LocalToolsRefreshedEvent is published by the ConnectionManager after refreshMCPServerTools completes.
+// It signals that the list of tools exposed by this agent's MCP server may have changed.
+type LocalToolsRefreshedEvent struct {
+	baseEvent
+	// Add fields if needed later, e.g., count of tools.
+}
+
+// NewLocalToolsRefreshedEvent creates a new LocalToolsRefreshedEvent.
+func NewLocalToolsRefreshedEvent() *LocalToolsRefreshedEvent {
+	return &LocalToolsRefreshedEvent{
+		baseEvent: newBaseEvent(LocalToolsRefreshed),
+	}
+}
diff --git a/internal/mcp/server.go b/internal/mcp/server.go
@@ -985,6 +985,10 @@ func (cm *ConnectionManager) handleToolsProcessed(event events.Event) {
 	cm.mu.Lock()
 	cm.refreshMCPServerTools()
 	cm.mu.Unlock()
+
+	// Publish event to signal that local tools might have changed
+	cm.logger.Info().Msg("Publishing LocalToolsRefreshedEvent after MCP server tool refresh.")
+	cm.eventBus.Publish(events.NewLocalToolsRefreshedEvent())
 }
 
 // refreshMCPServerTools rebuilds the runtime tool state.
