mcp-neovim-server

Instructions

Implementation Reference

• src/index.ts:99-134 (registration)

  MCP server.tool registration for 'vim_command', including description, input schema, and thin handler wrapper

  server.tool(
    "vim_command",
    "Execute Vim commands with optional shell command support",
    { command: z.string().describe("Vim command to execute (use ! prefix for shell commands if enabled)") },
    async ({ command }) => {
      try {
        // Check if this is a shell command
        if (command.startsWith('!')) {
          const allowShellCommands = process.env.ALLOW_SHELL_COMMANDS === 'true';
          if (!allowShellCommands) {
            return {
              content: [{
                type: "text",
                text: "Shell command execution is disabled. Set ALLOW_SHELL_COMMANDS=true environment variable to enable shell commands."
              }]
            };
          }
        }
  
        const result = await neovimManager.sendCommand(command);
        return {
          content: [{
            type: "text",
            text: result
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: error instanceof Error ? error.message : 'Error executing command'
          }]
        };
      }
    }
  );

• src/index.ts:102-102 (schema)

  Zod input schema defining the 'command' parameter for vim_command tool

  { command: z.string().describe("Vim command to execute (use ! prefix for shell commands if enabled)") },

• src/index.ts:103-133 (handler)

  Tool handler function: checks for shell command permission and delegates execution to NeovimManager.sendCommand, with error handling and MCP response formatting

  async ({ command }) => {
    try {
      // Check if this is a shell command
      if (command.startsWith('!')) {
        const allowShellCommands = process.env.ALLOW_SHELL_COMMANDS === 'true';
        if (!allowShellCommands) {
          return {
            content: [{
              type: "text",
              text: "Shell command execution is disabled. Set ALLOW_SHELL_COMMANDS=true environment variable to enable shell commands."
            }]
          };
        }
      }
  
      const result = await neovimManager.sendCommand(command);
      return {
        content: [{
          type: "text",
          text: result
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: error instanceof Error ? error.message : 'Error executing command'
        }]
      };
    }
  }

• src/neovim.ts:151-209 (helper)

  Core helper method in NeovimManager that implements the actual Vim command execution via Neovim API, handles shell commands (! prefix), captures output and errors using execute() and errmsg

  public async sendCommand(command: string): Promise<string> {
    if (!command || command.trim().length === 0) {
      throw new NeovimValidationError('Command cannot be empty');
    }
  
    try {
      const nvim = await this.connect();
  
      // Remove leading colon if present
      const normalizedCommand = command.startsWith(':') ? command.substring(1) : command;
  
      // Handle shell commands (starting with !)
      if (normalizedCommand.startsWith('!')) {
        if (process.env.ALLOW_SHELL_COMMANDS !== 'true') {
          return 'Shell command execution is disabled. Set ALLOW_SHELL_COMMANDS=true environment variable to enable shell commands.';
        }
  
        const shellCommand = normalizedCommand.substring(1).trim();
        if (!shellCommand) {
          throw new NeovimValidationError('Shell command cannot be empty');
        }
        
        try {
          // Execute the command and capture output directly
          const output = await nvim.eval(`system('${shellCommand.replace(/'/g, "''")}')`);
          if (output) {
            return String(output).trim();
          }
          return 'No output from command';
        } catch (error) {
          console.error('Shell command error:', error);
          const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
          throw new NeovimCommandError(`!${shellCommand}`, errorMessage);
        }
      }
  
      // For regular Vim commands
      await nvim.setVvar('errmsg', '');
      
      // Execute the command and capture its output using the execute() function
      const output = await nvim.call('execute', [normalizedCommand]);
      
      // Check for errors
      const vimerr = await nvim.getVvar('errmsg');
      if (vimerr) {
        console.error('Vim error:', vimerr);
        throw new NeovimCommandError(normalizedCommand, String(vimerr));
      }
  
      // Return the actual command output if any
      return output ? String(output).trim() : 'Command executed (no output)';
    } catch (error) {
      if (error instanceof NeovimCommandError || error instanceof NeovimValidationError) {
        throw error;
      }
      console.error('Error sending command:', error);
      throw new NeovimCommandError(command, error instanceof Error ? error.message : 'Unknown error');
    }
  }