Skip to content

Commit 5a11222

Browse files
ravitemerravitemer
committed
docs: make docs
1 parent f100847 commit 5a11222

1 file changed

Lines changed: 178 additions & 12 deletions

File tree

‎doc/mcphub.txt‎

Lines changed: 178 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
*mcphub.nvim.txt* For NVIM v0.10.0 Last change: 2025 July 14
1+
*mcphub.nvim.txt* For NVIM v0.10.0 Last change: 2025 July 18
22

33
==============================================================================
44
Table of Contents *mcphub.nvim-table-of-contents*
@@ -64,8 +64,11 @@ additional benefits. It looks something like:
6464
"mcp-server-fetch"
6565
]
6666
},
67-
"remote-server": {
68-
"url": "https://api.example.com/mcp"
67+
"github": {
68+
"url": "https://api.githubcopilot.com/mcp/",
69+
"headers": {
70+
"Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
71+
}
6972
}
7073
}
7174
}
@@ -130,6 +133,20 @@ These servers provide essential functionality without external dependencies and
130133
offer deep Neovim integration.
131134

132135

136+
WORKSPACE-AWARE CONFIGURATION ~
137+
138+
MCP Hub automatically detects project-local configuration files
139+
(`.mcphub/servers.json`, `.vscode/mcp.json`, `.cursor/mcp.json`) and creates
140+
isolated hub instances for each workspace. This enables:
141+
142+
- **Project-specific servers**: `mcp-server-filesystem` with project paths, `mcp-language-server` with project-specific LSP configurations
143+
- **Isolated environments**: Each project gets its own hub instance and server processes
144+
- **Configuration merging**: Project configs override global settings while preserving global servers
145+
146+
Users can view all active workspace hubs and switch between them seamlessly
147+
through the UI.
148+
149+
133150
CHAT INTEGRATIONS ~
134151

135152
- MCP Hub provides integrations with popular chat plugins like Avante <https://github.com/yetone/avante.nvim>, CodeCompanion <https://github.com/olimorris/codecompanion.nvim>, CopilotChat <https://github.com/CopilotC-Nvim/CopilotChat.nvim>.
@@ -214,6 +231,12 @@ FEATURE SUPPORT MATRIX *mcphub.nvim-what-is-mcp-hub?-feature-support-matrix*
214231
command execution
215232
across all fields
216233

234+
Workspace Management
235+
236+
Project-Local ✅ Automatic detection
237+
Configs and merging with
238+
global config
239+
217240
Advanced
218241

219242
Smart File-watching ✅ Smart updates with
@@ -422,9 +445,17 @@ detail.
422445
--- `mcp-hub` binary related options-------------------
423446
config = vim.fn.expand("~/.config/mcphub/servers.json"), -- Absolute path to MCP Servers config file (will create if not exists)
424447
port = 37373, -- The port `mcp-hub` server listens to
425-
shutdown_delay = 60 * 10 * 000, -- Delay in ms before shutting down the server when last instance closes (default: 10 minutes)
448+
shutdown_delay = 5 * 60 * 000, -- Delay in ms before shutting down the server when last instance closes (default: 5 minutes)
426449
use_bundled_binary = false, -- Use local `mcp-hub` binary (set this to true when using build = "bundled_build.lua")
427450
mcp_request_timeout = 60000, --Max time allowed for a MCP tool or resource to execute in milliseconds, set longer for long running tasks
451+
global_env = {}, -- Global environment variables available to all MCP servers (can be a table or a function returning a table)
452+
workspace = {
453+
enabled = true, -- Enable project-local configuration files
454+
look_for = { ".mcphub/servers.json", ".vscode/mcp.json", ".cursor/mcp.json" }, -- Files to look for when detecting project boundaries
455+
reload_on_dir_changed = true, -- Automatically switch hubs on DirChanged event
456+
port_range = { min = 40000, max = 41000 }, -- Port range for generating unique workspace ports
457+
get_port = nil, -- Optional function returning custom port number. Called when generating ports to allow custom port assignment logic
458+
},
428459

