feat: add post-action UX guidance for install, approval, and empty states

Improve user experience after key actions by guiding users to the next
step instead of leaving them without direction.

- My Servers empty state: replace plain text with gradient "Discover MCP
  Servers" button that navigates to the Discover tab
- Discover page post-install: success toast now includes "Go to My
  Servers to enable" action link (servers install disabled by default)
- OAuth consent post-approval: new success screen with "Manage
  Permissions" button guiding users to assign FeatureSets on Clients page
- Move activeNav to Zustand store for cross-component navigation
- Extend Toast component to support optional action buttons (backward
  compatible)

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

apps/desktop/src/App.tsx

@@ -35,7 +35,7 @@ import { ConnectIDEs } from '@/components/ConnectIDEs';
 import { useDataSync } from '@/hooks/useDataSync';
 import { useAnalytics } from '@/hooks/useAnalytics';
 import { initAnalytics, capture, optIn, optOut } from '@/lib/analytics';
-import { useAppStore, useActiveSpace, useViewSpace, useTheme, useAnalyticsEnabled } from '@/stores';
+import { useAppStore, useActiveSpace, useViewSpace, useTheme, useAnalyticsEnabled, useActiveNav, useNavigateTo } from '@/stores';
 import { RegistryPage } from '@/features/registry';
 import { FeatureSetsPage } from '@/features/featuresets';
 import { ClientsPage } from '@/features/clients';
@@ -80,13 +80,12 @@ function McpMuxGlyph({ className }: { className?: string }) {
   );
 }
 
