Can See vs Nvim MCP

connect

Connect to a running Neovim instance over its Unix socket or TCP address. Call this before any other tool if the agent is not yet connected. Connection is persistent for the session; you only need to call it once unless you want to switch instances. Called with no arguments: auto-connects when exactly one instance is running; returns a list of instances when multiple are found. Optional selection (provide at most one): - index: pick from the listed instances (1-based). - socket_path: connect directly to a known Unix socket or host:port. - terminal_pid: find the Neovim instance whose process tree contains this PID (useful when Neovim runs inside a specific terminal). Returns {connected, cwd, file} on success, or {error} with details on failure (e.g. no instances found, connection timeout, bad index).

send_command

Run one or more Vim ex commands in Neovim. This is a mutation tool — commands can modify buffers, files on disk, windows, and editor state. command: a single command string or a list of strings, without the leading ':'. E.g. "w", "e src/main.py", "42", "wincmd v", "lua vim.print(...)", or ["wincmd p", "e file.py", "wincmd p"]. Use this for editor operations that don't have a dedicated tool (e.g. saving, opening files, splitting windows, setting options). Use `send_keys` instead when you need normal-mode motions or operator sequences. Use `find_and_replace_buf` or `write_full_buf` for buffer text edits — they are safer and provide undo. Returns {output} with the command's captured output, or {error} if the command failed. When given a list, returns a list of results in the same order; execution stops on the first error.

send_keys

Send raw keystrokes to Neovim as if typed by the user. This is a mutation tool — keystrokes can modify buffers, change mode, and trigger editor actions. keys: a string of Vim keystrokes. Esc is prepended automatically, so input always begins in normal mode. Multi-mode sequences must be sent in a single call (e.g. "17GVG", not "17GV" then "G"). Use Vim notation for special keys (e.g. "<CR>", "<C-w>v", "<Tab>"). Use this for normal-mode motions, visual selections, or operator sequences. Use `send_command` for ex commands, and `find_and_replace_buf` or `write_full_buf` for text edits — they are safer and provide structured results. Returns {sent} confirming the keys that were dispatched. Keystrokes are fire-and-forget; errors from the resulting Vim actions are not captured in the return value.

send_to_terminal

Type text into a terminal buffer's running program (usually a shell) by writing to its job channel. This is a mutation tool — the text reaches the program's stdin as if typed, but is not executed unless submit is true. text: the text to send, raw. In most shells an embedded newline acts like pressing Enter, so multi-line text may execute line by line. When submit is false, trailing newlines are stripped so nothing runs by accident. terminal: which terminal to target — a buffer number or buffer name, as listed under `terminals` in `get_state` / `get_state_brief`. Names match exactly first, then by unique substring. Omit it when exactly one terminal exists; with several open, omitting it returns an error listing them. submit: false (default) leaves the text at the prompt for the user to review and press Enter. true appends a carriage return so the program executes it immediately. NEVER pass submit=true unless the user has explicitly asked for the command to be run — "put", "paste", "type", or "prepare" a command always means submit=false. Suggesting a command yourself is not permission to run it. When in doubt, use submit=false and let the user press Enter. Use this whenever text needs to go into a terminal. It works regardless of focus, mode, or visibility and never moves the user's cursor — unlike `send_keys`, which requires focusing the terminal and juggling modes. Terminal buffers cannot be edited with the buffer tools. Returns {sent, terminal, buf, submitted} on success — sent is the byte count actually written. On failure returns {error}, including a `terminals` list when the target was missing or ambiguous.

get_all_diagnostics

Get LSP diagnostics from all open buffers in Neovim. Read-only. Use this for a project-wide overview of errors and warnings. Use `get_buf_diagnostics` instead when you only need diagnostics for a specific file — it is more focused and returns less data. Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when there are no diagnostics. Results depend on which LSP servers are attached and which buffers are loaded in Neovim.

get_buf_diagnostics