429460
---Chat-plugin related options-----------------
430461
auto_approve = false, -- Auto approve mcp tool calls
@@ -485,6 +516,10 @@ detail.
485516
file_path = nil,
486517
prefix = "MCPHub",
487518
},
519+
520+
-- Global environment variables available to all MCP servers
521+
-- Can be a table or a function(context) -> table
522+
global_env = {},
488523
})
489524
end
490525
}
@@ -537,7 +572,7 @@ to the server URL e.g `http://mydomain.com:customport` or
537572

538573
SHUTDOWN_DELAY ~
539574

540-
Default: `600000` (10 minutes)
575+
Default: `5 * 60 * 000` (5 minutes)
541576

542577
Time in milliseconds to wait before shutting down the `mcp-hub` server when the
543578
last Neovim instance closes. The `mcp-hub` server stays up for 10 minutes after
@@ -587,6 +622,105 @@ See Contributing
587622
detailed development setup.
588623

589624

625+
GLOBAL_ENV ~
626+
627+
Default: `{}`
628+
629+
The `global_env` option lets you inject environment variables into all MCP
630+
servers started by MCPHub. This is useful for secrets, tokens, or session
631+
variables (like `DBUS_SESSION_BUS_ADDRESS`) that should be available to every
632+
server process.
633+
634+
You can use either a table or a function that returns a table. The function
635+
receives the job context (workspace info, port, config files, etc).
636+
637+
638+
TABLE EXAMPLE
639+
640+
>lua
641+
require("mcphub").setup({
642+
global_env = {
643+
-- Array-style: uses os.getenv("VAR")
644+
"DBUS_SESSION_BUS_ADDRESS",
645+
-- Hash-style: explicit value
646+
PROJECT_ROOT = vim.fn.getcwd(),
647+
CUSTOM_VAR = "custom_value",
648+
}
649+
})
650+
<
651+
652+
653+
FUNCTION EXAMPLE
654+
655+
>lua
656+
require("mcphub").setup({
657+
global_env = function(context)
658+
local env = {
659+
"DBUS_SESSION_BUS_ADDRESS",
660+
}
661+
-- Add context-aware variables
662+
if context.is_workspace_mode then
663+
env.WORKSPACE_ROOT = context.workspace_root
664+
env.WORKSPACE_PORT = tostring(context.port)
665+
end
666+
env.CONFIG_FILES = table.concat(context.config_files, ":")
667+
return env
668+
end
669+
})
670+
<
671+
672+
**Notes:** - Array-style entries (`"VAR"`) will use the value from
673+
`os.getenv("VAR")`. - Hash-style entries (`KEY = "value"`) use the explicit
674+
value. - The function receives a context table with fields like `port`, `cwd`,
675+
`config_files`, `is_workspace_mode`, and `workspace_root`.
676+
677+
678+
WORKSPACE ~
679+
680+
Default:
681+
682+
>lua
683+
{
684+
workspace = {
685+
enabled = true,
686+
look_for = { ".mcphub/servers.json", ".vscode/mcp.json", ".cursor/mcp.json" },
687+
reload_on_dir_changed = true,
688+
port_range = { min = 40000, max = 41000 },
689+
get_port = nil,
690+
}
691+
}
692+
<
693+
694+
Enables project-local configuration files. When enabled, MCP Hub automatically
695+
detects project boundaries and creates isolated hub instances with merged
696+
configurations (project overrides global).
697+
698+
- **enabled**: Master switch for workspace functionality
699+
- **look_for**: Files to search for when detecting project boundaries
700+
- **reload_on_dir_changed**: Auto-switch hubs on directory change
701+
- **port_range**: Port range for generating unique workspace ports
702+
- **get_port**: Optional function returning custom port number. Called when generating ports to allow custom port assignment logic
703+
704+
705+
CUSTOM PORT EXAMPLE
706+
707+
>lua
708+
require("mcphub").setup({
709+
workspace = {
710+
get_port = function()
711+
local project_name = vim.fn.fnamemodify(vim.fn.getcwd(), ":t")
712+
if project_name == "critical-project" then
713+
return 45000 -- Use fixed port for specific project
714+
end
715+
return nil -- Use default hash-based port generation
716+
end
717+
}
718+
})
719+
<
720+
721+
See Workspace Guide </workspace> for detailed usage examples.
722+
723+
590724
CHAT-PLUGIN RELATED OPTIONS*mcphub.nvim-configuration-chat-plugin-related-options*
591725

