docs(nvim): update instructions.md with correct tool names and new window tools

This commit is contained in:
Riz Ashraf committed 2026-09-23 04:30:38 +01:00
1 parent 4cae55bab3
commit da98391ef9
1 file changed
+15 -29
+15 -29
View File
@@ -3,43 +3,29 @@
When connected to this Neovim MCP server (win-nvim or linux-nvim), you have powerful tools to interact directly with the active Neovim editor.
## The Tool Arsenal
The following tools are available (many should be agerTools):
The following tools are available:
- **File/Buffer Mgmt:**
vim_open_file,
vim_open_buffer,
vim_close_buffer,
vim_split_window,
vim_reload_buffer,
vim_save_buffer
`nvim_open_file`, `nvim_open_buffer`, `nvim_close_buffer`, `nvim_reload_buffer`, `nvim_save_buffer`, `nvim_list_buffers`
- **Window Mgmt:**
`nvim_split_window`, `nvim_close_window`, `nvim_list_windows`, `nvim_get_active_window`, `nvim_set_active_window`
- **State Reading:**
vim_get_active_buffer,
vim_get_cursor,
vim_get_visual_selection,
vim_get_viewport,
vim_get_messages
`nvim_get_active_buffer`, `nvim_get_cursor`, `nvim_goto_line`, `nvim_get_visual_selection`, `nvim_get_viewport`, `nvim_get_messages`
- **Diagnostics & Visuals:**
vim_set_diagnostics,
vim_highlight_lines,
vim_set_quickfix
`nvim_set_diagnostics`, `nvim_get_diagnostics`, `nvim_highlight_lines`, `nvim_set_extmark`, `nvim_set_quickfix`
- **God Mode:**
vim_execute_lua
`nvim_execute_lua`
## 1. Using Dedicated Tools First
Always prefer the specific dedicated tools (like
vim_open_file,
vim_highlight_lines, etc.) over writing raw Lua scripts. These tools are tested and safe.
Always prefer the specific dedicated tools (like `nvim_open_file`, `nvim_highlight_lines`, etc.) over writing raw Lua scripts. These tools are tested and safe.
## 2. Lua God Mode (
vim_execute_lua)
If you need to access *any* Neovim API that does not have a dedicated tool (e.g., complex buffer edits, changing options, LSP interactions), you MUST use
vim_execute_lua as your escape hatch.
## 2. Lua God Mode (`nvim_execute_lua`)
If you need to access *any* Neovim API that does not have a dedicated tool (e.g., complex buffer edits, changing options, LSP interactions), you MUST use `nvim_execute_lua` as your escape hatch.
### CRITICAL RULES for
vim_execute_lua:
1. **Never Block:** Never use interactive prompts ( im.fn.input, im.ui.select, im.fn.confirm) or confirmation flags in regex substitutions (e.g., %s/old/new/gc). This will cause the headless MCP bridge to deadlock forever.
2. **Visual Feedback:** Always trigger a notification using ␍equire("notify")("Antigravity: [Action]", "info", { title = "Antigravity" }).
3. **Auto-Save:** If you modify a file buffer, always save it using im.cmd('write') within the same Lua script so external tools can see the changes, unless you explicitly want to pause for manual human review.
### CRITICAL RULES for `nvim_execute_lua`:
1. **Never Block:** Never use interactive prompts (`vim.fn.input`, `vim.ui.select`, `vim.fn.confirm`) or confirmation flags in regex substitutions (e.g., `%s/old/new/gc`). This will cause the headless MCP bridge to deadlock forever.
2. **Visual Feedback:** Always trigger a notification using `require("notify")("Antigravity: [Action]", "info", { title = "Antigravity" })`.
3. **Auto-Save:** If you modify a file buffer, always save it using `vim.cmd('write')` within the same Lua script so external tools can see the changes, unless you explicitly want to pause for manual human review.
4. **Buffer Focus:** When making changes to a specific buffer, always ensure the active window is switched to that buffer, and optionally move the cursor so the human can see the change visually.
## 3. The "Unix is NOT King" Rule
When Neovim is running and you need to perform file read/writes or search and replace within an opened project, **prioritize Neovim tools over basic unix terminal utilities** (like cat, grep, sed, wk, or PowerShell equivalents). Use Neovim as your primary interface to the codebase.
When Neovim is running and you need to perform file read/writes or search and replace within an opened project, **prioritize Neovim tools over basic unix terminal utilities** (like `cat`, `grep`, `sed`, `awk`, or PowerShell equivalents). Use Neovim as your primary interface to the codebase.