Oleks
74 lines
4.2 KiB
Markdown
74 lines
4.2 KiB
Markdown
# Dependencies
|
|
|
|
This plugin **bundles nothing**. It ships only configuration —
|
|
`plugin.json`, `.mcp.json`, one agent, three skills — and ties together a
|
|
chain of components that must already exist on the system. The README says
|
|
it plainly: *"This plugin doesn't ship those — it depends on them."*
|
|
|
|
The plugin's *only direct* dependency is the `mcp-session-pool` endpoint in
|
|
`.mcp.json` (`http://pool.localhost:12010/p/neovim/mcp`). Everything else
|
|
listed here is what makes that endpoint actually return the `vim_*` tools.
|
|
|
|
## Connection path
|
|
|
|
```text
|
|
Claude Code session
|
|
└─ .mcp.json → http://pool.localhost:12010/p/neovim/mcp (Streamable-HTTP)
|
|
└─ 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
|
|
```
|
|
|
|
## Editor side
|
|
|
|
| Dependency | Role | Notes |
|
|
| --- | --- | --- |
|
|
| **Neovim** | The target editor the companion reads and drives. | Must run with an RPC socket (`serverstart` → `/run/user/1000/nvim.sock`, via NixVim `extraConfigLuaPre`). Requires **≥ 0.10** — the `editor-introspect` skill uses `vim.fn.getregion`. |
|
|
| **`coder/claudecode.nvim`** | Neovim plugin loaded inside nvim. | Provides the `:ClaudeCode*` commands and `<leader>a*` keymaps that `claude-code-handoff` drives. Without it the handoff skill has nothing to delegate to. |
|
|
|
|
## MCP bridge chain (emmett systemd services)
|
|
|
|
| Dependency | Role | Notes |
|
|
| --- | --- | --- |
|
|
| **`mcp-neovim-server`** | stdio MCP server that attaches to nvim's msgpack-RPC socket and exposes the `vim_*` tools. | npm package, fetched on demand via `npx -y mcp-neovim-server`. Reads `NVIM_SOCKET_PATH`. |
|
|
| **`supergateway`** | Wraps the stdio `mcp-neovim-server` as a Streamable-HTTP endpoint. | npm package, fetched via `npx -y supergateway`. Run `--stateful` so the pool has a session to pin. |
|
|
| **Node.js / `npx`** | Runtime for the two npm packages above. | The only *hard install* of the chain — `npx -y` fetches the packages themselves on demand. |
|
|
| **`mcp-session-pool`** | M=1 session pooler on `:12010`. The single endpoint `.mcp.json` targets. | Bridges sessionless clients (Claude Code) to the sessionful bridge upstream; re-pins via `/pools/neovim/repin`. Defined under `~/projects/servers/emmett/mcp-session-pool/`. |
|
|
| **`nvim-mcp-bridge`** | Socket-gated systemd service (`:12016`) supervising supergateway + mcp-neovim-server. | Started by a `systemd.path` inotify watch on the nvim socket; stops when the socket disappears. Defined in `~/projects/servers/emmett/nixos/nvim-mcp-bridge.nix`. |
|
|
|
|
### Helpers the bridge service shells out to
|
|
|
|
| Dependency | Role |
|
|
| --- | --- |
|
|
| **`inotify-tools`** (`inotifywait`) | Watches the nvim socket; the bridge exits when the socket is deleted (nvim quit). |
|
|
| **`curl`** | The bridge's `ExecStartPost` POSTs `/pools/neovim/repin` to the pool. |
|
|
| **`bash` + `coreutils`** | The bridge unit's `PATH` — npm spawns `sh`. |
|
|
|
|
## Outer
|
|
|
|
| Dependency | Role | Notes |
|
|
| --- | --- | --- |
|
|
| **`claude` CLI** (Claude Code) | Hosts this plugin. | `neovim.nix` also launches the in-editor session as `claude --agent nvim-agentic:companion` (`coder/claudecode.nvim`'s `terminal_cmd`). |
|
|
|
|
## Host assumption
|
|
|
|
The pool and bridge run as **systemd services under user `oleks` on emmett**
|
|
(the local laptop), so the per-user nvim socket at `/run/user/1000/nvim.sock`
|
|
is directly reachable. The `pool.localhost` hostname is an `/etc/hosts` alias
|
|
(`127.0.0.1`) set in `~/projects/servers/emmett/nixos/configuration.nix`.
|
|
|
|
## Diagnosing a missing chain
|
|
|
|
If the `vim_*` tools are absent from a Claude Code session, walk the three
|
|
breakable links in order:
|
|
|
|
1. **nvim** — running, and did it create the socket at `{{nvim_socket}}`?
|
|
(`ls` it.) No socket ⇒ restart nvim.
|
|
2. **bridge / pool** — `systemctl status nvim-mcp-bridge`; pool status at
|
|
`http://127.0.0.1:12010/pools/neovim`.
|
|
3. **this session** — MCP servers attach once, at `claude` launch. A session
|
|
started before the bridge was up never registers the tools ⇒ restart
|
|
Claude Code.
|