feat: Add tool cache invalidation with differential update logic and manual discovery trigger (#208)

* feat(api): add server tool discovery functionality and auto cache invalidation of tools

- Implemented `discoverServerTools` method in APIService to trigger tool discovery for a specified server.
- Updated ServerDetail.vue to include a button for discovering tools, enhancing user interaction.
- Added backend support for tool discovery in the ServerController and integrated it into the routing.
- Introduced `GetToolsByServer` method in the index manager to retrieve tools associated with a server.
- Enhanced the OpenAPI documentation to reflect the new endpoint for tool discovery.

This feature allows users to manually trigger tool discovery, improving the management of server tools.

* fix: add missing DiscoverServerTools and GetToolsByServer to test mocks

- Add DiscoverServerTools method to MockServerController in contracts_test.go
- Add DiscoverServerTools method to baseController in security_test.go
- Add GetToolsByServer to TestIndexManagerContract expected methods

These methods were added to the interfaces in this PR but the test mocks
were not updated, causing CI failures.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Algis Dumbris <a.dumbris@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

frontend/src/services/api.ts

@@ -243,6 +243,12 @@ class APIService {
     })
   }
 
+  async discoverServerTools(serverName: string): Promise<APIResponse> {
+    return this.request(`/api/v1/servers/${encodeURIComponent(serverName)}/discover-tools`, {
+      method: 'POST',
+    })
+  }
+
   async deleteServer(serverName: string): Promise<APIResponse> {
     return this.callTool('upstream_servers', {
       operation: 'remove',

frontend/src/views/ServerDetail.vue

@@ -86,6 +86,12 @@
                   OAuth Login
                 </button>
               </li>
+              <li v-if="server.enabled && server.connected">
+                <button @click="discoverTools" :disabled="actionLoading">
+                  <span v-if="actionLoading" class="loading loading-spinner loading-xs"></span>
+                  Discover Tools
+                </button>
+              </li>
               <li>
                 <button @click="server.quarantined ? unquarantineServer() : quarantineServer()" :disabled="actionLoading">
                   <span v-if="actionLoading" class="loading loading-spinner loading-xs"></span>
@@ -685,6 +691,43 @@ async function refreshData() {
   await loadServerDetails()
 }
 
+async function discoverTools() {
+  if (!server.value) return
+
+  actionLoading.value = true
+  try {
+    const response = await api.discoverServerTools(server.value.name)
+
+    if (!response.success) {
+      throw new Error(response.error || 'Failed to discover tools')
+    }
+
+    systemStore.addToast({
+      type: 'success',
+      title: 'Tool Discovery Started',
+      message: `Discovering tools for ${server.value.name}...`,
+    })
+
+    // Refresh server details after a short delay to show updated tool count
+    setTimeout(async () => {
+      await loadServerDetails()
+      systemStore.addToast({
+        type: 'info',
+        title: 'Tools Updated',
+        message: `Tool cache refreshed for ${server.value?.name}`,
+      })
+    }, 2000)
+  } catch (error) {
+    systemStore.addToast({
+      type: 'error',
+      title: 'Tool Discovery Failed',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    })
+  } finally {
+    actionLoading.value = false
+  }
+}
+
 function viewToolSchema(tool: Tool) {
   selectedToolSchema.value = tool
 }

internal/appctx/contracts_test.go

@@ -179,6 +179,11 @@ func TestIndexManagerContract(t *testing.T) {
 			in:   []reflect.Type{},
 			out:  []reflect.Type{reflect.TypeOf((*error)(nil)).Elem()},
 		},
+		"GetToolsByServer": {
+			name: "GetToolsByServer",
+			in:   []reflect.Type{reflect.TypeOf("")},
+			out:  []reflect.Type{reflect.TypeOf([]*config.ToolMetadata{}), reflect.TypeOf((*error)(nil)).Elem()},
+		},
 	}
 
 	verifyInterfaceContract(t, interfaceType, expectedMethods)

internal/appctx/interfaces.go

@@ -67,6 +67,7 @@ type IndexManager interface {
 	// Tool management
 	DeleteTool(serverName, toolName string) error
 	DeleteServerTools(serverName string) error
+	GetToolsByServer(serverName string) ([]*config.ToolMetadata, error)
 
 	// Index management
 	RebuildIndex() error

internal/httpapi/contracts_test.go

@@ -285,6 +285,11 @@ func (m *MockServerController) GetVersionInfo() *updatecheck.VersionInfo {
 	return nil
 }
 
+// Tool discovery
+func (m *MockServerController) DiscoverServerTools(_ context.Context, _ string) error {
+	return nil
+}
+
 // Test contract compliance for API responses
 func TestAPIContractCompliance(t *testing.T) {
 	logger := zaptest.NewLogger(t).Sugar()

internal/httpapi/security_test.go

@@ -301,3 +301,6 @@ func (m *baseController) GetToolCallsBySession(sessionID string, limit, offset i
 	return nil, 0, nil
 }
 func (m *baseController) GetVersionInfo() *updatecheck.VersionInfo { return nil }
+func (m *baseController) DiscoverServerTools(_ context.Context, _ string) error {
+	return nil
+}

internal/httpapi/server.go

@@ -53,6 +53,7 @@ type ServerController interface {
 	GetQuarantinedServers() ([]map[string]interface{}, error)
 	UnquarantineServer(serverName string) error
 	GetManagementService() interface{} // Returns the management service for unified operations
+	DiscoverServerTools(ctx context.Context, serverName string) error
 
 	// Tools and search
 	GetServerTools(serverName string) ([]map[string]interface{}, error)
@@ -335,6 +336,7 @@ func (s *Server) setupRoutes() {
 			r.Post("/logout", s.handleServerLogout)
 			r.Post("/quarantine", s.handleQuarantineServer)
 			r.Post("/unquarantine", s.handleUnquarantineServer)
+			r.Post("/discover-tools", s.handleDiscoverServerTools)
 			r.Get("/tools", s.handleGetServerTools)
 			r.Get("/logs", s.handleGetServerLogs)
 			r.Get("/tool-calls", s.handleGetServerToolCalls)
@@ -1054,6 +1056,49 @@ func (s *Server) handleRestartServer(w http.ResponseWriter, r *http.Request) {
 	s.writeSuccess(w, response)
 }
 
+// handleDiscoverServerTools godoc
+// @Summary Discover tools for a specific server
+// @Description Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.
+// @Tags servers
+// @Produce json
+// @Security ApiKeyAuth
+// @Security ApiKeyQuery
+// @Param id path string true "Server ID or name"
+// @Success 200 {object} contracts.ServerActionResponse "Tool discovery triggered successfully"
+// @Failure 400 {object} contracts.ErrorResponse "Bad request (missing server ID)"
+// @Failure 404 {object} contracts.ErrorResponse "Server not found"
+// @Failure 500 {object} contracts.ErrorResponse "Failed to discover tools"
+// @Router /api/v1/servers/{id}/discover-tools [post]
+func (s *Server) handleDiscoverServerTools(w http.ResponseWriter, r *http.Request) {
+	serverID := chi.URLParam(r, "id")
+	if serverID == "" {
+		s.writeError(w, http.StatusBadRequest, "Server ID required")
+		return
+	}
+
+	s.logger.Info("Manual tool discovery triggered via API", "server", serverID)
+
+	if err := s.controller.DiscoverServerTools(r.Context(), serverID); err != nil {
+		s.logger.Error("Failed to discover tools for server", "server", serverID, "error", err)
+		
+		if strings.Contains(err.Error(), "not found") {
+			s.writeError(w, http.StatusNotFound, fmt.Sprintf("Server not found: %s", serverID))
+			return
+		}
+		
+		s.writeError(w, http.StatusInternalServerError, fmt.Sprintf("Failed to discover tools: %v", err))
+		return
+	}
+
+	response := contracts.ServerActionResponse{
+		Server:  serverID,
+		Action:  "discover_tools",
+		Success: true,
+		Async:   false,
+	}
+	s.writeSuccess(w, response)
+}
+
 func (s *Server) toggleServerAsync(serverID string, enabled bool) (bool, error) {
 	errCh := make(chan error, 1)
 	go func() {

internal/index/bleve.go

@@ -339,6 +339,44 @@ func (b *BleveIndex) RebuildIndex() error {
 	return nil
 }
 
+// GetToolsByServer retrieves all tools from a specific server
+func (b *BleveIndex) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error) {
+	// Create a term query for the server name
+	query := bleve.NewTermQuery(serverName)
+	query.SetField("server_name")
+
+	// Create search request with high limit to get all tools
+	searchReq := bleve.NewSearchRequest(query)
+	searchReq.Size = 10000 // Maximum tools per server
+	searchReq.Fields = []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "hash"}
+
+	b.logger.Debug("Querying tools by server", zap.String("server", serverName))
+
+	searchResult, err := b.index.Search(searchReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to query tools by server: %w", err)
+	}
+
+	// Convert results to ToolMetadata
+	var tools []*config.ToolMetadata
+	for _, hit := range searchResult.Hits {
+		toolMeta := &config.ToolMetadata{
+			Name:        getStringField(hit.Fields, "full_tool_name"),
+			ServerName:  getStringField(hit.Fields, "server_name"),
+			Description: getStringField(hit.Fields, "description"),
+			ParamsJSON:  getStringField(hit.Fields, "params_json"),
+			Hash:        getStringField(hit.Fields, "hash"),
+		}
+		tools = append(tools, toolMeta)
+	}
+
+	b.logger.Debug("Found tools for server",
+		zap.String("server", serverName),
+		zap.Int("count", len(tools)))
+
+	return tools, nil
+}
+
 // Helper function to get string field from search results
 func getStringField(fields map[string]interface{}, fieldName string) string {
 	if val, ok := fields[fieldName]; ok {

internal/index/manager.go

@@ -123,3 +123,11 @@ func (m *Manager) GetStats() (map[string]interface{}, error) {
 
 	return stats, nil
 }
+
+// GetToolsByServer retrieves all tools from a specific server
+func (m *Manager) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	return m.bleveIndex.GetToolsByServer(serverName)
+}