v0.6.0: drop MetaMCP from the neovim path
MetaMCP never re-dials a restarted upstream — proven for both STDIO and STREAMABLE_HTTP upstreams — so it cannot front an ephemeral, editor-bound MCP. The pool now fronts the nvim-mcp-bridge directly: Claude Code -> mcp-session-pool /p/neovim -> nvim-mcp-bridge -> nvim The pool re-establishes on its own (_ensure_pinned re-runs initialize), so an event-driven /repin (fired by the socket-appearance systemd.path oneshot) actually heals the chain. - tool names revert to two-segment mcp__neovim__vim_* (no MetaMCP aggregation prefix) - agents/companion.md + skills + README: surface description and troubleshooting runbook rewritten for the pool->bridge->nvim chain
This commit is contained in:
oleks
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "nvim-agentic-companion",
|
||||
"version": "0.5.0",
|
||||
"version": "0.6.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",
|
||||
|
||||
@@ -8,10 +8,9 @@ It assumes two things are already wired up:
|
||||
1. **`mcp-neovim-server`** reaching the running nvim's RPC socket (default
|
||||
`/run/user/1000/nvim.sock`, created by NixVim's `extraConfigLuaPre`
|
||||
`serverstart` at editor startup). The plugin ships a `.mcp.json` that points
|
||||
the `neovim` MCP server at a **MetaMCP namespace** over Streamable-HTTP
|
||||
(`pool.localhost:12010/p/neovim/mcp`) rather than spawning a per-session
|
||||
`npx` stdio child — one persistent server, shared across sessions. Because of
|
||||
MetaMCP's aggregation, the tools surface as `mcp__neovim__neovim__vim_*`.
|
||||
the `neovim` MCP server at the `mcp-session-pool` over Streamable-HTTP
|
||||
(`pool.localhost:12010/p/neovim/mcp`); the pool fronts a supervised
|
||||
stdio→HTTP bridge. Tools surface as `mcp__neovim__vim_*`.
|
||||
2. **`coder/claudecode.nvim`** loaded inside nvim, with `<leader>a*` keymaps
|
||||
wired (toggle, focus, send, accept/deny diff).
|
||||
|
||||
@@ -23,17 +22,22 @@ one agent and three skills.
|
||||
```text
|
||||
Claude Code session
|
||||
└─ .mcp.json → http://pool.localhost:12010/p/neovim/mcp (Streamable-HTTP)
|
||||
└─ mcp-session-pool (:12010, M=1 session pooler)
|
||||
└─ MetaMCP `neovim` namespace upstream
|
||||
└─ mcp-neovim-server (one persistent stdio child on emmett)
|
||||
└─ mcp-session-pool (:12010, M=1 session pooler, /repin endpoint)
|
||||
└─ nvim-mcp-bridge — supergateway (:12016, --stateful)
|
||||
└─ mcp-neovim-server (stdio child)
|
||||
└─ /run/user/1000/nvim.sock (nvim msgpack-RPC)
|
||||
└─ the running Neovim
|
||||
```
|
||||
|
||||
MetaMCP and the pool both run on emmett as systemd services under user `oleks`,
|
||||
so the per-user socket is directly reachable. If `mcp__neovim__neovim__*` tools
|
||||
are missing, walk the chain top-down: socket exists? `systemctl status metamcp`?
|
||||
session restarted since the wiring landed?
|
||||
No MetaMCP in this path: nvim is ephemeral and MetaMCP never re-dials a
|
||||
restarted upstream. The pool *does* re-establish (a fresh `initialize`), so
|
||||
pool→bridge self-heals. Recovery is event-driven — a `systemd.path` watching
|
||||
the nvim socket fires a oneshot that POSTs `/repin` to the pool when the socket
|
||||
(re)appears; no polling. The pool and bridge run on emmett as systemd services
|
||||
under user `oleks`, so the per-user socket is directly reachable. If
|
||||
`mcp__neovim__*` tools are missing: socket exists? `systemctl status
|
||||
nvim-mcp-bridge`? `http://127.0.0.1:12010/pools/neovim` pinned? session
|
||||
restarted since the wiring landed?
|
||||
|
||||
## Layout
|
||||
|
||||
|
||||
+22
-22
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: companion
|
||||
description: Neovim companion — answers questions about the user's *running* nvim instance and acts inside it on their behalf. Uses `mcp__neovim__neovim__*` tools to introspect live state (buffers, keymaps, diagnostics, loaded plugins, cursor position) and to execute `:` commands / lua. Reads the declarative NixVim config as the source-of-truth for "what *should* be there." For buffer-editing work, hands off to the in-editor `coder/claudecode.nvim` session instead of duplicating it. Trigger on <!-- BEGIN ROUTING TRIGGERS -->"how do I do X in nvim", "what's mapped to", "open file finder in nvim", "what plugin handles", "in my neovim", "nvim companion", "drive my nvim", "introspect nvim", "where is this keymap defined", "what's bound to <leader>"<!-- END ROUTING TRIGGERS -->.
|
||||
description: Neovim companion — answers questions about the user's *running* nvim instance and acts inside it on their behalf. Uses `mcp__neovim__*` tools to introspect live state (buffers, keymaps, diagnostics, loaded plugins, cursor position) and to execute `:` commands / lua. Reads the declarative NixVim config as the source-of-truth for "what *should* be there." For buffer-editing work, hands off to the in-editor `coder/claudecode.nvim` session instead of duplicating it. Trigger on <!-- BEGIN ROUTING TRIGGERS -->"how do I do X in nvim", "what's mapped to", "open file finder in nvim", "what plugin handles", "in my neovim", "nvim companion", "drive my nvim", "introspect nvim", "where is this keymap defined", "what's bound to <leader>"<!-- END ROUTING TRIGGERS -->.
|
||||
color: green
|
||||
tools: Bash, Read, Edit, Write, Glob, Grep, Skill, AskUserQuestion, WebFetch, WebSearch, TodoWrite, mcp__neovim__neovim__*
|
||||
tools: Bash, Read, Edit, Write, Glob, Grep, Skill, AskUserQuestion, WebFetch, WebSearch, TodoWrite, mcp__neovim__*
|
||||
---
|
||||
|
||||
# nvim companion
|
||||
@@ -16,16 +16,15 @@ 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__neovim__*` tools** — `mcp-neovim-server`, which bridges to
|
||||
1. **`mcp__neovim__*` tools** — `mcp-neovim-server`, which bridges to
|
||||
nvim over its msgpack-RPC Unix socket. It is *not* a direct stdio child of
|
||||
this session: it runs once as a MetaMCP namespace upstream on emmett, and
|
||||
the session reaches it over Streamable-HTTP through the session pool at
|
||||
`pool.localhost:12010/p/neovim/mcp`. The triple-segment prefix
|
||||
(`mcp__neovim__neovim__…`) is the MetaMCP aggregation shape — first `neovim`
|
||||
is the `.mcp.json` server key, second is the MetaMCP server name. Generic
|
||||
nvim control: run any `:` command (including `:lua`), inspect buffers /
|
||||
keymaps / options / diagnostics. Available so long as nvim runs with its
|
||||
socket, MetaMCP is up, and the namespace upstream connected. The exact
|
||||
this session: it runs on emmett behind the `nvim-mcp-bridge` (supergateway),
|
||||
and the session reaches it over Streamable-HTTP through `mcp-session-pool`
|
||||
at `pool.localhost:12010/p/neovim/mcp`. The chain is pool → bridge → nvim —
|
||||
no MetaMCP in this path (MetaMCP never re-dials a restarted upstream, and
|
||||
nvim is ephemeral). Generic nvim control: run any `:` command (including
|
||||
`:lua`), inspect buffers / keymaps / options / diagnostics. Available so
|
||||
long as nvim runs with its socket and the bridge + pool are up. The exact
|
||||
tools (note the leaf name is `vim_*`, *not* `nvim_*`):
|
||||
|
||||
| Tool | Use for |
|
||||
@@ -83,27 +82,27 @@ When both surfaces could answer a question, the rule of thumb:
|
||||
designed for the in-editor workflow; using them lets the user accept/reject
|
||||
diffs inline and keeps Claude Code's UX coherent.
|
||||
- **Anything else (keymaps, options, custom lua, plugin state, messages,
|
||||
arbitrary `:` commands) → the `mcp__neovim__neovim__*` tools.** The
|
||||
arbitrary `:` commands) → the `mcp__neovim__*` tools.** The
|
||||
universal screwdriver.
|
||||
- **When in doubt, IDE-link first.** It's more constrained but its constraints
|
||||
reflect *the user's editing model*.
|
||||
|
||||
If you are *not* the in-editor session (you're launched outside, e.g. from a
|
||||
terminal Claude Code session), only the `mcp__neovim__neovim__*` surface
|
||||
terminal Claude Code session), only the `mcp__neovim__*` surface
|
||||
is available — degrade gracefully.
|
||||
|
||||
## How to answer "how do I open the file finder?" (the canonical case)
|
||||
|
||||
Do not guess from training data. The user's keymaps are theirs.
|
||||
|
||||
1. Use `mcp__neovim__neovim__vim_command` to run `:verbose nmap <leader>f` (or
|
||||
1. Use `mcp__neovim__vim_command` to run `:verbose nmap <leader>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 the
|
||||
`mcp__neovim__neovim__vim_command` tool. Do not simulate the keypress
|
||||
`mcp__neovim__vim_command` tool. Do not simulate the keypress
|
||||
unless they specifically want practice.
|
||||
|
||||
## Doing things on the user's behalf
|
||||
@@ -112,7 +111,7 @@ 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 the `mcp__neovim__neovim__vim_command` tool. They reflect how
|
||||
these via the `mcp__neovim__vim_command` tool. 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.
|
||||
@@ -180,17 +179,18 @@ it inline rather than ceremoniously dispatching.
|
||||
|
||||
## When the MCP server is unavailable
|
||||
|
||||
If `mcp__neovim__neovim__*` tools are not present in this session, say
|
||||
If `mcp__neovim__*` tools are not present in this session, say
|
||||
so plainly and degrade gracefully: answer from the declarative config
|
||||
alone. The path has three links that can each break — walk them in
|
||||
order when telling the user what to check:
|
||||
|
||||
1. **nvim** — is it running, and did it create the socket at
|
||||
`{{nvim_socket}}`? (`ls` it.) No socket ⇒ restart nvim.
|
||||
2. **MetaMCP** — the `neovim` namespace upstream runs `mcp-neovim-server`
|
||||
once on emmett. If the socket exists but tools are absent,
|
||||
`systemctl status metamcp` and the pool at
|
||||
`pool.localhost:12010/p/neovim/mcp` are the next suspects.
|
||||
`{{nvim_socket}}`? (`ls` it.) No socket ⇒ restart nvim. On a nvim
|
||||
restart the socket-appearance inotify event re-pins the pool
|
||||
automatically (`nvim-mcp-repin.path` → `.service`).
|
||||
2. **bridge / pool** — if the socket exists but tools are absent,
|
||||
`systemctl status nvim-mcp-bridge` and the pool status at
|
||||
`http://127.0.0.1:12010/pools/neovim` are the next suspects.
|
||||
3. **This session** — MCP servers attach at `claude` launch. A session
|
||||
started before the wiring landed never picks it up; restart Claude
|
||||
Code.
|
||||
|
||||
@@ -12,7 +12,7 @@ description: |
|
||||
buffer", "have Claude edit my file", "send this to Claude in nvim",
|
||||
"let Claude in the editor handle it".
|
||||
disable-model-invocation: false
|
||||
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__neovim__neovim__*
|
||||
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__neovim__*
|
||||
---
|
||||
|
||||
# claude-code-handoff — let the in-editor Claude do the editing
|
||||
@@ -60,7 +60,7 @@ These are defined under `<leader>a*` in
|
||||
|
||||
## The full `:ClaudeCode*` command surface
|
||||
|
||||
When driving the editor via `mcp__neovim__neovim__vim_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__neovim__vim_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 `<leader>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__neovim__vim_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).
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ 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 the `mcp__neovim__neovim__*` tools
|
||||
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
|
||||
@@ -13,7 +13,7 @@ description: |
|
||||
neo-tree", "run this command in my nvim", "go to next diagnostic",
|
||||
"save my buffer".
|
||||
disable-model-invocation: false
|
||||
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__neovim__neovim__*
|
||||
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__neovim__*
|
||||
---
|
||||
|
||||
# editor-act — do things in the user's nvim
|
||||
@@ -24,7 +24,7 @@ For buffer edits, invoke `claude-code-handoff` instead.
|
||||
|
||||
## Preconditions
|
||||
|
||||
`mcp__neovim__neovim__*` tools must be present. If they aren't, stop and tell
|
||||
`mcp__neovim__*` tools must be present. If they aren't, stop and tell
|
||||
the user to restart nvim + Claude Code (see `editor-introspect` for
|
||||
the recovery message).
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: editor-introspect
|
||||
description: |
|
||||
Read-only inspection of the user's running Neovim instance via
|
||||
`mcp__neovim__neovim__*` tools. Use whenever a question depends on the live
|
||||
`mcp__neovim__*` tools. Use whenever a question depends on the live
|
||||
editor state: what is mapped to a key, which buffers are open, what
|
||||
the cursor is on, what diagnostics exist, which plugins are loaded,
|
||||
what the messages buffer says. Returns concrete facts grounded in
|
||||
@@ -12,7 +12,7 @@ description: |
|
||||
"current selection", "what's the cursor on", "any diagnostics",
|
||||
"lualine theme actually applied".
|
||||
disable-model-invocation: false
|
||||
allowed-tools: Bash, Read, Glob, Grep, mcp__neovim__neovim__*
|
||||
allowed-tools: Bash, Read, Glob, Grep, mcp__neovim__*
|
||||
---
|
||||
|
||||
# editor-introspect — read the live nvim instance
|
||||
@@ -24,7 +24,7 @@ for that.
|
||||
## Preconditions
|
||||
|
||||
The user's nvim must be running with an RPC socket reachable by the
|
||||
`mcp-neovim-server` MCP server. If `mcp__neovim__neovim__*` tools are not
|
||||
`mcp-neovim-server` MCP server. If `mcp__neovim__*` tools are not
|
||||
present in this session, **stop and tell the user**:
|
||||
|
||||
> The neovim MCP server isn't connected to this Claude Code session.
|
||||
@@ -38,13 +38,13 @@ Do not try to fake introspection from the config alone.
|
||||
`mcp-neovim-server` exposes these (note the `vim_` prefix, *not*
|
||||
`nvim_`):
|
||||
|
||||
- `mcp__neovim__neovim__vim_command` — run any `:` command, including `:lua`.
|
||||
- `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__neovim__vim_status` — cursor, mode, marks, registers in one
|
||||
- `mcp__neovim__vim_status` — cursor, mode, marks, registers in one
|
||||
call. Use instead of three separate `:lua` calls.
|
||||
- `mcp__neovim__neovim__vim_buffer` — buffer contents with line numbers.
|
||||
- `mcp__neovim__neovim__vim_health` — check the nvim↔server connection; run
|
||||
- `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`
|
||||
@@ -53,7 +53,7 @@ with `:lua print(vim.inspect(<expr>))` and parse the printed output.
|
||||
## The introspection vocabulary
|
||||
|
||||
Queries to reach for first. Unless noted, run each as the `command`
|
||||
argument to `mcp__neovim__neovim__vim_command`.
|
||||
argument to `mcp__neovim__vim_command`.
|
||||
|
||||
### Keymaps
|
||||
|
||||
|
||||
Reference in New Issue
Block a user