mcphub.nvim

MCPHub.nvim operates using an Express server that manages MCP servers and handles client requests. The lifecycle is designed for multi-instance support, allowing multiple Neovim instances to connect to a single shared hub.

Initialization Sequence

When setup() is called, the following occurs:

1. Pre-flight checks: The plugin checks for the mcp-hub command installation, verifies version compatibility, and checks if a server is already running.
2. Server Startup: If no server is running, it starts mcp-hub with config file watching enabled.
3. Server Binding: An Express server is created at http://localhost:[config.port] or the specified config.server_url.
4. Ready Callback: Once setup is successful, the on_ready callback is triggered, providing access to the hub instance and its REST API.

Multi-instance and Shutdown Behavior

• Shared State: Multiple Neovim instances can connect to the same running server. New instances register as clients.
• Automatic Cleanup: When a Neovim instance closes, it unregisters as a client. The server remains active as long as there is at least one client connected. When the last client unregisters, a shutdown timer is triggered. If a new client connects before the timer expires, the shutdown is canceled.

The req.editor_info field provides a consistent view of the current Neovim editor state, including the last_active buffer and a list of all open buffers. This allows tools to interact with the user's workspace regardless of which plugin triggered the tool.

---@class EditorInfo
---@field last_active BufferInfo # Currently active buffer
---@field buffers BufferInfo[] # List of all buffers

---@class BufferInfo
---@field name string # Buffer name
---@field filename string # Full file path
---@field windows number[] # Window IDs showing this buffer
---@field winnr number # Primary window number
---@field cursor_pos number[] # Cursor position [row, col]
---@field filetype string # Buffer filetype
---@field line_count number # Total lines
---@field is_visible boolean # Whether buffer is visible
---@field is_modified boolean # Whether buffer is modified
---@field is_loaded boolean # Whether buffer is loaded
---@field lastused number # Last used timestamp
---@field bufnr number # Buffer number

-- Example usage:
mcphub.add_tool("buffer", {
    name = "get_info",
    description = "Get buffer information",
    handler = function(req, res)
    local info = req.editor_info
    local active = info.last_active

    -- Access current buffer state
    local details = {
    name = active.filename,
    type = active.filetype,
    lines = active.line_count,
    cursor = active.cursor_pos,
    modified = active.is_modified,
    visible = active.is_visible
    }

    -- List all open buffers
    local buffers = {}
    for _, buf in ipairs(info.buffers) do
    table.insert(buffers, buf.filename)
      end

      return res:text(vim.inspect({
            active = details,
            open_buffers = buffers
            })):send()
                end
})

When a tool or resource is called from a chat plugin, the req.caller field provides context about the calling system. You can use this to adapt behavior (e.g., retrieving the correct buffer from avante or codecompanion).

Supported type values:

• avante
• codecompanion
• hubui

mcphub.add_tool("workspace", {
    name = "analyze_buffer",
    description = "Analyze current buffer",
    handler = function(req, res)
    -- Get correct buffer based on caller
    local bufnr
    if req.caller.type == "codecompanion" then
    -- Get buffer from CodeCompanion chat context
    local chat = req.caller.codecompanion.chat
    bufnr = chat.context.bufnr
    local is_var = req.caller.meta.is_within_variable -- true if called from #variable

    elseif req.caller.type == "avante" then
    -- Get buffer from Avante code context
    bufnr = req.caller.avante.code.bufnr

    elseif req.caller.type == "hubui" then
    -- Using hub UI context
    bufnr = req.caller.hubui.context.bufnr or 0
    end

    -- Use the buffer number
    local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
    return res:text(#lines .. " lines found"):send()
    end
})

Workspaces allow for isolated MCP server setups per project by using project-local configuration files. This enables different server configurations (like filesystem access or LSP settings) for different projects without manually editing a global configuration.

Project Detection

When you open Neovim, MCP Hub searches upward from the current directory for the first available configuration file:

• .mcphub/servers.json (MCP Hub specific)
• .vscode/mcp.json (VS Code compatibility)
• .cursor/mcp.json (Cursor compatibility)

Hub Instance Lifecycle

Each detected workspace triggers the creation of a unique hub instance with:

• Unique port: Generated from a hash of the project path.
• Isolated processes: A separate mcp-hub instance running its own servers.
• Merged configuration: Project-specific configurations override the global configuration.
• Project context: The hub starts with its cwd set to the project directory.

Automatic Switching

If reload_on_dir_changed is enabled, MCP Hub automatically detects new workspaces and switches to the appropriate hub instance when you change directories using :cd.