mcp-memory/agent-rules/nvim_architecture.md

Neovim MCP Architecture (Cross-Platform)

We use a modular, cross-platform approach for MCP Neovim integration to cleanly connect with Neovim instances across Windows and WSL.

The Architecture

1. mcp-memory-server: The core Windows daemon (handles state, lock-files, and global graph).
2. mcp-memory-stub: The WSL proxy that forwards standard json-rpc to the Windows daemon.
3. mcp-memory-nvim: The unified cross-platform Neovim MCP server binary (mcp-memory-nvim.exe on Windows, mcp-memory-nvim on Linux). Its sole responsibility is finding active Neovim instances (via named pipes on Windows or domain sockets on Unix/WSL) and sending RPC commands to them.

This isolates editor-control logic natively to whichever OS environment execution is running in.

How the MCP Server Gets Called

The Antigravity CLI (agy) acts as the MCP Client and automatically manages the lifecycle of these servers.

1. Registration: The servers are registered in the global configuration file:

   • WSL: /home/riz/.gemini/config/mcp_config.json
   • Windows: C:\Users\reazul.ashraf\.gemini\config\mcp_config.json

2. Execution: When agy starts up, it reads mcp_config.json. If it finds "win-nvim": { "command": "C:\\Users\\reazul.ashraf\\.local\\bin\\mcp-memory-nvim.exe" }, it will spawn that binary as a background subprocess using standard stdio.

3. Communication:

   • The LLM requests to use a consolidated tool (e.g., nvim_workspace with action focus, or nvim_exec).
   • The agy CLI sends a JSON-RPC request to the mcp-memory-nvim subprocess via its stdin.
   • The Rust MCP Server receives the request, connects to the Neovim active socket/pipe (~/.gemini/active_nvim.txt or \\.\pipe\nvim.*), sends the Msgpack-RPC command, and writes the JSON-RPC response back to stdout.
   • The agy CLI reads the response from stdout and returns it to the LLM context.

Capabilities & Requirements

To use this architecture, Neovim must run the gemini-integration.lua script to broadcast its active socket to ~/.gemini/active_nvim.txt.

The MCP server provides 5 cohesive mega-tools:

1. nvim_buffer (actions: read, replace, save, undo, redo, create_scratch)
2. nvim_workspace (actions: list_buffers, list_windows, focus, split, cwd)
3. nvim_intelligence (actions: hover, definition, references, outline, query, diagnostics, rename, code_action)
4. nvim_ui (actions: highlight, ghost_text, clear)
5. nvim_exec (actions: lua, vimscript, terminal)