# 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_view` with action `goto_line`, or `nvim_execute_lua`).
   - 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 7 cohesive domain tools:
1. **`nvim_buffer`** (actions: `get_active`, `read`, `open`, `create_scratch`, `save`, `reload`, `close`, `list`, `search`)
2. **`nvim_window`** (actions: `list`, `get_active`, `focus`, `split`, `close`)
3. **`nvim_view`** (actions: `goto_line`, `get_cursor`, `get_viewport`, `get_selection`)
4. **`nvim_diagnostics`** (actions: `get`, `set`, `set_quickfix`)
5. **`nvim_visual`** (actions: `preview`, `extmark`, `highlight`, `clear_highlight`)
6. **`nvim_execute_lua`** (direct Lua execution escape hatch)
7. **`nvim_system`** (actions: `get_info`, `get_messages`, `send_to_terminal`)