mcp-memory/agent-rules/nvim_architecture.md

Neovim MCP Architecture (Dual-OS)

We use a modular, multi-binary approach for MCP Neovim integration to cleanly separate Windows and Linux concerns, avoiding complex cross-OS wsl.exe bridging within the main mcp-memory-server.

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-win-nvim: A dedicated Windows-native MCP server. Its sole responsibility is finding active Neovim instances running natively on Windows and sending RPC commands to them.
4. mcp-memory-linux-nvim: A dedicated Linux-native MCP server running inside WSL. Its sole responsibility is finding active Neovim instances inside WSL (including Tmux sessions) and sending RPC commands to them.

This isolates editor-control logic to the native OS where the editor is actually running.

How the Respective MCP Servers Get 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 "linux-nvim": { "command": "/home/riz/.local/bin/mcp-memory-linux-nvim" }, it will spawn that binary as a background subprocess using standard stdio.

3. Communication:

   • The LLM requests to use a tool (e.g., nvim_goto_line).
   • The agy CLI sends a JSON-RPC request to the mcp-memory-linux-nvim subprocess via its stdin.
   • The Rust MCP Server receives the request, connects to the Neovim active socket (~/.gemini/active_nvim.txt), 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 servers provide 5 core tools:

1. nvim_goto_line
2. nvim_set_diagnostics
3. nvim_get_active_buffer
4. nvim_get_cursor
5. nvim_get_visual_selection