mcp-neovim-server

Instructions

Implementation Reference

• src/index.ts:136-158 (registration)

  Registers the 'vim_status' MCP tool with no input parameters. The handler fetches Neovim status via neovimManager and returns it as JSON.

  server.tool(
    "vim_status",
    "Get comprehensive Neovim status including cursor position, mode, marks, and registers",
    {},
    async () => {
      try {
        const status = await neovimManager.getNeovimStatus();
        return {
          content: [{
            type: "text",
            text: JSON.stringify(status, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: error instanceof Error ? error.message : 'Error getting Neovim status'
          }]
        };
      }
    }
  );

• src/neovim.ts:328-438 (handler)

  Main handler logic in NeovimManager.getNeovimStatus(): Connects to Neovim, retrieves cursor position, mode, visual info, filename, marks, registers, cwd, LSP/plugin info, and constructs status object.

  public async getNeovimStatus(): Promise<NeovimStatus | string> {
    try {
      const nvim = await this.connect();
      const window = await nvim.window;
      const cursor = await window.cursor;
      const mode = await nvim.mode;
      const buffer = await nvim.buffer;
      
      // Get window layout
      const layout = await nvim.eval('winlayout()');
      const tabpage = await nvim.tabpage;
      const currentTab = await tabpage.number;
  
      // Get marks (a-z) - only include set marks
      const marks: { [key: string]: [number, number] } = {};
      for (const mark of 'abcdefghijklmnopqrstuvwxyz') {
        try {
          const pos = await nvim.eval(`getpos("'${mark}")`) as [number, number, number, number];
          // Only include marks that are actually set (not at position 0,0)
          if (pos[1] > 0 && pos[2] > 0) {
            marks[mark] = [pos[1], pos[2]];
          }
        } catch (e) {
          // Mark not set
        }
      }
  
      // Get registers (a-z, ", 0-9) - only include non-empty registers
      const registers: { [key: string]: string } = {};
      const registerNames = [...'abcdefghijklmnopqrstuvwxyz', '"', ...Array(10).keys()];
      for (const reg of registerNames) {
        try {
          const content = String(await nvim.eval(`getreg('${reg}')`));
          // Only include registers that have content
          if (content && content.trim().length > 0) {
            registers[String(reg)] = content;
          }
        } catch (e) {
          // Register empty or error
        }
      }
  
      // Get current working directory
      const cwd = await nvim.call('getcwd');
  
      // Get basic plugin information (LSP clients, loaded plugins)
      let lspInfo = '';
      let pluginInfo = '';
      
      try {
        // Get LSP clients if available (use new API for Neovim >=0.10)
        const lspClients = await nvim.eval('luaeval("vim.lsp.get_clients()")');
        if (Array.isArray(lspClients) && lspClients.length > 0) {
          const clientNames = lspClients.map((client: any) => client.name || 'unknown').join(', ');
          lspInfo = `Active LSP clients: ${clientNames}`;
        } else {
          lspInfo = 'No active LSP clients';
        }
      } catch (e) {
        lspInfo = 'LSP information unavailable';
      }
  
      try {
        // Get loaded plugins (simplified check)
        const hasLsp = await nvim.eval('exists(":LspInfo")');
        const hasTelescope = await nvim.eval('exists(":Telescope")');
        const hasTreesitter = await nvim.eval('exists("g:loaded_nvim_treesitter")');
        const hasCompletion = await nvim.eval('exists("g:loaded_completion")');
        
        const plugins = [];
        if (hasLsp) plugins.push('LSP');
        if (hasTelescope) plugins.push('Telescope');
        if (hasTreesitter) plugins.push('TreeSitter');
        if (hasCompletion) plugins.push('Completion');
        
        pluginInfo = plugins.length > 0 ? `Detected plugins: ${plugins.join(', ')}` : 'No common plugins detected';
      } catch (e) {
        pluginInfo = 'Plugin information unavailable';
      }
  
      // Get visual selection information using the new method
      const visualInfo = await this.getVisualSelectionInfo(nvim, mode.mode);
  
      const neovimStatus: NeovimStatus = {
        cursorPosition: cursor,
        mode: mode.mode,
        visualSelection: visualInfo.selectedText || '',
        fileName: await buffer.name,
        windowLayout: JSON.stringify(layout),
        currentTab,
        marks,
        registers,
        cwd,
        lspInfo,
        pluginInfo,
        visualInfo: {
          hasActiveSelection: visualInfo.hasSelection,
          visualModeType: visualInfo.visualModeType,
          startPos: visualInfo.startPos,
          endPos: visualInfo.endPos,
          lastVisualStart: visualInfo.lastVisualStart,
          lastVisualEnd: visualInfo.lastVisualEnd
        }
      };
  
      return neovimStatus;
    } catch (error) {
      console.error('Error getting Neovim status:', error);
      return 'Error getting Neovim status';
    }
  }

• src/neovim.ts:25-45 (schema)

  TypeScript interface defining the structure of NeovimStatus returned by the tool.

  interface NeovimStatus {
    cursorPosition: [number, number];
    mode: string;
    visualSelection: string;
    fileName: string;
    windowLayout: string;
    currentTab: number;
    marks: { [key: string]: [number, number] };
    registers: { [key: string]: string };
    cwd: string;
    lspInfo?: string;
    pluginInfo?: string;
    visualInfo?: {
      hasActiveSelection: boolean;
      visualModeType?: string;
      startPos?: [number, number];
      endPos?: [number, number];
      lastVisualStart?: [number, number];
      lastVisualEnd?: [number, number];
    };
  }

• src/neovim.ts:211-326 (helper)

  Helper method to retrieve detailed visual selection information, including active selections and last visual marks, used in getNeovimStatus.

  private async getVisualSelectionInfo(nvim: Neovim, mode: string): Promise<{
    hasSelection: boolean;
    selectedText?: string;
    startPos?: [number, number];
    endPos?: [number, number];
    visualModeType?: string;
    lastVisualStart?: [number, number];
    lastVisualEnd?: [number, number];
  }> {
    try {
      const isInVisualMode = mode.includes('v') || mode.includes('V') || mode.includes('\x16');
  
      if (isInVisualMode) {
        // Currently in visual mode - get active selection
        const [startPos, endPos, initialVisualModeType] = await Promise.all([
          nvim.call('getpos', ['v']) as Promise<[number, number, number, number]>,
          nvim.call('getpos', ['.']) as Promise<[number, number, number, number]>,
          nvim.call('visualmode', []) as Promise<string>
        ]);
  
        // Convert positions to [line, col] format
        const start: [number, number] = [startPos[1], startPos[2]];
        const end: [number, number] = [endPos[1], endPos[2]];
  
        // Get the selected text using a more reliable approach
        let selectedText = '';
        let visualModeType = initialVisualModeType;
        try {
          const result = await nvim.lua(`
            -- Get visual mode type first
            local mode = vim.fn.visualmode()
            if not mode or mode == '' then
              return { text = '', mode = '' }
            end
  
            local start_pos = vim.fn.getpos('v')
            local end_pos = vim.fn.getpos('.')
            local start_line, start_col = start_pos[2], start_pos[3]
            local end_line, end_col = end_pos[2], end_pos[3]
  
            -- Ensure proper ordering (start should be before end)
            if start_line > end_line or (start_line == end_line and start_col > end_col) then
              start_line, end_line = end_line, start_line
              start_col, end_col = end_col, start_col
            end
  
            local text = ''
  
            if mode == 'v' then
              -- Character-wise visual mode
              if start_line == end_line then
                local line = vim.api.nvim_buf_get_lines(0, start_line - 1, start_line, false)[1] or ''
                text = line:sub(start_col, end_col)
              else
                local lines = vim.api.nvim_buf_get_lines(0, start_line - 1, end_line, false)
                if #lines > 0 then
                  -- Handle first line
                  lines[1] = lines[1]:sub(start_col)
                  -- Handle last line
                  if #lines > 1 then
                    lines[#lines] = lines[#lines]:sub(1, end_col)
                  end
                  text = table.concat(lines, '\\n')
                end
              end
            elseif mode == 'V' then
              -- Line-wise visual mode
              local lines = vim.api.nvim_buf_get_lines(0, start_line - 1, end_line, false)
              text = table.concat(lines, '\\n')
            elseif mode == '\\022' then
              -- Block-wise visual mode (Ctrl-V)
              local lines = vim.api.nvim_buf_get_lines(0, start_line - 1, end_line, false)
              local result = {}
              for _, line in ipairs(lines) do
                table.insert(result, line:sub(start_col, end_col))
              end
              text = table.concat(result, '\\n')
            end
  
            return { text = text, mode = mode }
          `) as { text: string; mode: string };
  
          selectedText = result.text || '';
          visualModeType = result.mode || visualModeType;
        } catch (e) {
          selectedText = '[Selection text unavailable]';
        }
  
        return {
          hasSelection: true,
          selectedText,
          startPos: start,
          endPos: end,
          visualModeType
        };
      } else {
        // Not in visual mode - get last visual selection marks
        try {
          const [lastStart, lastEnd] = await Promise.all([
            nvim.call('getpos', ["'<"]) as Promise<[number, number, number, number]>,
            nvim.call('getpos', ["'>"]) as Promise<[number, number, number, number]>
          ]);
  
          return {
            hasSelection: false,
            lastVisualStart: [lastStart[1], lastStart[2]],
            lastVisualEnd: [lastEnd[1], lastEnd[2]]
          };
        } catch (e) {
          return { hasSelection: false };
        }
      }
    } catch (error) {
      return { hasSelection: false, selectedText: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` };
    }
  }