feat(lualine): add global variables API for lazy-loading support

- Add vim.g.mcphub_status, vim.g.mcphub_servers_count, vim.g.mcphub_executing
- Move state tracking logic from lualine extension to hub core
- Update documentation with recommended global variables approach
- Deprecate full lualine component with warning
- Support spinners during hub startup/restart and execution
- Show '-' when hub is stopped or not loaded

Fixes #208

Author: ravitemer

doc/extensions/lualine.md

@@ -1,18 +1,82 @@
 # Lualine Integration
 
-MCP Hub provides a lualine component that can be used to show the status of the MCP Hub and the number of connected servers. Add the component to a lualine section to use it. The following example shows how to add the component to the `lualine_x` section:
+MCP Hub provides multiple ways to integrate with lualine, with the recommended approach using global variables for optimal lazy-loading support.
+
+## Recommended: Global Variables Approach
+
+Use MCPHub's global variables for a lightweight, lazy-load friendly component:
 
 ```lua
 require('lualine').setup {
     sections = {
         lualine_x = {
-            -- Other lualine components in "x" section
-            {require('mcphub.extensions.lualine')}, -- Uses defaults
+            {
+                function()
+                    -- Check if MCPHub is loaded
+                    if not vim.g.loaded_mcphub then
+                        return "󰐻 -"
+                    end
+                    
+                    local count = vim.g.mcphub_servers_count or 0
+                    local status = vim.g.mcphub_status or "stopped"
+                    local executing = vim.g.mcphub_executing
+                    
+                    -- Show "-" when stopped
+                    if status == "stopped" then
+                        return "󰐻 -"
+                    end
+                    
+                    -- Show spinner when executing, starting, or restarting
+                    if executing or status == "starting" or status == "restarting" then
+                        local frames = { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" }
+                        local frame = math.floor(vim.loop.now() / 100) % #frames + 1
+                        return "󰐻 " .. frames[frame]
+                    end
+                    
+                    return "󰐻 " .. count
+                end,
+                color = function()
+                    if not vim.g.loaded_mcphub then
+                        return { fg = "#6c7086" } -- Gray for not loaded
+                    end
+                    
+                    local status = vim.g.mcphub_status or "stopped"
+                    if status == "ready" or status == "restarted" then
+                        return { fg = "#50fa7b" } -- Green for connected
+                    elseif status == "starting" or status == "restarting" then  
+                        return { fg = "#ffb86c" } -- Orange for connecting
+                    else
+                        return { fg = "#ff5555" } -- Red for error/stopped
+                    end
+                end,
+            },
         },
     },
 }
 ```
 
+### Available Global Variables
+
+MCPHub automatically maintains these global variables:
+- `vim.g.loaded_mcphub` - Whether MCPHub plugin is loaded (set by plugin loader)
+- `vim.g.mcphub_status` - Current hub state ("starting", "ready", "stopped", etc.)
+- `vim.g.mcphub_servers_count` - Number of connected servers  
+- `vim.g.mcphub_executing` - Whether a tool/resource is currently executing
+
+
+## Legacy: Full Component (Loads MCPHub) - DEPRECATED
+
+**⚠️ DEPRECATED**: This approach will load MCPHub even with lazy loading enabled and shows a deprecation warning. Use the global variables approach above instead.
+
+```lua
+require('lualine').setup {
+    sections = {
+        lualine_x = {
+            {require('mcphub.extensions.lualine')}, -- Uses defaults
+        },
+    },
+}
+```
 
 #### When MCP Hub is connecting:
 
