nvim-mcp 0.1.0__tar.gz

nvim_mcp-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+.uv/
+
+# mypy / type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

nvim_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Burgess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nvim_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: nvim-mcp
+Version: 0.1.0
+Summary: MCP server for AI-assisted control of Neovim via pynvim
+Project-URL: Homepage, https://github.com/paulburgess1357/nvim-mcp
+Author: Paul Burgess
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]
+Requires-Dist: pynvim

nvim_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nvim-mcp"
+version = "0.1.0"
+description = "MCP server for AI-assisted control of Neovim via pynvim"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paul Burgess" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp[cli]",
+    "pynvim",
+]
+
+[project.scripts]
+nvim-mcp = "nvim_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/paulburgess1357/nvim-mcp"
+
+[dependency-groups]
+dev = [
+    "pytest",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nvim_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nvim_mcp-0.1.0/src/nvim_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for Neovim control via pynvim."""
+
+__version__ = "0.1.0"

nvim_mcp-0.1.0/src/nvim_mcp/neovim.py

@@ -0,0 +1,432 @@
+"""NeovimManager: multi-instance socket discovery, connection, and communication."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import stat
+import subprocess
+import time
+from dataclasses import dataclass
+
+import pynvim
+
+
+@dataclass
+class NvimInstance:
+    socket_path: str
+    pid: int
+    cwd: str
+    current_file: str
+
+
+_GET_STATE_LUA = """\
+local wins = {}
+for _, w in ipairs(vim.api.nvim_tabpage_list_wins(0)) do
+    local b = vim.api.nvim_win_get_buf(w)
+    wins[#wins + 1] = {
+        file = vim.api.nvim_buf_get_name(b),
+        modified = vim.bo[b].modified,
+        active = (w == vim.api.nvim_get_current_win()),
+    }
+end
+local modified = {}
+local buf_count = 0
+for _, b in ipairs(vim.api.nvim_list_bufs()) do
+    if vim.bo[b].buflisted and vim.api.nvim_buf_is_loaded(b) then
+        buf_count = buf_count + 1
+        if vim.bo[b].modified then
+            modified[#modified + 1] = vim.api.nvim_buf_get_name(b)
+        end
+    end
+end
+return {
+    file = vim.fn.expand('%:p'),
+    line = vim.fn.line('.'),
+    col = vim.fn.col('.'),
+    mode = vim.fn.mode(),
+    modified = vim.bo.modified,
+    filetype = vim.bo.filetype,
+    total_lines = vim.fn.line('$'),
+    cwd = vim.fn.getcwd(),
+    relativenumber = vim.wo.relativenumber,
+    windows = wins,
+    modified_buffers = modified,
+    buffer_count = buf_count,
+}
+"""
+
+_EXEC_COMMAND_LUA = """\
+local input = ...
+vim.v.errmsg = ''
+local ok, result = pcall(vim.api.nvim_exec2, input, {output = true})
+local output = ok and (result.output or '') or ''
+local errmsg = vim.v.errmsg
+if not ok then errmsg = tostring(result) end
+return {output = output, errmsg = errmsg}
+"""
+
+
+class NeovimManager:
+    def __init__(self) -> None:
+        self._nvim: pynvim.Nvim | None = None
+        self._socket_path: str | None = None
+        self._lock = asyncio.Lock()
+        self._discovery_cache: tuple[float, list[NvimInstance]] | None = None
+        self._discovery_cache_ttl = 30.0
+
+    # -- Discovery -----------------------------------------------------------
+
+    async def discover(self) -> list[NvimInstance]:
+        if self._discovery_cache is not None:
+            ts, cached = self._discovery_cache
+            if time.monotonic() - ts < self._discovery_cache_ttl:
+                return list(cached)
+
+        candidates = self._all_sockets()
+
+        async def _probe_with_timeout(sock: str) -> NvimInstance | None:
+            try:
+                return await asyncio.wait_for(
+                    asyncio.to_thread(self._probe_socket, sock),
+                    timeout=5.0,
+                )
+            except (asyncio.TimeoutError, Exception):
+                return None
+
+        results = await asyncio.gather(
+            *(_probe_with_timeout(s) for s in candidates)
+        )
+        instances = [r for r in results if r is not None]
+        self._discovery_cache = (time.monotonic(), instances)
+        return instances
+
+    # -- Connection ----------------------------------------------------------
+
+    async def connect(
+        self,
+        socket_path: str | None = None,
+        terminal_pid: int | None = None,
+        index: int | None = None,
+    ) -> str:
+        instances = await self.discover()
+
+        if socket_path is not None:
+            target = socket_path
+        elif terminal_pid is not None:
+            target = self._find_socket_for_terminal(terminal_pid, instances)
+            if target is None:
+                return (
+                    f"Error: no Neovim instance found for terminal PID "
+                    f"{terminal_pid}."
+                )
+        elif index is not None:
+            if index < 1 or index > len(instances):
+                return (
+                    f"Error: index {index} out of range. "
+                    f"Found {len(instances)} instance(s)."
+                )
+            target = instances[index - 1].socket_path
+        elif len(instances) == 1:
+            target = instances[0].socket_path
+        elif len(instances) == 0:
+            return "Error: no Neovim instances found. Is Neovim running?"
+        else:
+            return self._format_instance_list(instances)
+
+        async with self._lock:
+            try:
+                nvim = await asyncio.wait_for(
+                    asyncio.to_thread(pynvim.attach, "socket", path=target),
+                    timeout=5.0,
+                )
+            except (asyncio.TimeoutError, OSError) as e:
+                return f"Error: could not connect to {target}: {e}"
+
+            self._nvim = nvim
+            self._socket_path = target
+
+            try:
+                state = await asyncio.to_thread(self._get_state_sync)
+                cwd = state.get("cwd", "?")
+                current_file = state.get("file", "") or "(none)"
+            except Exception:
+                cwd = "?"
+                current_file = "?"
+
+        return f"Connected to nvim at {target} (cwd: {cwd}, file: {current_file})"
+
+    # -- Send ----------------------------------------------------------------
+
+    async def send(self, input: str, mode: str) -> str:
+        async with self._lock:
+            if self._nvim is None:
+                err = await self._auto_connect_unlocked()
+                if err is not None:
+                    return err
+            try:
+                return await asyncio.to_thread(self._send_sync, input, mode)
+            except (OSError, pynvim.NvimError) as e:
+                if not self._is_connection_error(e):
+                    raise
+                await self._reconnect_unlocked()
+                return await asyncio.to_thread(self._send_sync, input, mode)
+
+    def _send_sync(self, input: str, mode: str) -> str:
+        assert self._nvim is not None
+
+        if mode == "command":
+            result = self._nvim.exec_lua(_EXEC_COMMAND_LUA, input)
+            output = result.get("output", "") or ""
+            errmsg = result.get("errmsg", "") or ""
+            parts: list[str] = []
+            if output:
+                parts.append(output)
+            if errmsg:
+                parts.append(f"E: {errmsg}")
+            return "\n".join(parts) if parts else "(no output)"
+
+        if mode == "eval":
+            try:
+                result = self._nvim.eval(input)
+                return str(result)
+            except pynvim.NvimError as e:
+                if self._is_connection_error(e):
+                    raise
+                return f"Error: {e}"
+
+        if mode == "keys":
+            self._nvim.input("<Esc>" + input)
+            return f"Keys sent: {input}"
+
+        return f"Error: unknown mode {mode!r}. Use 'command', 'eval', or 'keys'."
+
+    # -- State ---------------------------------------------------------------
+
+    async def get_state(self) -> dict:
+        async with self._lock:
+            if self._nvim is None:
+                err = await self._auto_connect_unlocked()
+                if err is not None:
+                    raise RuntimeError(err)
+            try:
+                return await asyncio.to_thread(self._get_state_sync)
+            except (OSError, pynvim.NvimError) as e:
+                if not self._is_connection_error(e):
+                    raise
+                await self._reconnect_unlocked()
+                return await asyncio.to_thread(self._get_state_sync)
+
+    def _get_state_sync(self) -> dict:
+        assert self._nvim is not None
+        return self._nvim.exec_lua(_GET_STATE_LUA)
+
+    # -- Auto-connect (called with lock held) --------------------------------
+
+    async def _auto_connect_unlocked(self) -> str | None:
+        """Auto-connect when a single instance exists.
+
+        Returns an error message if connection fails, None on success.
+        Must be called with ``self._lock`` held.
+        """
+        instances = await self.discover()
+        if len(instances) == 0:
+            return "Error: no Neovim instances found. Is Neovim running?"
+        if len(instances) > 1:
+            return (
+                "Error: multiple Neovim instances found. Connect first:\n"
+                + self._format_instance_list(instances)
+            )
+
+        target = instances[0].socket_path
+        try:
+            nvim = await asyncio.wait_for(
+                asyncio.to_thread(pynvim.attach, "socket", path=target),
+                timeout=5.0,
+            )
+        except (asyncio.TimeoutError, OSError) as e:
+            return f"Error: could not auto-connect to {target}: {e}"
+
+        self._nvim = nvim
+        self._socket_path = target
+        return None
+
+    # -- Reconnect (called with lock held) -----------------------------------
+
+    async def _reconnect_unlocked(self) -> None:
+        """Re-attach to the last-known socket.
+
+        Must be called with ``self._lock`` held.
+        """
+        if self._nvim is not None:
+            try:
+                self._nvim.close()
+            except Exception:
+                pass
+        self._nvim = None
+
+        if self._socket_path is None:
+            raise RuntimeError("Cannot reconnect: no previous socket path.")
+
+        try:
+            self._nvim = await asyncio.wait_for(
+                asyncio.to_thread(
+                    pynvim.attach, "socket", path=self._socket_path
+                ),
+                timeout=5.0,
+            )
+        except (asyncio.TimeoutError, OSError) as e:
+            raise RuntimeError(
+                f"Reconnect to {self._socket_path} failed: {e}"
+            ) from e
+
+    # -- Socket discovery (synchronous) --------------------------------------
+
+    @staticmethod
+    def _all_sockets() -> list[str]:
+        override = os.environ.get("NVIM_SOCKET_PATH")
+        if override:
+            try:
+                real = os.path.realpath(override)
+                st = os.stat(real)
+                if stat.S_ISSOCK(st.st_mode):
+                    return [real]
+            except OSError:
+                pass
+
+        search_dirs: list[str] = []
+
+        xdg = os.environ.get("XDG_RUNTIME_DIR")
+        if xdg:
+            search_dirs.append(xdg)
+
+        try:
+            run_user = f"/run/user/{os.getuid()}"
+            search_dirs.append(run_user)
+        except AttributeError:
+            pass  # os.getuid() unavailable on Windows
+
+        tmpdir = os.environ.get("TMPDIR")
+        if tmpdir:
+            search_dirs.append(tmpdir)
+        search_dirs.append("/tmp")
+
+        seen: set[str] = set()
+        results: list[str] = []
+
+        for base_dir in search_dirs:
+            if not os.path.isdir(base_dir):
+                continue
+            for root, dirnames, filenames in os.walk(base_dir, followlinks=False):
+                rel = os.path.relpath(root, base_dir)
+                depth = 0 if rel == "." else rel.count(os.sep) + 1
+
+                all_entries = filenames + list(dirnames)
+
+                if depth >= 4:
+                    dirnames.clear()
+
+                for name in all_entries:
+                    if not name.startswith("nvim"):
+                        continue
+                    full = os.path.join(root, name)
+                    try:
+                        st = os.stat(full)
+                    except OSError:
+                        continue
+                    if not stat.S_ISSOCK(st.st_mode):
+                        continue
+                    real = os.path.realpath(full)
+                    if real not in seen:
+                        seen.add(real)
+                        results.append(full)
+
+        return results
+
+    @staticmethod
+    def _probe_socket(sock: str) -> NvimInstance | None:
+        try:
+            nvim = pynvim.attach("socket", path=sock)
+        except Exception:
+            return None
+        try:
+            pid: int = nvim.eval("getpid()")
+            cwd: str = nvim.eval("getcwd()")
+            current_file: str = nvim.eval("expand('%:p')")
+            return NvimInstance(
+                socket_path=sock,
+                pid=pid,
+                cwd=cwd,
+                current_file=current_file,
+            )
+        except Exception:
+            return None
+        finally:
+            try:
+                nvim.close()
+            except Exception:
+                pass
+
+    @staticmethod
+    def _find_socket_for_terminal(
+        terminal_pid: int, instances: list[NvimInstance]
+    ) -> str | None:
+        descendants: set[int] = set()
+        to_visit = [terminal_pid]
+        while to_visit:
+            pid = to_visit.pop()
+            if pid in descendants:
+                continue
+            descendants.add(pid)
+            try:
+                result = subprocess.run(
+                    ["pgrep", "-P", str(pid)],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    for line in result.stdout.strip().splitlines():
+                        child = int(line.strip())
+                        if child not in descendants:
+                            to_visit.append(child)
+            except (subprocess.TimeoutExpired, ValueError, OSError):
+                pass
+
+        for inst in instances:
+            if inst.pid in descendants:
+                return inst.socket_path
+        return None
+
+    @staticmethod
+    def _is_connection_error(e: Exception) -> bool:
+        if isinstance(e, (
+            BrokenPipeError,
+            ConnectionRefusedError,
+            ConnectionResetError,
+            ConnectionAbortedError,
+        )):
+            return True
+        if isinstance(e, OSError) and not isinstance(e, pynvim.NvimError):
+            return True
+        if isinstance(e, pynvim.NvimError):
+            msg = str(e).lower()
+            return any(
+                kw in msg
+                for kw in ("eof", "broken pipe", "connection", "transport", "closed")
+            )
+        return False
+
+    @staticmethod
+    def _format_instance_list(instances: list[NvimInstance]) -> str:
+        lines = ["Multiple Neovim instances found:"]
+        for i, inst in enumerate(instances, 1):
+            file_display = inst.current_file or "(none)"
+            lines.append(
+                f"  {i}. {inst.socket_path} "
+                f"(cwd: {inst.cwd}, file: {file_display})"
+            )
+        lines.append(
+            "\nUse index=N, socket_path=..., or terminal_pid=... to select one."
+        )
+        return "\n".join(lines)

nvim_mcp-0.1.0/src/nvim_mcp/recipes.md

@@ -0,0 +1,156 @@
+## Files
+
+- Open file: nvim_send(input="e /path/to/file", mode="command")
+- Open file in new window: nvim_send(input="sp /path/to/file", mode="command")
+- Open file in vertical split: nvim_send(input="vs /path/to/file", mode="command")
+- Save: nvim_send(input="w", mode="command")
+- Save all buffers: nvim_send(input="wa", mode="command")
+- Save as: nvim_send(input="saveas /path/to/newfile", mode="command")
+- Write to path without switching buffer: nvim_send(input="w /path/to/file", mode="command")
+- Close buffer: nvim_send(input="bd", mode="command")
+- Close buffer force (discard changes): nvim_send(input="bd!", mode="command")
+- Wipe buffer: nvim_send(input="bwipe", mode="command")
+- Reload from disk if unchanged: nvim_send(input="checktime", mode="command")
+- Force reload from disk: nvim_send(input="e!", mode="command")
+- New empty buffer: nvim_send(input="enew", mode="command")
+- Alternate file: nvim_send(input="e #", mode="command")
+- Print current file path: nvim_send(input="echo expand('%:p')", mode="command")
+- Change directory for session: nvim_send(input="cd /path/to/dir", mode="command")
+
+## Navigation
+
+- Go to line N: nvim_send(input="42", mode="command")
+- Go to first line: nvim_send(input="1", mode="command")
+- Go to last line: nvim_send(input="$", mode="command")
+- Jump to matching bracket: nvim_send(input="%", mode="keys")
+- Older jump-list position: nvim_send(input="<C-o>", mode="keys")
+- Newer jump-list position: nvim_send(input="<C-i>", mode="keys")
+- Older change position: nvim_send(input="g;", mode="keys")
+- Newer change position: nvim_send(input="g,", mode="keys")
+- Last edit line: nvim_send(input="`.", mode="keys")
+- Local definition (buffer symbol): nvim_send(input="gd", mode="keys")
+- Local declaration: nvim_send(input="gD", mode="keys")
+- Show jump list: nvim_send(input="jumps", mode="command")
+- Show change list: nvim_send(input="changes", mode="command")
+- Center cursor line: nvim_send(input="zz", mode="keys")
+- Scroll cursor to top: nvim_send(input="zt", mode="keys")
+- Scroll cursor to bottom: nvim_send(input="zb", mode="keys")
+
+## Buffers
+
+- List buffers: nvim_send(input="buffers", mode="command")
+- Same as ls: nvim_send(input="ls!", mode="command")
+- Switch by number: nvim_send(input="b 3", mode="command")
+- Switch by name/pattern: nvim_send(input="buffer foo", mode="command")
+- Next buffer: nvim_send(input="bnext", mode="command")
+- Previous buffer: nvim_send(input="bprevious", mode="command")
+- First buffer: nvim_send(input="bfirst", mode="command")
+- Last buffer: nvim_send(input="blast", mode="command")
+- Delete buffer: nvim_send(input="bdelete", mode="command")
+- Delete buffer N: nvim_send(input="3bdelete", mode="command")
+- Wipe buffer: nvim_send(input="bwipeout", mode="command")
+- Buffer info (name, modified): nvim_send(input="echo bufname('%') .. ' ' .. (&modified ? '[+]' : '')", mode="command")
+- Count lines in buffer: nvim_send(input="echo line('$')", mode="command")
+
+## Windows & Tabs
+
+- Horizontal split: nvim_send(input="split", mode="command")
+- Horizontal split file: nvim_send(input="split /path/to/file", mode="command")
+- Vertical split: nvim_send(input="vsplit", mode="command")
+- Vertical split file: nvim_send(input="vsplit /path/to/file", mode="command")
+- New window: nvim_send(input="new", mode="command")
+- New vertical window: nvim_send(input="vnew", mode="command")
+- Close window: nvim_send(input="close", mode="command")
+- Close window force: nvim_send(input="close!", mode="command")
+- Only this window: nvim_send(input="only", mode="command")
+- Move to next window: nvim_send(input="wincmd w", mode="command")
+- Move to previous window: nvim_send(input="wincmd W", mode="command")
+- Move down: nvim_send(input="wincmd j", mode="command")
+- Move up: nvim_send(input="wincmd k", mode="command")
+- Move left: nvim_send(input="wincmd h", mode="command")
+- Move right: nvim_send(input="wincmd l", mode="command")
+- Move to top-left: nvim_send(input="wincmd t", mode="command")
+- Move to bottom-right: nvim_send(input="wincmd b", mode="command")
+- Swap with next: nvim_send(input="wincmd x", mode="command")
+- Equal width/height: nvim_send(input="wincmd =", mode="command")
+- Max height: nvim_send(input="wincmd _", mode="command")
+- Max width: nvim_send(input="wincmd |", mode="command")
+- Resize height +N: nvim_send(input="resize +5", mode="command")
+- Resize width +N: nvim_send(input="vertical resize +10", mode="command")
+- New tab: nvim_send(input="tabnew", mode="command")
+- New tab with file: nvim_send(input="tabnew /path/to/file", mode="command")
+- Close tab: nvim_send(input="tabclose", mode="command")
+- Close other tabs: nvim_send(input="tabonly", mode="command")
+- Next tab: nvim_send(input="tabnext", mode="command")
+- Previous tab: nvim_send(input="tabprevious", mode="command")
+- Go to tab N: nvim_send(input="tabn 2", mode="command")
+- List tabs: nvim_send(input="tabs", mode="command")
+
+## Marks
+
+- Set local mark a at cursor: nvim_send(input="lua local r,c=vim.api.nvim_win_get_cursor(0); vim.api.nvim_buf_set_mark(0, 'a', r, c)", mode="command")
+- Set global mark A (cross-file): nvim_send(input="lua local r,c=vim.api.nvim_win_get_cursor(0); vim.api.nvim_buf_set_mark(0, 'A', r, c)", mode="command")
+- Jump to mark a (current buffer): nvim_send(input="'a", mode="keys")
+- Jump to global mark A: nvim_send(input="'A", mode="keys")
+- Jump to mark exact column: nvim_send(input="`a", mode="keys")
+- List marks: nvim_send(input="marks", mode="command")
+- Delete mark a: nvim_send(input="delmarks a", mode="command")
+- Delete marks a-c: nvim_send(input="delmarks a b c", mode="command")
+- Delete all marks in buffer: nvim_send(input="delmarks!", mode="command")
+- Last insert end: nvim_send(input="'^", mode="keys")
+- Last change start: nvim_send(input="'[", mode="keys")
+- Last change end: nvim_send(input="']", mode="keys")
+- Visual selection start: nvim_send(input="'<", mode="keys")
+- Visual selection end: nvim_send(input="'>", mode="keys")
+
+## Registers
+
+- Get register a as string (eval result): nvim_send(input="getreg('a')", mode="eval")
+- Set register a: nvim_send(input="let @a = 'text'", mode="command")
+- Append to register a: nvim_send(input="let @A = @A .. 'more'", mode="command")
+- List registers: nvim_send(input="registers", mode="command")
+- Yank line to register a: nvim_send(input="lua vim.fn.setreg('a', vim.fn.getline('.'))", mode="command")
+- Black hole register (discard yank target): nvim_send(input="let @_ = @a", mode="command")
+- System clipboard get: nvim_send(input="getreg('+')", mode="eval")
+- System clipboard set: nvim_send(input="let @+ = 'text'", mode="command")
+- Primary selection get (X11): nvim_send(input="getreg('*')", mode="eval")
+- Unnamed register: nvim_send(input="getreg('\"')", mode="eval")
+- Last yank: nvim_send(input="getreg('0')", mode="eval")
+- Last insert (`.` register): nvim_send(input="getreg('.')", mode="eval")
+- Last command line: nvim_send(input="getreg(':')", mode="eval")
+- Last search pattern: nvim_send(input="getreg('/')", mode="eval")
+- Small delete: nvim_send(input="getreg('-')", mode="eval")
+- Expression register result: nvim_send(input="getreg('=')", mode="eval")
+
+## Folds
+
+- Close fold at cursor: nvim_send(input="foldclose", mode="command")
+- Open fold at cursor: nvim_send(input="foldopen", mode="command")
+- Toggle fold: nvim_send(input="za", mode="keys")
+- Close all folds (foldlevel): nvim_send(input="lua vim.o.foldlevel = 0", mode="command")
+- Open all folds: nvim_send(input="lua vim.o.foldlevel = 99", mode="command")
+- Create fold for range (lines 3–10): nvim_send(input="3,10fold", mode="command")
+- Delete fold at cursor: nvim_send(input="zd", mode="keys")
+- Delete all folds in window: nvim_send(input="normal! zE", mode="command")
+- Enable folding for buffer: nvim_send(input="setlocal foldmethod=manual", mode="command")
+
+## LSP & Diagnostics
+
+- Go to definition: nvim_send(input="lua vim.lsp.buf.definition()", mode="command")
+- Go to declaration: nvim_send(input="lua vim.lsp.buf.declaration()", mode="command")
+- Go to type definition: nvim_send(input="lua vim.lsp.buf.type_definition()", mode="command")
+- Go to implementation: nvim_send(input="lua vim.lsp.buf.implementation()", mode="command")
+- Find references: nvim_send(input="lua vim.lsp.buf.references()", mode="command")
+- Hover documentation: nvim_send(input="lua vim.lsp.buf.hover()", mode="command")
+- Rename symbol: nvim_send(input="lua vim.lsp.buf.rename()", mode="command")
+- Code action: nvim_send(input="lua vim.lsp.buf.code_action()", mode="command")
+- Format buffer: nvim_send(input="lua vim.lsp.buf.format({ async = true })", mode="command")
+- Signature help: nvim_send(input="lua vim.lsp.buf.signature_help()", mode="command")
+- Incoming calls: nvim_send(input="lua vim.lsp.buf.incoming_calls()", mode="command")
+- Outgoing calls: nvim_send(input="lua vim.lsp.buf.outgoing_calls()", mode="command")
+- Next diagnostic in buffer: nvim_send(input="lua vim.diagnostic.goto_next()", mode="command")
+- Previous diagnostic in buffer: nvim_send(input="lua vim.diagnostic.goto_prev()", mode="command")
+- Open diagnostics as quickfix: nvim_send(input="lua vim.diagnostic.setqflist()", mode="command")
+- Open diagnostics for buffer in quickfix: nvim_send(input="lua vim.diagnostic.setqflist({ bufnr = 0 })", mode="command")
+- List diagnostics (Lua table as message): nvim_send(input="lua vim.inspect(vim.diagnostic.get(0))", mode="command")
+- Get diagnostic count: nvim_send(input="lua vim.diagnostic.count(0)", mode="command")

nvim_mcp-0.1.0/src/nvim_mcp/recipes.py

@@ -0,0 +1,71 @@
+"""Load and serve Neovim operation recipes for the nvim_recipes MCP tool."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from importlib import resources
+
+
+QUICK_REFERENCE = """Quick reference (top operations):
+
+1. **Open file:** `nvim_send(input="e /path/to/file", mode="command")`
+2. **Save file:** `nvim_send(input="w", mode="command")`
+3. **Go to line:** `nvim_send(input="42", mode="command")`
+4. **Reload from disk:** `nvim_send(input="checktime", mode="command")`
+5. **Close buffer:** `nvim_send(input="bd", mode="command")`
+6. **Vertical split:** `nvim_send(input="vs /path/to/file", mode="command")`
+7. **Navigate windows:** `nvim_send(input="wincmd w", mode="command")`
+8. **LSP go-to-definition:** `nvim_send(input="lua vim.lsp.buf.definition()", mode="command")`
+9. **LSP references:** `nvim_send(input="lua vim.lsp.buf.references()", mode="command")`
+"""
+
+
+def _read_recipes_md() -> str:
+    return resources.files("nvim_mcp").joinpath("recipes.md").read_text(encoding="utf-8")
+
+
+@lru_cache(maxsize=1)
+def _parsed_recipes() -> dict[str, str]:
+    text = _read_recipes_md()
+    pattern = re.compile(r"^## (.+)$", re.MULTILINE)
+    parts = pattern.split(text)
+    result: dict[str, str] = {}
+    # parts[0] is preamble before first ##; then (title, body)+
+    i = 1
+    while i + 1 < len(parts):
+        name = parts[i].strip().lower()
+        body = parts[i + 1].strip()
+        result[name] = body
+        i += 2
+    return result
+
+
+def load_recipes() -> dict[str, str]:
+    """Parse recipes.md into {category_name: body_text} dict.
+
+    Split on ^## headers. Each header becomes a category key (lowercased, stripped).
+    Category body is everything until the next ^## or EOF.
+    """
+    return dict(_parsed_recipes())
+
+
+def get_recipes(category: str | None = None) -> str:
+    """
+    No category: return QUICK_REFERENCE + list of category names.
+    With category: return full recipes for that section.
+    Unknown category: return error message with valid categories listed.
+    """
+    recipes = load_recipes()
+    names = sorted(recipes)
+
+    if category is None:
+        lines = [QUICK_REFERENCE.rstrip(), "", "Categories:", *[f"- {n}" for n in names]]
+        return "\n".join(lines) + "\n"
+
+    key = category.strip().lower()
+    if key in recipes:
+        return f"## {category.strip()}\n\n{recipes[key]}\n"
+
+    valid = ", ".join(names)
+    return f"Unknown category {category!r}. Valid categories: {valid}\n"

nvim_mcp-0.1.0/src/nvim_mcp/server.py

@@ -0,0 +1,74 @@
+"""FastMCP entry point: tools for Neovim discovery, control, state, and recipes."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from nvim_mcp.neovim import NeovimManager
+from nvim_mcp.recipes import get_recipes
+
+mcp = FastMCP("nvim-mcp")
+manager = NeovimManager()
+
+
+@mcp.tool()
+async def nvim_connect(
+    socket_path: str | None = None,
+    terminal_pid: int | None = None,
+    index: int | None = None,
+) -> str:
+    """Connect to a Neovim instance.
+
+    No args = auto-connect if one instance, list all if multiple.
+    With index = pick from list (1-based).
+    With socket_path = direct connect.
+    With terminal_pid = match via process tree.
+    """
+    return await manager.connect(
+        socket_path=socket_path,
+        terminal_pid=terminal_pid,
+        index=index,
+    )
+
+
+@mcp.tool()
+async def nvim_send(
+    input: str,
+    mode: Literal["command", "eval", "keys"] = "command",
+) -> str:
+    """Send input to Neovim.
+
+    Modes:
+    - command: Run ex command without leading ':'. E.g. "e /path/to/file", "w", "42"
+    - eval: Evaluate expression, return result. E.g. "getcwd()", "line('$')"
+    - keys: Send keystrokes for navigation. E.g. "gg", "G", "za"
+
+    Auto-connects if only one Neovim instance exists.
+    """
+    return await manager.send(input=input, mode=mode)
+
+
+@mcp.tool()
+async def nvim_state() -> dict:
+    """Get structured Neovim state.
+
+    Returns file, line, col, mode, modified status, filetype, total lines,
+    cwd, relativenumber, window layout, modified buffers, and buffer count.
+    """
+    return await manager.get_state()
+
+
+@mcp.tool()
+async def nvim_recipes(category: str | None = None) -> str:
+    """Get Neovim operation recipes.
+
+    No args = quick reference + category list.
+    With category = full recipes for that section.
+    """
+    return get_recipes(category=category)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")