Get LSP diagnostics for a single Neovim buffer. Read-only. file: path relative to Neovim's cwd (as shown in `get_state` buffers). The buffer must already be open in Neovim; returns an error otherwise. Use this when you need diagnostics for one specific file. Use `get_all_diagnostics` instead for a project-wide overview. Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when the buffer has no diagnostics.

find_and_replace_buf

Find and replace text in a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves. file: path relative to Neovim's cwd (as shown in `get_state` buffers). old_string: the exact text to find. Must match exactly once in the buffer; returns an error if not found or if it matches multiple locations. Include surrounding lines to disambiguate. new_string: the replacement text. Creates the buffer if it doesn't already exist. Use this for targeted edits. Use `write_full_buf` instead when replacing the entire buffer content. Use `read_full_buf` or `read_buf_range` first if you need to see the current content before editing. Returns {start_line, lines_removed, lines_added, total_lines} on success, or {error} with a message on failure.

write_full_buf

Replace the entire content of a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves. file: path relative to Neovim's cwd (as shown in `get_state` buffers). content: the full new text for the buffer. Creates the buffer if it doesn't already exist. Use this when you need to rewrite the whole file. Use `find_and_replace_buf` instead for targeted edits that preserve surrounding content. Returns {total_lines} with the new line count.

read_full_buf

Read the full content of a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes. file: path relative to Neovim's cwd (as shown in `get_state` buffers). The buffer must already be open in Neovim; returns an error otherwise. Use this when you need to see the entire file. Use `read_buf_range` instead when you only need a specific section — it returns less data. Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "1: first line").

read_buf_range

Read a specific line range from a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes. file: path relative to Neovim's cwd (as shown in `get_state` buffers). The buffer must already be open in Neovim; returns an error otherwise. start_line: first line to read (1-indexed, inclusive). end_line: last line to read (1-indexed, inclusive). Out-of-range values are clamped to the buffer bounds. If start_line > end_line they are swapped automatically. Use this when you only need a section of a file. Use `read_full_buf` instead when you need the entire buffer. Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "10: some code").

get_state

Full snapshot of the current Neovim session. Read-only — does not modify any editor state. Use `get_state_brief` for quick orientation at the start of a turn. Use this when you need the complete picture: all window details, folds, marks, diagnostics summaries, highlights, virtual text, and indent settings. Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative paths of all listed buffers), modified_buffers, current_tab, tab_count, and terminals — a list of open terminal buffers as {buf, name, visible}, present only when at least one exists (targets for `send_to_terminal`). windows — list of visible windows (current tab only). The active window is always first, the alternate window (previous) is second. Each window entry contains: file (path relative to cwd), filetype, total_lines, modified, buftype ("file" for normal buffers, "terminal", etc.), line, col, indent: {expandtab, shiftwidth, tabstop}. Optional per-window fields (present when applicable): - role: "active" or "alternate". - context: numbered lines surrounding the cursor. - selection: {start_line, start_col, end_line, end_col} in visual modes. - folds: list of [start, end] closed fold ranges. - diagnostics_summary: {error, warning, info, hint} counts. - marks: list of {mark, line, col} for lowercase (a-z) buffer marks. - mcp_highlights: list of {start_line, end_line, color} for active highlights. - mcp_virtual_text: list of {line, position, lines, color} for active virtual text.

get_state_brief

Lightweight snapshot of the Neovim session for quick orientation. Read-only — does not modify any editor state. Use this at the start of each turn to see what the user is working on. Use `get_state` instead when you need the full picture: all windows, folds, marks, diagnostics summaries, highlights, virtual text, and indent settings. Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative paths of all listed buffers), modified_buffers, and active_window: {file, filetype, total_lines, modified, buftype, line, col, context}. context is a short list of numbered lines around the cursor. If an alternate window exists, also returns alternate_window with the same fields. When terminal buffers exist, returns terminals — a list of {buf, name, visible} (targets for `send_to_terminal`).