592726

@@ -739,8 +873,8 @@ Default:
739873
<
740874

741875
Configuration options for MCPHub’s builtin tools like `edit_file` tool. View
742-
complete Builtin Tools Documentation </mcp/builtin/> for all available tools
743-
and their configuration options.
876+
complete Builtin Tools Documentation </mcp/builtin/neovim> for all available
877+
tools and their configuration options.
744878

745879

746880
UI ~
@@ -828,6 +962,9 @@ default and supports real-time updates across all Neovim instances. You can set
828962
supports **universal ${} placeholder syntax** for environment variables and
829963
command execution across all configuration fields.
830964

965+
[!TIP] Use the `global_env` option to inject environment variables into all MCP
966+
servers, instead of duplicating them in every server’s `env` field.
967+
831968
MANAGE SERVERS ~
832969

833970
Adding, editing, deleting and securing MCP servers in easy and intuitive with
@@ -2599,7 +2736,36 @@ ADD TOOLS TO AVANTE ~
25992736
CONFIGURE AVANTE INTEGRATION ~
26002737

26012738
By default, MCP server prompts will be available as
2602-
`/mcp:server_name:prompt_name` in avante chat.
2739+
`/mcp:server_name:prompt_name` in avante chat. If you are using `blink.cmp`
2740+
then you also need to configure `Kaiser-Yang/blink-cmp-avante`
2741+
<https://github.com/Kaiser-Yang/blink-cmp-avante>
2742+
2743+
Example blink.cmp configuration ~
2744+
2745+
>lua
2746+
return {
2747+
"saghen/blink.cmp",
2748+
dependencies = {
2749+
"Kaiser-Yang/blink-cmp-avante",
2750+
},
2751+
---@module 'blink.cmp'
2752+
---@type blink.cmp.Config
2753+
opts = {
2754+
sources = {
2755+
default = { "lsp", "avante", "path", "snippets", "buffer" },
2756+
providers = {
2757+
avante = {
2758+
module = "blink-cmp-avante",
2759+
name = "Avante",
2760+
opts = {
2761+
-- options for blink-cmp-avante
2762+
},
2763+
},
2764+
},
2765+
},
2766+
}
2767+
}
2768+
<
26032769

26042770
>lua
26052771
require("mcphub").setup({
@@ -2835,9 +3001,9 @@ Server groups are automatically created based on your connected MCP servers
28353001
when enabled via `make_tools`. Check your MCP Hub UI to see which servers you
28363002
have connected.
28373003

2838-
MCPHub includes powerful builtin servers </mcp/builtin/> like `@neovim` (file
2839-
operations, terminal, LSP) and `@mcphub` (server management) that are always
2840-
available.
3004+
MCPHub includes powerful builtin servers </mcp/builtin/neovim> like `@neovim`
3005+
(file operations, terminal, LSP) and `@mcphub` (server management) that are
3006+
always available.
28413007

28423008

28433009
3. INDIVIDUAL TOOLS (WHEN MAKE_TOOLS = TRUE)
@@ -3290,7 +3456,7 @@ doc/other/architecture.md doc/other/troubleshooting.md
32903456
==============================================================================
32913457
7. Links *mcphub.nvim-links*
32923458

3293-
1. *Image*: doc/https:/github.com/user-attachments/assets/21fe7703-9bc3-4c01-93ce-3230521bd5bf
3459+
1. *Image*: doc/https:/github.com/user-attachments/assets/7c299fbd-4820-4065-8b07-50db66179d3d
32943460
2. *Image*: doc/https:/github.com/user-attachments/assets/201a5804-99b6-4284-9351-348899e62467
32953461
3. *Image*: doc/https:/github.com/user-attachments/assets/64708065-3428-4eb3-82a5-e32d2d1f98c6
32963462
4. *Image*: doc/mcp/https:/github.com/user-attachments/assets/f5c8adfa-601e-4d03-8745-75180a9d3648

0 commit comments

Comments
 (0)