Skip to main content

Neovim Integration

Integrate Buildable with Neovim through MCP for enhanced development workflow.

Prerequisites​

  • Neovim 0.8+ installed
  • Node.js for MCP server
  • Active Buildable account

Installation​

1. Install MCP Plugin​

Using your preferred plugin manager:

vim-plug​

Plug 'buildable/neovim-mcp'

packer.nvim​

use 'buildable/neovim-mcp'

lazy.nvim​

{
  'buildable/neovim-mcp',
  config = function()
    require('buildable').setup({
      api_key = 'your-api-key',
      project_id = 'your-project-id'
    })
  end
}

2. Configuration​

Add to your init.lua:

require('buildable').setup({
  -- API Configuration
  api_key = os.getenv('BUILDABLE_API_KEY'),
  project_id = os.getenv('BUILDABLE_PROJECT_ID'),
  
  -- MCP Server Configuration
  mcp_server = {
    command = 'npx',
    args = { '@buildable/mcp-server' },
    env = {
      BUILDABLE_API_KEY = os.getenv('BUILDABLE_API_KEY'),
      BUILDABLE_PROJECT_ID = os.getenv('BUILDABLE_PROJECT_ID'),
      BUILDABLE_AI_ASSISTANT_ID = os.getenv('BUILDABLE_AI_ASSISTANT_ID')
    }
  },
  
  -- UI Configuration
  ui = {
    enable_sidebar = true,
    show_task_status = true,
    auto_update = true
  }
})

3. Environment Variables​

Set in your shell configuration:

export BUILDABLE_API_KEY="<your_full_api_key_here>"
export BUILDABLE_PROJECT_ID="<your_project_id>"
export BUILDABLE_AI_ASSISTANT_ID="<assistant_name>"

Features​

Task Management​

  • View tasks in a dedicated sidebar
  • Update task status with commands
  • Filter tasks by status, priority, or assignee
  • Quick task creation from selection

Code Integration​

  • AI-powered code suggestions based on active tasks
  • Contextual help for current development work
  • Automatic code generation for common patterns

Real-time Sync​

  • Live updates from Buildable dashboard
  • Automatic status synchronization
  • Push notifications for task changes

Commands​

Task Commands​

  • :BuildableTaskList - Show all tasks
  • :BuildableTaskShow <id> - Show specific task details
  • :BuildableTaskComplete <id> - Mark task as complete
  • :BuildableTaskCreate - Create new task from selection

AI Commands​

  • :BuildableAskAI <prompt> - Ask AI about current context
  • :BuildableCodeSuggest - Get code suggestions for current task
  • :BuildableRefactor - AI-powered refactoring suggestions

Sync Commands​

  • :BuildableSync - Manual sync with Buildable
  • :BuildableStatus - Show connection status
  • :BuildableReconnect - Reconnect to MCP server

Key Mappings​

Default key mappings (customize in your config):

-- Task management
vim.keymap.set('n', '<leader>bt', ':BuildableTaskList<CR>')
vim.keymap.set('n', '<leader>bc', ':BuildableTaskComplete<CR>')
vim.keymap.set('n', '<leader>bn', ':BuildableTaskCreate<CR>')

-- AI assistance
vim.keymap.set('n', '<leader>ba', ':BuildableAskAI<CR>')
vim.keymap.set('v', '<leader>bs', ':BuildableCodeSuggest<CR>')
vim.keymap.set('n', '<leader>br', ':BuildableRefactor<CR>')

-- Sync
vim.keymap.set('n', '<leader>by', ':BuildableSync<CR>')

UI Components​

Task Sidebar​

Shows your current tasks with:

  • Task title and description
  • Current status and priority
  • Assigned user
  • Due dates and estimates

Status Line Integration​

Add to your status line:

require('lualine').setup({
  sections = {
    lualine_x = {
      function()
        return require('buildable').get_current_task()
      end
    }
  }
})

Floating Windows​

  • Task details in floating windows
  • Code suggestions overlay
  • Progress indicators

Advanced Configuration​

Custom Task Filters​

require('buildable').setup({
  task_filters = {
    my_tasks = function(task)
      return task.assigned_to == 'me' and task.status ~= 'completed'
    end,
    urgent = function(task)
      return task.priority == 'high' or task.due_date < os.time() + 86400
    end
  }
})

AI Model Configuration​

require('buildable').setup({
  ai = {
    model = 'gpt-4',
    temperature = 0.3,
    max_tokens = 1000,
    context_window = 4000
  }
})

Integration with Other Plugins​

Telescope Integration​

require('telescope').load_extension('buildable')

vim.keymap.set('n', '<leader>ft', ':Telescope buildable tasks<CR>')
vim.keymap.set('n', '<leader>fp', ':Telescope buildable projects<CR>')

nvim-tree Integration​

require('nvim-tree').setup({
  renderer = {
    icons = {
      show = {
        git = true,
        buildable = true -- Show task indicators
      }
    }
  }
})

Troubleshooting​

Plugin Not Loading​

Check that your plugin manager properly installed the plugin:

:checkhealth buildable

MCP Connection Issues​

Verify the MCP server is accessible:

:lua print(require('buildable').check_mcp_connection())

API Authentication​

Test your API credentials:

:lua print(require('buildable').test_auth())

Performance Issues​

  • Reduce sync frequency in configuration
  • Disable auto-update for large projects
  • Use filtered task views

Best Practices​

  1. Use environment variables for sensitive configuration
  2. Set up key mappings for frequently used commands
  3. Configure filters to focus on relevant tasks
  4. Enable auto-sync for real-time updates
  5. Customize UI to match your workflow

Community​

  • Share configurations in our GitHub discussions
  • Contribute to the plugin repository
  • Join our Discord for Neovim-specific support
  • Report bugs and feature requests

Contributing​

The Neovim plugin is open source:

  • Fork the repository
  • Create feature branches
  • Submit pull requests
  • Add tests for new features

Getting Help​

  • Check :help buildable for built-in documentation
  • Review plugin configuration examples
  • Join our Discord #neovim channel
  • Contact support for integration issues