@@ -26,10 +90,7 @@ require('lualine').setup {
 
 ![image](https://github.com/user-attachments/assets/f6bdeeec-48f7-48de-89a5-22236a52843f)
 
-
-## Usage
-
-#### Options
+### Legacy Component Options
 
 The lualine component accepts the standard lualine options and the following options:
 - `icon`: Icon to display. (default: `"󰐻"`)

doc/mcphub.txt

@@ -1,4 +1,4 @@
-*mcphub.nvim.txt*          For NVIM v0.10.0          Last change: 2025 July 18
+*mcphub.nvim.txt*          For NVIM v0.10.0          Last change: 2025 July 19
 
 ==============================================================================
 Table of Contents                              *mcphub.nvim-table-of-contents*
@@ -3372,16 +3372,84 @@ Resources from MCP servers will also be available as CopilotChat variables `#`.
 
 LUALINE INTEGRATION               *mcphub.nvim-extensions-lualine-integration*
 
-MCP Hub provides a lualine component that can be used to show the status of the
-MCP Hub and the number of connected servers. Add the component to a lualine
-section to use it. The following example shows how to add the component to the
-`lualine_x` section:
+MCP Hub provides multiple ways to integrate with lualine, with the recommended
+approach using global variables for optimal lazy-loading support.
+
+
+RECOMMENDED: GLOBAL VARIABLES APPROACH ~
+
+Use MCPHub’s global variables for a lightweight, lazy-load friendly
+component:
+
+>lua
+    require('lualine').setup {
+        sections = {
+            lualine_x = {
+                {
+                    function()
+                        -- Check if MCPHub is loaded
+                        if not vim.g.loaded_mcphub then
+                            return "󰐻 -"
+                        end
+                        
+                        local count = vim.g.mcphub_servers_count or 0
+                        local status = vim.g.mcphub_status or "stopped"
+                        local executing = vim.g.mcphub_executing
+                        
+                        -- Show "-" when stopped
+                        if status == "stopped" then
+                            return "󰐻 -"
+                        end
+                        
+                        -- Show spinner when executing, starting, or restarting
+                        if executing or status == "starting" or status == "restarting" then
+                            local frames = { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" }
+                            local frame = math.floor(vim.loop.now() / 100) % #frames + 1
+                            return "󰐻 " .. frames[frame]
+                        end
+                        
+                        return "󰐻 " .. count
+                    end,
+                    color = function()
+                        if not vim.g.loaded_mcphub then
+                            return { fg = "#6c7086" } -- Gray for not loaded
+                        end
+                        
+                        local status = vim.g.mcphub_status or "stopped"
+                        if status == "ready" or status == "restarted" then
+                            return { fg = "#50fa7b" } -- Green for connected
+                        elseif status == "starting" or status == "restarting" then  
+                            return { fg = "#ffb86c" } -- Orange for connecting
+                        else
+                            return { fg = "#ff5555" } -- Red for error/stopped
+                        end
+                    end,
+                },
+            },
+        },
+    }
+<
+
+
+AVAILABLE GLOBAL VARIABLES
+
+MCPHub automatically maintains these global variables: - `vim.g.loaded_mcphub`
+- Whether MCPHub plugin is loaded (set by plugin loader) -
+`vim.g.mcphub_status` - Current hub state ("starting", "ready", "stopped",
+etc.) - `vim.g.mcphub_servers_count` - Number of connected servers -
+`vim.g.mcphub_executing` - Whether a tool/resource is currently executing
+
+
+LEGACY: FULL COMPONENT (LOADS MCPHUB) - DEPRECATED ~
+
+**⚠️ DEPRECATED**: This approach will load MCPHub even with lazy loading
+enabled and shows a deprecation warning. Use the global variables approach
+above instead.
 
 >lua
     require('lualine').setup {
         sections = {
             lualine_x = {
-                -- Other lualine components in "x" section
                 {require('mcphub.extensions.lualine')}, -- Uses defaults
             },
         },
@@ -3398,10 +3466,7 @@ WHEN CONNECTED SHOWS NUMBER OF CONNECTED SERVERS:
 WHEN A TOOL OR RESOURCE IS BEING CALLED, SHOWS SPINNER:
 
 
-USAGE ~
-
-
-OPTIONS
+LEGACY COMPONENT OPTIONS
 
 The lualine component accepts the standard lualine options and the following
 options: - `icon`: Icon to display. (default: `"󰐻"`) - `colored`: Enable

lua/mcphub/extensions/lualine.lua

@@ -1,6 +1,11 @@
 --[[
 --NOTE: Having cmd = "MCPHub" or lazy = true in user's lazy config, and adding lualine component using require("mcphub.extensions.lualine") will start the hub indirectly.
 --]]
+
+-- DEPRECATED: This lualine component will load MCPHub even with lazy loading.
+-- Use the global variables approach instead: vim.g.mcphub_status, vim.g.mcphub_servers_count, vim.g.mcphub_executing
+-- See documentation for recommended usage: doc/extensions/lualine.md
+
 local M = require("lualine.component"):extend()
 local utils = require("lualine.utils.utils")
 local spinner_frames = { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" }
@@ -31,6 +36,10 @@ M.HubState = {
 vim.g.mcphub_status = M.HubState.STARTING
 -- Initialize the component
 function M:init(options)
+    vim.notify_once(
+        "MCPHub lualine extension is deprecated. Use global variables instead for better lazy-loading. See :help mcphub-lualine",
+        vim.log.levels.WARN
+    )
     M.super.init(self, options)
     self:create_autocommands()
     self.options = vim.tbl_deep_extend("keep", self.options or {}, default_options)

lua/mcphub/hub.lua

@@ -44,7 +44,7 @@ MCPHub.__index = MCPHub
 --- @param opts table Configuration options
 --- @return MCPHub.Hub
 function MCPHub:new(opts)
-    return setmetatable({
+    local instance = setmetatable({
         port = opts.port,
         server_url = opts.server_url,
         config = opts.config,
@@ -62,6 +62,11 @@ function MCPHub:new(opts)
         on_error = opts.on_error or function() end,
         setup_opts = opts,
     }, MCPHub)
+
+    -- Setup global state tracking
+    instance:_setup_global_state_tracking()
+
+    return instance
 end
 
 --- Resolve context (workspace vs global) for the current directory
@@ -429,6 +434,7 @@ function MCPHub:handle_hub_ready()
     self.ready = true
     self.is_restarting = false
     self.is_starting = false
+    self:_update_global_state()
     self.on_ready(self)
     self:update_servers()
     if State.marketplace_state.status == "empty" then
@@ -442,6 +448,7 @@ function MCPHub:_clean_up()
     self.is_starting = false
     self.is_restarting = false
     State:update_hub_state(constants.HubState.STOPPED)
+    self:_update_global_state()
 end
 
 ---@param msg string
@@ -1066,6 +1073,9 @@ function MCPHub:refresh_native_servers()
 end
 
 function MCPHub:fire_servers_updated()
+    -- Update global state
+    self:_update_global_state()
+
     -- Triggers UI update
     State:notify_subscribers({
         server_state = true,
@@ -1640,4 +1650,32 @@ function MCPHub:get_marketplace_catalog(opts)
     })
 end
 
+--- Update global variables for lualine integration
+function MCPHub:_update_global_state()
+    vim.g.mcphub_status = State.server_state.state
+    vim.g.mcphub_servers_count = #self:get_servers()
+end
+
+--- Setup global variable tracking for tool/resource execution
+function MCPHub:_setup_global_state_tracking()
+    local group = vim.api.nvim_create_augroup("mcphub_global_state", { clear = true })
+
+    -- Track tool/resource/prompt execution
+    vim.api.nvim_create_autocmd("User", {
+        group = group,
+        pattern = { "MCPHubToolStart", "MCPHubResourceStart", "MCPHubPromptStart" },
+        callback = function()
+            vim.g.mcphub_executing = true
+        end,
+    })
+
+    vim.api.nvim_create_autocmd("User", {
+        group = group,
+        pattern = { "MCPHubToolEnd", "MCPHubResourceEnd", "MCPHubPromptEnd" },
+        callback = function()
+            vim.g.mcphub_executing = false
+        end,
+    })
+end
+
 return MCPHub

lua/mcphub/init.lua

@@ -8,6 +8,11 @@ local native = require("mcphub.native")
 local utils = require("mcphub.utils")
 local validation = require("mcphub.utils.validation")
 
+-- Initialize global variables for lualine integration
+vim.g.mcphub_status = "stopped"
+vim.g.mcphub_servers_count = 0
+vim.g.mcphub_executing = false
+
 ---@class MCPHub
 local M = {
     is_native_server = native.is_native_server,