🎉v6.0.0 - Workspace-Aware MCP Hub and more!

[ravitemer]

Hey everyone! 🎉

This is a big release! We've completely revolutionized how MCP Hub works with workspace-aware configuration that solves fundamental multi-project workflow issues.

Demo

🔊 Video has sound

workspaces.mp4

🏠 The Problem This Solves

Previously, all MCP servers shared the same configuration and worked from the same directory. This caused issues:

• Wrong Project Context: mcp-server-filesystem accessing the wrong project directory
• Language Server Conflicts: mcp-language-server with wrong workspace configuration
• Environment Variable Issues: Session variables like DBUS_SESSION_BUS_ADDRESS not available to MCP servers
• Manual Configuration Switching: Having to edit global config for every project

✨ What's New in v6.0.0

🏠 Workspace-Aware MCP Hub

Smart Project Detection

MCP Hub now automatically detects project boundaries by looking for:

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

Isolated Hub Instances

Each workspace gets:

• Unique Port: Generated from project path hash (e.g., 40123)
• Isolated Processes: Separate mcp-hub instance with its own servers
• Project Context: Hub starts with cwd set to project directory
• Configuration Merging: Project configs override global settings

Automatic Switching

When you change directories (cd), MCP Hub automatically:

• Detects the new workspace
• Connects to the appropriate hub instance
• Switches to the correct server configuration

🌍 Global Environment Variables

Inject environment variables into ALL MCP servers:

require("mcphub").setup({
  global_env = {
    "DBUS_SESSION_BUS_ADDRESS", -- Array-style: uses os.getenv()
    "OPENAI_API_KEY",
    PROJECT_ROOT = "${PWD}", -- Hash-style: explicit value
  }
})

Or use functions for dynamic variables:

require("mcphub").setup({
  global_env = function(context)
    return {
      "DBUS_SESSION_BUS_ADDRESS",
      WORKSPACE_PORT = tostring(context.port),
      IS_WORKSPACE = context.is_workspace_mode and "true" or "false",
    }
  end
})

🎨 Enhanced UI Experience

Active Hubs Section

View and manage all running workspace hub instances:

Grouped Server Display

Servers organized by config source with visual indicators:

• 🌍 Global: Servers from your global config
• 📁 Project: Servers from project-specific config

Multi-Config Editor

Tab-based interface for editing different config files:

Workspace Actions

• <d>: Kill workspace process (with confirmation)
• <gc>: Change directory to workspace

🛠️ Example Setup

Global Config (~/.config/mcphub/servers.json)

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["@modelcontextprotocol/server-memory"]
    }
  }
}

Project Config (.mcphub/servers.json)

Instead of hardcoding paths, we can use the global_env field to declare variables that are passed on to all MCP servers:

E.g: The working directory of the running process can be declared as below:

  global_env = function(context)
    return {
      CWD = context.cwd,
    }
  end,

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx", 
      "args": ["mcp-server-filesystem", "${CWD}"]
    },
    "lsp": {
      "command": "mcp-language-server",
      "args": [
        "--workspace", "${CWD}",
        "--lsp", "lua-language-server", 
        "--", "--stdio"
      ]
    }
  }
}

⚙️ Configuration

Enable workspace features (enabled by default):

require("mcphub").setup({
  workspace = {
    enabled = true, -- Default: true
    look_for = { ".mcphub/servers.json", ".vscode/mcp.json", ".cursor/mcp.json" },
    reload_on_dir_changed = true, -- Auto-switch on directory change
    port_range = { min = 40000, max = 41000 }, -- Port range for workspace hubs
    get_port = nil, -- Optional custom port function
  },
  global_env = function(context)
    return {
      CWD = context.cwd,
      "DBUS_SESSION_BUS_ADDRESS", -- For session variables
    }
  end,
})

📚 Documentation

Complete workspace guide available: Workspaces

⚡ Getting Started

1. Update MCPHub.nvim to v6.0.0
2. No breaking changes - existing configs work unchanged
3. Create project configs in your project roots using supported file names
4. Use :MCPHub to view active hubs and manage workspaces