-type NavItem = 'home' | 'registry' | 'servers' | 'spaces' | 'featuresets' | 'clients' | 'settings';
-
 function AppContent() {
   // Sync data from backend on mount
   useDataSync();
 
-  const [activeNav, setActiveNav] = useState<NavItem>('home');
+  const activeNav = useActiveNav();
+  const navigateTo = useNavigateTo();
   const [availableUpdate, setAvailableUpdate] = useState<{ version: string } | null>(null);
 
   // Auto-check for updates on startup (silent check after 5 seconds)
@@ -199,21 +198,21 @@ function AppContent() {
           icon={<Home className="h-4 w-4" />}
           label="Dashboard"
           active={activeNav === 'home'}
-          onClick={() => setActiveNav('home')}
+          onClick={() => navigateTo('home')}
           data-testid="nav-dashboard"
         />
         <SidebarItem
           icon={<Server className="h-4 w-4" />}
           label="My Servers"
           active={activeNav === 'servers'}
-          onClick={() => setActiveNav('servers')}
+          onClick={() => navigateTo('servers')}
           data-testid="nav-my-servers"
         />
         <SidebarItem
           icon={<Server className="h-4 w-4" />}
           label="Discover"
           active={activeNav === 'registry'}
-          onClick={() => setActiveNav('registry')}
+          onClick={() => navigateTo('registry')}
           data-testid="nav-discover"
         />
       </SidebarSection>
@@ -223,14 +222,14 @@ function AppContent() {
           icon={<Globe className="h-4 w-4" />}
           label="Spaces"
           active={activeNav === 'spaces'}
-          onClick={() => setActiveNav('spaces')}
+          onClick={() => navigateTo('spaces')}
           data-testid="nav-spaces"
         />
         <SidebarItem
           icon={<Wrench className="h-4 w-4" />}
           label="FeatureSets"
           active={activeNav === 'featuresets'}
-          onClick={() => setActiveNav('featuresets')}
+          onClick={() => navigateTo('featuresets')}
           data-testid="nav-featuresets"
         />
       </SidebarSection>
@@ -240,7 +239,7 @@ function AppContent() {
           icon={<Monitor className="h-4 w-4" />}
           label="Clients"
           active={activeNav === 'clients'}
-          onClick={() => setActiveNav('clients')}
+          onClick={() => navigateTo('clients')}
           data-testid="nav-clients"
         />
       </SidebarSection>
@@ -250,7 +249,7 @@ function AppContent() {
           icon={<Settings className="h-4 w-4" />}
           label="Settings"
           active={activeNav === 'settings'}
-          onClick={() => setActiveNav('settings')}
+          onClick={() => navigateTo('settings')}
           data-testid="nav-settings"
         />
       </SidebarSection>
@@ -316,7 +315,7 @@ function AppContent() {
               </span>
               <button
                 onClick={() => {
-                  setActiveNav('settings');
+                  navigateTo('settings');
                   setAvailableUpdate(null);
                 }}
                 className="text-blue-500 hover:text-blue-400 font-medium underline underline-offset-2"

apps/desktop/src/components/OAuthConsentModal.tsx

@@ -16,6 +16,7 @@ import { listen } from '@tauri-apps/api/event';
 import { Check, X, AlertCircle, Loader2, Globe, Lock } from 'lucide-react';
 import { Button, Card, CardHeader, CardTitle, CardDescription, CardContent } from '@mcpmux/ui';
 import { listSpaces, type Space } from '@/lib/api/spaces';
+import { useAppStore } from '@/stores';
 import { resolveKnownClientKey } from '@/lib/clientIcons';
 import cursorIcon from '@/assets/client-icons/cursor.svg';
 import vscodeIcon from '@/assets/client-icons/vscode.png';
@@ -72,7 +73,8 @@ type ModalState =
   | { type: 'hidden' }
   | { type: 'loading'; requestId: string }
   | { type: 'error'; requestId: string; error: ConsentError }
-  | { type: 'consent'; details: ConsentRequestDetails };
+  | { type: 'consent'; details: ConsentRequestDetails }
+  | { type: 'approved'; clientName: string };
 
 /** Open a URL using the backend open command (handles custom protocols like cursor://) */
 async function openRedirectUrl(url: string): Promise<void> {
@@ -196,7 +198,7 @@ export function OAuthConsentModal() {
       if (response.success && response.redirect_url) {
         console.log('[OAuth] Approved, redirecting to:', response.redirect_url);
         await openRedirectUrl(response.redirect_url);
-        setModalState({ type: 'hidden' });
+        setModalState({ type: 'approved', clientName: clientAlias || details.clientName });
       } else {
         setProcessError(response.error || 'Failed to approve consent');
       }
@@ -289,6 +291,58 @@ export function OAuthConsentModal() {
     );
   }
 
+  // Approved state - show success with next-step guidance
+  if (modalState.type === 'approved') {
+    const navigateTo = useAppStore.getState().navigateTo;
+    return (
+      <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm">
+        <Card className="animate-in fade-in zoom-in mx-4 w-full max-w-md shadow-xl duration-200">
+          <CardHeader>
+            <div className="flex items-center gap-3">
+              <div className="rounded-full bg-green-500/10 p-2">
+                <Check className="h-6 w-6 text-green-500" />
+              </div>
+              <div>
+                <CardTitle>Client Approved</CardTitle>
+                <CardDescription>
+                  {modalState.clientName} is now connected
+                </CardDescription>
+              </div>
+            </div>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div className="rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--surface))] p-4 text-sm">
+              <p className="font-medium mb-1">Next step: Grant permissions</p>
+              <p className="text-[rgb(var(--muted))]">
+                Assign FeatureSets to control which tools, prompts, and resources this client can access.
+              </p>
+            </div>
+            <div className="flex gap-3">
+              <Button
+                variant="secondary"
+                className="flex-1"
+                onClick={handleDismiss}
+              >
+                Later
+              </Button>
+              <Button
+                variant="primary"
+                className="flex-1"
+                onClick={() => {
+                  navigateTo('clients');
+                  handleDismiss();
+                }}
+                data-testid="go-to-clients-btn"
+              >
+                Manage Permissions →
+              </Button>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
   // Consent state - show approval modal
   const { details } = modalState;
   const scopes = details.scope?.split(' ').filter(Boolean) || ['mcp'];

apps/desktop/src/features/registry/RegistryPage.tsx

@@ -10,7 +10,7 @@ import { useToast, ToastContainer } from '@mcpmux/ui';
 import { useRegistryStore } from '../../stores/registryStore';
 import { ServerCard } from './ServerCard';
 import { ServerDetailModal } from './ServerDetailModal';
-import { useViewSpace } from '@/stores';
+import { useViewSpace, useNavigateTo } from '@/stores';
 import { capture } from '@/lib/analytics';
 
 export function RegistryPage() {
@@ -39,6 +39,7 @@ export function RegistryPage() {
 
   const [localSearch, setLocalSearch] = useState('');
   const viewSpace = useViewSpace();
+  const navigateTo = useNavigateTo();
   const { toasts, success, error: showToastError, dismiss } = useToast();
 
   const itemsPerPage = uiConfig?.items_per_page ?? 24;
@@ -105,7 +106,13 @@ export function RegistryPage() {
     const serverName = server?.name || 'Server';
     try {
       await installServer(id, viewSpace?.id);
-      success('Server installed', `"${serverName}" has been installed`);
+      success('Server installed', `"${serverName}" has been installed`, {
+        duration: 6000,
+        action: {
+          label: 'Go to My Servers to enable →',
+          onClick: () => navigateTo('servers'),
+        },
+      });
     } catch {
       showToastError('Install failed', `Failed to install "${serverName}"`);
     }

apps/desktop/src/features/servers/ServersPage.tsx

@@ -26,7 +26,7 @@ import type { ServerFeature } from '@/lib/api/serverFeatures';
 import { listServerFeaturesByServer } from '@/lib/api/serverFeatures';
 import type { ConnectionStatus, ServerStatusResponse } from '@/lib/api/serverManager';
 import { getServerStatuses as fetchServerStatuses } from '@/lib/api/serverManager';
-import { useViewSpace } from '@/stores';
+import { useViewSpace, useNavigateTo } from '@/stores';
 import { useServerManager } from '@/hooks/useServerManager';
 import { useGatewayEvents, useDomainEvents } from '@/hooks/useDomainEvents';
 import type { GatewayChangedPayload, ServerChangedPayload } from '@/hooks/useDomainEvents';
@@ -192,7 +192,8 @@ export function ServersPage() {
   const [editConfigSpace, setEditConfigSpace] = useState<{ id: string; name: string } | null>(null);
 
   const viewSpace = useViewSpace();
-  
+  const navigateTo = useNavigateTo();
+
   // Event-driven server status management
   const {
     statuses: serverStatuses,
@@ -890,7 +891,13 @@ export function ServersPage() {
         <div className="text-center py-12 text-[rgb(var(--muted))]">
           <div className="text-5xl mb-4">📦</div>
           <p className="text-lg mb-2">No servers installed</p>
-          <p className="text-sm">Visit Discover to install MCP servers</p>
+          <button
+            onClick={() => navigateTo('registry')}
+            className="mt-3 px-6 py-2.5 rounded-lg text-sm font-semibold text-white bg-gradient-to-r from-primary-500 to-purple-500 hover:from-primary-600 hover:to-purple-600 shadow-md hover:shadow-lg transition-all hover:scale-[1.03]"
+            data-testid="discover-servers-btn"
+          >
+            Discover MCP Servers
+          </button>
         </div>
       ) : (
         <div className="space-y-3">

apps/desktop/src/stores/appStore.ts

@@ -7,6 +7,7 @@ const initialState: AppState = {
   spaces: [],
   activeSpaceId: null,
   viewSpaceId: null,
+  activeNav: 'home',
   sidebarCollapsed: false,
   theme: 'system',
   analyticsEnabled: true,
@@ -85,6 +86,12 @@ export const useAppStore = create<AppStore>()(
           }
         }),
 
+      // Navigation
+      navigateTo: (nav) =>
+        set((state) => {
+          state.activeNav = nav;
+        }),
+
       // UI
       toggleSidebar: () =>
         set((state) => {

apps/desktop/src/stores/selectors.ts

@@ -5,6 +5,8 @@ import { Space } from '@/lib/api/spaces';
 export const useSpaces = () => useAppStore((state) => state.spaces);
 export const useActiveSpaceId = () => useAppStore((state) => state.activeSpaceId);
 export const useViewSpaceId = () => useAppStore((state) => state.viewSpaceId);
+export const useActiveNav = () => useAppStore((state) => state.activeNav);
+export const useNavigateTo = () => useAppStore((state) => state.navigateTo);
 export const useTheme = () => useAppStore((state) => state.theme);
 export const useSidebarCollapsed = () => useAppStore((state) => state.sidebarCollapsed);
 export const useAnalyticsEnabled = () => useAppStore((state) => state.analyticsEnabled);

apps/desktop/src/stores/types.ts

@@ -1,11 +1,16 @@
 import { Space } from '@/lib/api/spaces';
 
+export type NavItem = 'home' | 'registry' | 'servers' | 'spaces' | 'featuresets' | 'clients' | 'settings';
+
 export interface AppState {
   // Spaces
   spaces: Space[];
   activeSpaceId: string | null;
   viewSpaceId: string | null;
 
+  // Navigation
+  activeNav: NavItem;
+
   // UI state
   sidebarCollapsed: boolean;
   theme: 'light' | 'dark' | 'system';
@@ -27,6 +32,9 @@ export interface AppActions {
   removeSpace: (id: string) => void;
   updateSpace: (id: string, updates: Partial<Space>) => void;
 
+  // Navigation
+  navigateTo: (nav: NavItem) => void;
+
   // UI
   toggleSidebar: () => void;
   setTheme: (theme: 'light' | 'dark' | 'system') => void;

packages/ui/src/components/common/Toast.tsx

@@ -4,12 +4,18 @@ import { cn } from '../../lib/cn';
 
 export type ToastType = 'success' | 'error' | 'warning' | 'info';
 
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
 export interface ToastProps {
   id: string;
   type: ToastType;
   title: string;
   message?: string;
   duration?: number;
+  action?: ToastAction;
   onClose: (id: string) => void;
 }
 
@@ -33,6 +39,7 @@ export function Toast({
   title,
   message,
   duration = 3000,
+  action,
   onClose,
 }: ToastProps) {
   const Icon = iconMap[type];
@@ -62,6 +69,15 @@ export function Toast({
         {message && (
           <p className="text-xs text-[rgb(var(--muted))] mt-1">{message}</p>
         )}
+        {action && (
+          <button
+            onClick={() => { action.onClick(); onClose(id); }}
+            className="mt-2 text-xs font-semibold text-[rgb(var(--primary))] hover:underline"
+            data-testid="toast-action"
+          >
+            {action.label}
+          </button>
+        )}
       </div>
       <button
         onClick={() => onClose(id)}

packages/ui/src/hooks/useToast.ts

@@ -1,11 +1,12 @@
 import { useState, useCallback } from 'react';
-import { ToastProps, ToastType } from '../components/common/Toast';
+import { ToastProps, ToastType, ToastAction } from '../components/common/Toast';
 
 export interface ToastOptions {
   title: string;
   message?: string;
   type?: ToastType;
   duration?: number;
+  action?: ToastAction;
 }
 
 export function useToast() {
@@ -19,6 +20,7 @@ export function useToast() {
       title: options.title,
       message: options.message,
       duration: options.duration ?? 3000,
+      action: options.action,
       onClose: (toastId: string) => {
         setToasts((prev) => prev.filter((t) => t.id !== toastId));
       },
@@ -29,8 +31,9 @@ export function useToast() {
   }, []);
 
   const success = useCallback(
-    (title: string, message?: string, duration?: number) => {
-      return showToast({ title, message, type: 'success', duration });
+    (title: string, message?: string, options?: number | { duration?: number; action?: ToastAction }) => {
+      const opts = typeof options === 'number' ? { duration: options } : options;
+      return showToast({ title, message, type: 'success', duration: opts?.duration, action: opts?.action });
     },
     [showToast]
   );

packages/ui/src/index.ts

@@ -15,7 +15,7 @@ export { Input } from './components/common/Input';
 export { Card, CardHeader, CardTitle, CardDescription, CardContent } from './components/common/Card';
 export { Switch } from './components/common/Switch';
 export { Toast, ToastContainer } from './components/common/Toast';
-export type { ToastProps, ToastType } from './components/common/Toast';
+export type { ToastProps, ToastType, ToastAction } from './components/common/Toast';
 
 // Hooks
 export { useToast } from './hooks/useToast';