From 222035d4febf7f8883bb4e3f40bfe6e24e4945eb Mon Sep 17 00:00:00 2001 From: oleks Date: Thu, 21 May 2026 11:08:54 +0300 Subject: [PATCH] v0.4.0: fix MCP tool names (vim_* not nvim_*) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mcp-neovim-server exposes tools named vim_command, vim_buffer, vim_status, vim_edit, vim_window, vim_file_open, vim_search, etc. — all with a vim_ prefix and with no eval tool. The agent and skills previously referenced mcp__neovim__nvim_command and mcp__neovim__nvim_eval, which do not exist, so every drive/introspect call would have failed to resolve. - agents/companion.md: add the full vim_* tool reference table; note that lua is evaluated via vim_command with :lua print(...) - skills/editor-introspect: add a 'tools you have' section; correct the runnable-via line - skills/editor-act: correct the description's tool references --- .claude-plugin/plugin.json | 2 +- agents/companion.md | 45 +++++++++++++++++++++++------ skills/claude-code-handoff/SKILL.md | 6 ++-- skills/editor-act/SKILL.md | 11 +++---- skills/editor-introspect/SKILL.md | 22 ++++++++++++-- 5 files changed, 65 insertions(+), 21 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 65bbc81..8611141 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "nvim-agentic-companion", - "version": "0.3.0", + "version": "0.4.0", "description": "Neovim companion that pairs the running editor (via mcp-neovim-server) with the official Claude Code IDE plugin (coder/claudecode.nvim). Provides an opinionated agent and skills for introspecting your live nvim state (buffers, keymaps, diagnostics, plugins), driving it on your behalf (open files, run keymaps, execute lua), and handing work cleanly to the in-editor Claude Code session for buffer edits.", "author": { "name": "oleks", diff --git a/agents/companion.md b/agents/companion.md index 234f8cf..4cdf84e 100644 --- a/agents/companion.md +++ b/agents/companion.md @@ -16,10 +16,37 @@ to *do* X for them when that is cheaper than teaching. You have *three* complementary surfaces. Use the one that matches the question. -1. **`mcp__neovim__*` tools** — provided by `mcp-neovim-server` over a Unix - socket. Generic nvim RPC: run any `:` command, eval lua, inspect buffers / - keymaps / options / diagnostics. Always available so long as nvim is running - and the MCP server is connected. Use for arbitrary introspection or driving. +1. **`mcp__neovim__*` tools** — provided by `mcp-neovim-server`, a stdio MCP + server that bridges to nvim over its msgpack-RPC Unix socket. Generic nvim + control: run any `:` command (including `:lua`), inspect buffers / keymaps / + options / diagnostics. Available so long as nvim is running with its socket + and the MCP server is connected. The exact tools (note the `vim_` prefix, + *not* `nvim_`): + + | Tool | Use for | + | -------------------- | ----------------------------------------- | + | `vim_command` | run any `:` command incl. `:lua` (main) | + | `vim_buffer` | buffer contents with line numbers | + | `vim_status` | cursor, mode, marks, registers in one go | + | `vim_edit` | insert / replace / replaceAll buffer text | + | `vim_window` | split / close / navigate windows | + | `vim_file_open` | open a file into a new buffer | + | `vim_buffer_switch` | switch to a buffer by name or number | + | `vim_buffer_save` | save current buffer | + | `vim_search` | search within the current buffer | + | `vim_search_replace` | find-and-replace in the current buffer | + | `vim_grep` | project-wide vimgrep into the quickfix | + | `vim_visual` | create a visual-mode selection | + | `vim_mark` | set a named mark | + | `vim_register` | set register contents | + | `vim_macro` | record / stop / play a macro | + | `vim_tab` | create / close / navigate tabs | + | `vim_fold` | create / open / close / toggle folds | + | `vim_jump` | navigate the jump list | + | `vim_health` | check the nvim-to-server connection | + + There is **no eval tool** — to evaluate lua, call `vim_command` with a + `:lua print(vim.inspect(...))` argument and read the returned output. 2. **`coder/claudecode.nvim` IDE link** — when *you* are the in-editor Claude Code session (launched from `:ClaudeCode`), the editor itself exposes @@ -63,13 +90,13 @@ degrade gracefully. Do not guess from training data. The user's keymaps are theirs. -1. Use `mcp__neovim__nvim_command` to run `:verbose nmap f` (or +1. Use `mcp__neovim__vim_command` to run `:verbose nmap f` (or `:Telescope keymaps` if telescope is loaded) and read the result. 2. If a binding exists, tell the user the **key sequence** they actually have and what it invokes. 3. Cite the line in `{{config_path}}` where it's defined (grep for the action name). -4. If they ask you to *do* it, run the command via `mcp__neovim__nvim_command`. +4. If they ask you to *do* it, run the command via `mcp__neovim__vim_command`. Do not simulate the keypress unless they specifically want practice. ## Doing things on the user's behalf @@ -78,12 +105,12 @@ You may drive the editor. Prefer the user's *own* keymaps and commands over teaching new ones. The hierarchy: 1. **Existing user command** (`:Telescope find_files`, `:Neotree`, etc.) — use - these via `mcp__neovim__nvim_command`. They reflect how the user already + these via `mcp__neovim__vim_command`. They reflect how the user already thinks about their editor. 2. **Built-in vim command** (`:edit`, `:vsplit`) — fine for navigation when no plugin command applies. -3. **Lua eval** (`mcp__neovim__nvim_eval` or running `:lua ...`) — last resort, - for things with no command surface. Keep snippets short and obvious. +3. **Lua via `vim_command`** — call `vim_command` with `:lua ...` for things + with no command surface. Last resort. Keep snippets short and obvious. Things you must **not** do without asking first: diff --git a/skills/claude-code-handoff/SKILL.md b/skills/claude-code-handoff/SKILL.md index 0c89c8d..a8cfcc7 100644 --- a/skills/claude-code-handoff/SKILL.md +++ b/skills/claude-code-handoff/SKILL.md @@ -60,7 +60,7 @@ These are defined under `a*` in ## The full `:ClaudeCode*` command surface -When driving the editor via `mcp__neovim__nvim_command` you have more +When driving the editor via `mcp__neovim__vim_command` you have more than the keymaps above. The complete set: - `:ClaudeCode` — toggle the terminal split. @@ -88,7 +88,7 @@ quoting them. 1. **Confirm the split is open.** Either ask `editor-introspect` to check for a Claude Code buffer/window, or just run - `:ClaudeCode` via `mcp__neovim__nvim_command` — the command is + `:ClaudeCode` via `mcp__neovim__vim_command` — the command is idempotent (toggles, but if already visible the user sees no surprise). @@ -104,7 +104,7 @@ quoting them. neovim.nix add a keymap for ...", say "add a `tw` keymap that toggles wrap, next to the existing wrap-toggle block." Send via `:ClaudeCodeSend` (after selection) or by typing the - prompt into the Claude Code buffer (`mcp__neovim__nvim_command` + prompt into the Claude Code buffer (`mcp__neovim__vim_command` plus an explicit feedkeys is overkill — usually the user can type it themselves once focus is in the split). diff --git a/skills/editor-act/SKILL.md b/skills/editor-act/SKILL.md index 1a4b4b8..a2a2ff1 100644 --- a/skills/editor-act/SKILL.md +++ b/skills/editor-act/SKILL.md @@ -3,11 +3,12 @@ name: editor-act description: | Drive the user's running Neovim instance — open files, run user commands, trigger keymaps, jump to LSP locations, toggle UI, - evaluate small lua snippets. Uses `mcp__neovim__nvim_command` / - `nvim_eval` against the live instance. Prefers the user's own - commands and keymaps over teaching new vim syntax. Will *not* edit - buffer contents — that work is handed off via the - `claude-code-handoff` skill. Trigger on "open in nvim", + evaluate small lua snippets. Uses the `mcp__neovim__*` tools + (`vim_command`, `vim_file_open`, `vim_window`, …) against the live + instance. Prefers the user's own commands and keymaps over teaching + new vim syntax. Will *not* edit buffer contents — that work is + handed off via the `claude-code-handoff` skill. Trigger on + "open in nvim", "jump to definition of", "show file finder", "split this", "toggle neo-tree", "run this command in my nvim", "go to next diagnostic", "save my buffer". diff --git a/skills/editor-introspect/SKILL.md b/skills/editor-introspect/SKILL.md index 229689c..67d81a7 100644 --- a/skills/editor-introspect/SKILL.md +++ b/skills/editor-introspect/SKILL.md @@ -33,11 +33,27 @@ present in this session, **stop and tell the user**: Do not try to fake introspection from the config alone. +## The tools you have + +`mcp-neovim-server` exposes these (note the `vim_` prefix, *not* +`nvim_`): + +- `mcp__neovim__vim_command` — run any `:` command, including `:lua`. + Returns the rendered command output. This is the workhorse for + introspection: pass `:verbose nmap ...`, `:lua print(...)`, etc. +- `mcp__neovim__vim_status` — cursor, mode, marks, registers in one + call. Use instead of three separate `:lua` calls. +- `mcp__neovim__vim_buffer` — buffer contents with line numbers. +- `mcp__neovim__vim_health` — check the nvim↔server connection; run + this first if anything seems disconnected. + +There is **no eval tool**. To get a lua value, call `vim_command` +with `:lua print(vim.inspect())` and parse the printed output. + ## The introspection vocabulary -These are the queries you should reach for first. All are runnable -via `mcp__neovim__nvim_command` (returns the rendered command output) -or `mcp__neovim__nvim_eval` (returns a value). +Queries to reach for first. Unless noted, run each as the `command` +argument to `mcp__neovim__vim_command`. ### Keymaps