From 7fed3a2e771bb721636db838d0494b57d821861d Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Fri, 9 Oct 2026 06:16:29 +0100 Subject: [PATCH] docs(nvim-core): prune obsolete tool names from configuration and docs --- agent-rules/neovim_ux.md | 2 +- agent-rules/nvim_architecture.md | 16 ++++----- agent-rules/nvim_editing.md | 8 ++--- agent-rules/nvim_mcp_enforcement.md | 2 +- mcp_tools_review.md | 4 +-- nvim-core/src/instructions.md | 51 +++++++---------------------- 6 files changed, 27 insertions(+), 56 deletions(-) diff --git a/agent-rules/neovim_ux.md b/agent-rules/neovim_ux.md index 1f005bb..4c72d7b 100644 --- a/agent-rules/neovim_ux.md +++ b/agent-rules/neovim_ux.md @@ -1,6 +1,6 @@ # Neovim UX Protocol & Live Editing -Whenever you need to actively interact with the user's Neovim UI or dynamically inject code edits into their live buffers, use the nvim_execute_lua tool (the "God Mode" escape hatch). +Whenever you need to actively interact with the user's Neovim UI or dynamically inject code edits into their live buffers, use the nvim_exec tool (with action 'lua') (the "God Mode" escape hatch). ## 1. Showing UI Feedback (Agent Notifications) The user has a global Lua table _G.gemini loaded in their Neovim environment. You can use it to pop up a floating notification window when you are starting a background task. diff --git a/agent-rules/nvim_architecture.md b/agent-rules/nvim_architecture.md index 7a0bde0..5bfa24d 100644 --- a/agent-rules/nvim_architecture.md +++ b/agent-rules/nvim_architecture.md @@ -21,7 +21,7 @@ The Antigravity CLI (`agy`) acts as the MCP Client and automatically manages the When `agy` starts up, it reads `mcp_config.json`. If it finds `"win-nvim": { "command": "C:\\Users\\reazul.ashraf\\.local\\bin\\mcp-memory-nvim.exe" }`, it will spawn that binary as a background subprocess using standard `stdio`. 3. **Communication:** - - The LLM requests to use a consolidated tool (e.g., `nvim_view` with action `goto_line`, or `nvim_execute_lua`). + - The LLM requests to use a consolidated tool (e.g., `nvim_workspace` with action `focus`, or `nvim_exec`). - The `agy` CLI sends a JSON-RPC request to the `mcp-memory-nvim` subprocess via its `stdin`. - The Rust MCP Server receives the request, connects to the Neovim active socket/pipe (`~/.gemini/active_nvim.txt` or `\\.\pipe\nvim.*`), sends the Msgpack-RPC command, and writes the JSON-RPC response back to `stdout`. - The `agy` CLI reads the response from `stdout` and returns it to the LLM context. @@ -29,12 +29,10 @@ The Antigravity CLI (`agy`) acts as the MCP Client and automatically manages the ## Capabilities & Requirements To use this architecture, Neovim must run the `gemini-integration.lua` script to broadcast its active socket to `~/.gemini/active_nvim.txt`. -The MCP server provides 7 cohesive domain tools: -1. **`nvim_buffer`** (actions: `get_active`, `read`, `open`, `create_scratch`, `save`, `reload`, `close`, `list`, `search`) -2. **`nvim_window`** (actions: `list`, `get_active`, `focus`, `split`, `close`) -3. **`nvim_view`** (actions: `goto_line`, `get_cursor`, `get_viewport`, `get_selection`) -4. **`nvim_diagnostics`** (actions: `get`, `set`, `set_quickfix`) -5. **`nvim_visual`** (actions: `preview`, `extmark`, `highlight`, `clear_highlight`) -6. **`nvim_execute_lua`** (direct Lua execution escape hatch) -7. **`nvim_system`** (actions: `get_info`, `get_messages`, `send_to_terminal`) +The MCP server provides 5 cohesive mega-tools: +1. **`nvim_buffer`** (actions: `read`, `replace`, `save`, `undo`, `redo`, `create_scratch`) +2. **`nvim_workspace`** (actions: `list_buffers`, `list_windows`, `focus`, `split`, `cwd`) +3. **`nvim_intelligence`** (actions: `hover`, `definition`, `references`, `outline`, `query`, `diagnostics`, `rename`, `code_action`) +4. **`nvim_ui`** (actions: `highlight`, `ghost_text`, `clear`) +5. **`nvim_exec`** (actions: `lua`, `vimscript`, `terminal`) diff --git a/agent-rules/nvim_editing.md b/agent-rules/nvim_editing.md index ebaaa1a..6200cd8 100644 --- a/agent-rules/nvim_editing.md +++ b/agent-rules/nvim_editing.md @@ -16,9 +16,9 @@ File edits must use EXACTLY one of two paths: ## 2. Strict Tool Adherence (No Raw Lua RCE) You must strictly use the specialized, sandboxed Neovim MCP tools: - `nvim_buffer`: For reading, writing, saving, and creating scratch buffers. -- `nvim_window`: For creating splits and focusing panes. -- `nvim_visual`: For highlighting diffs, adding ghost text, and showing previews. -**DO NOT** use `nvim_execute_lua` to mutate editor state. It is restricted to **READ-ONLY** queries. +- `nvim_workspace`: For creating splits and focusing panes. +- `nvim_ui`: For highlighting diffs, adding ghost text, and showing previews. +**DO NOT** use `nvim_exec` (action `lua`) to mutate editor state. It is restricted to **READ-ONLY** queries. ## 3. Headless Quarantine Headless mode (`nvim --headless`) is strictly banned for interactive edits. @@ -26,7 +26,7 @@ Headless mode (`nvim --headless`) is strictly banned for interactive edits. Headless instances are allowed ONLY for non-interactive background batch processing (e.g., project-wide formatting or linting). ## 4. UI Presentation & Chat Console Minimization -Never output large plans, context blocks, or architectural discussions to the chat console if Neovim is running. You MUST use the `nvim_buffer` and `nvim_window` tools to open a vertical split (e.g., `Antigravity_Plan.md` scratch buffer) and present the markdown natively. Reserve the chat console strictly for brief confirmations. +Never output large plans, context blocks, or architectural discussions to the chat console if Neovim is running. You MUST use the `nvim_buffer` and `nvim_workspace` tools to open a vertical split (e.g., `Antigravity_Plan.md` scratch buffer) and present the markdown natively. Reserve the chat console strictly for brief confirmations. ## 5. Visual Cues & Auto-Save When manipulating buffers via MCP: diff --git a/agent-rules/nvim_mcp_enforcement.md b/agent-rules/nvim_mcp_enforcement.md index 6a2f0e1..65293e3 100644 --- a/agent-rules/nvim_mcp_enforcement.md +++ b/agent-rules/nvim_mcp_enforcement.md @@ -3,6 +3,6 @@ When interacting with the user's Neovim editor (e.g., opening a file, moving the cursor, reading the active buffer, setting diagnostics), you MUST ALWAYS use the MCP tools provided by the `win-nvim` (Neovim) MCP server. - You are strictly forbidden from using bash scripts, `nvim --server`, or other raw terminal/shell hacks to remote-control Neovim. -- You must rely entirely on the consolidated MCP tool registry (`nvim_buffer`, `nvim_window`, `nvim_view`, `nvim_diagnostics`, `nvim_visual`, `nvim_execute_lua`, `nvim_system`). +- You must rely entirely on the consolidated MCP tool registry (`nvim_buffer`, `nvim_workspace`, `nvim_intelligence`, `nvim_ui`, `nvim_exec`). - If the tool is eagerly loaded, use it natively as an agent tool. If lazy-loaded, invoke it via the `call_mcp_tool` mechanism. diff --git a/mcp_tools_review.md b/mcp_tools_review.md index 33f72e0..034e21d 100644 --- a/mcp_tools_review.md +++ b/mcp_tools_review.md @@ -10,7 +10,7 @@ Our current MCP ecosystem is highly advanced, utilizing a **Dual-Transport Leade * `process_logs`: Direct file seeking and daemon log management (`watch`, `get`, `clear`). Prevents LLMs from reading multi-megabyte log files. **Score: A** ### 2. Neovim IDE Integration (nvim-core) -* `nvim_buffer`, `nvim_window`, `nvim_view`, `nvim_diagnostics`, `nvim_visual`, `nvim_execute_lua`, `nvim_system`. +* `nvim_buffer`, `nvim_workspace`, `nvim_intelligence`, `nvim_ui`, `nvim_exec`. * **Review:** Exceptional human QoL. The agent interacts with the code where the human's eyes actually are. Ghost text and diagnostic extmarks provide an IDE-like experience usually reserved for closed-source tools like Cursor. **Score: S-Tier** ### 3. Clipboard & Workflow @@ -37,7 +37,7 @@ To push the system to the absolute bleeding edge of autonomous coding, I propose * **The Solution:** Using Tantivy and BERT embeddings in our backend. We index the AST blocks of the codebase in the background. The LLM can query *"Where is the auth token validated?"* and get the exact 3 relevant functions instantly. * **Impact:** Massive token cost reduction (no blind file reading). Instant T2R for codebase exploration. -### 3. `nvim_system` terminal execution (Interactive Execution QoL) +### 3. `nvim_exec` terminal execution (Interactive Execution QoL) * **The Problem:** When the agent runs a background terminal command (`cargo build`, `npm run dev`), the output is hidden from the human, and interactive prompts cause the background task to hang indefinitely. * **The Solution:** Dispatch to Neovim terminal splits where the human can watch the tests run natively, interact with prompts, see ANSI colors, and interact seamlessly. * **Impact:** Massive Human QoL. diff --git a/nvim-core/src/instructions.md b/nvim-core/src/instructions.md index 5023180..33fdf9f 100644 --- a/nvim-core/src/instructions.md +++ b/nvim-core/src/instructions.md @@ -2,48 +2,22 @@ When connected to this Neovim MCP server (`win-nvim`), you have powerful tools to interact directly with the active Neovim editor. -## The Consolidated Tool Arsenal (v2) -The server consolidates granular Neovim operations into 7 smart domain tools: -- **`nvim_buffer`**: Buffer and file management. - - `action: "open_file"`: Open file in buffer (args: `file`, `line`, `col`). - - `action: "open"`: Open buffer (args: `bufnr`). - - `action: "close"`: Close buffer (args: `bufnr`, `force`). - - `action: "reload"`: Reload buffer from disk (args: `bufnr`). - - `action: "save"`: Save buffer to disk (args: `bufnr`). - - `action: "list"`: List all loaded buffers. -- **`nvim_window`**: Window split and focus management. - - `action: "split"`: Split window (args: `direction: "horizontal" | "vertical"`, `file`). - - `action: "close"`: Close window (args: `winnr`). - - `action: "list"`: List open windows. - - `action: "get_active"`: Get active window details. - - `action: "set_active"`: Set active window focus (args: `winnr`). -- **`nvim_view`**: Editor viewport and navigation. - - `action: "get_active_buffer"`: Get active buffer details. - - `action: "get_cursor"`: Get current cursor line/col. - - `action: "goto_line"`: Jump cursor to line (args: `line`, `col`). - - `action: "get_viewport"`: Get visible line range in viewport. - - `action: "get_messages"`: Get Neovim command-line messages. -- **`nvim_diagnostics`**: LSP diagnostics querying and publishing. - - `action: "get"`: Get diagnostics (args: `bufnr`, `severity`). - - `action: "set"`: Set buffer diagnostics (args: `bufnr`, `diagnostics`). -- **`nvim_visual`**: Visual highlighting, extmarks, and quickfix. - - `action: "get_selection"`: Get current visual selection text and range. - - `action: "highlight_lines"`: Highlight line ranges (args: `bufnr`, `hl_group`, `start_line`, `end_line`). - - `action: "set_extmark"`: Place virtual text or sign extmarks (args: `bufnr`, `ns_id`, `line`, `col`, `opts`). - - `action: "set_quickfix"`: Populate quickfix list (args: `items`, `title`). -- **`nvim_execute_lua`**: God Mode arbitrary Lua evaluation. - - Arguments: `code: String`. -- **`nvim_system`**: System diagnostics and connection heartbeat. - - `action: "ping"`: Heartbeat test. - - `action: "status"`: Server and socket bridge health status. +## The Consolidated Tool Arsenal (v3) +The server consolidates granular Neovim operations into 5 smart mega-tools: +- **`nvim_buffer`**: Buffer and file management. Actions: `read`, `replace`, `save`, `undo`, `redo`, `create_scratch`. +- **`nvim_workspace`**: Window split and focus management. Actions: `list_buffers`, `list_windows`, `focus`, `split`, `cwd`. +- **`nvim_intelligence`**: Code intelligence and LSP. Actions: `hover`, `definition`, `references`, `outline`, `query`, `diagnostics`, `rename`, `code_action`. +- **`nvim_ui`**: Visual highlighting, diff previews, and ghost text. Actions: `highlight`, `ghost_text`, `clear`. +- **`nvim_exec`**: Escape hatch for raw evaluation. Actions: `lua`, `vimscript`, `terminal`. ## 1. Using Consolidated Domain Tools First -Always prefer the specific consolidated tools (like `nvim_buffer`, `nvim_window`, `nvim_visual`, etc.) over writing raw Lua scripts. These tools are strongly typed, tested, and safe. +Always prefer the specific consolidated tools (like `nvim_buffer`, `nvim_workspace`, `nvim_ui`, etc.) over writing raw Lua scripts. These tools are strongly typed, tested, and safe. -## 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, custom LSP interactions), you MUST use `nvim_execute_lua` as your escape hatch. +## 2. Lua God Mode (`nvim_exec` with action `lua`) +If you need to access *any* Neovim API that does not have a dedicated tool (e.g., changing options, setting autocmds), you MUST use `nvim_exec` with action `lua` as your escape hatch. +**CRITICAL**: `nvim_exec` is restricted to **READ-ONLY** queries. Do NOT use it to mutate editor state. -### CRITICAL RULES for `nvim_execute_lua`: +### CRITICAL RULES for `nvim_exec` (`lua`): 1. **Never Block:** Never use interactive prompt functions or interactive confirmation flags in 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. @@ -57,4 +31,3 @@ While the headless background instance is great for autonomous, routine tasks, i ## 4. Tool Schema Discovery Do **NOT** grep or search the Rust source code to find tool schemas or arguments. All lazy-loaded MCP tool schemas are automatically cached as JSON files on your disk. To understand a tool's arguments, directly read `~/.gemini/antigravity-cli/mcp/win-nvim/.json` (or linux-nvim). -