feat: implement MCP tool system with diff integration and comprehensive test coverage

Change-Id: If27e0783e938f4c791c7f9190f897ef25e6ee5b0
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

.github/workflows/claude.yml

@@ -25,12 +25,13 @@ jobs:
       id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 1
+          persist-credentials: false
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@8e84799f37d42f24e0ebae41205346879bdcab5a # v0.0.7/beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

ARCHITECTURE.md

@@ -70,14 +70,27 @@ The lock file system enables Claude CLI to discover the Neovim integration:
 }
 ```
 
-### 3. MCP Tool Implementation
+### 3. MCP Tool System
 
-The plugin implements tools that Claude can invoke:
+The plugin implements a dynamic tool system following the Model Context Protocol 2025-03-26 specification. Tools are registered with both handlers and JSON schemas:
 
-- File operations (open, save, check status)
-- Editor information (diagnostics, open editors)
-- Selection management
-- Diff viewing
+**MCP-Exposed Tools:**
+
+- `openFile` - Opens files with optional line/text selection
+- `getCurrentSelection` - Gets current text selection
+- `getOpenEditors` - Lists currently open files
+- `openDiff` - Opens native Neovim diff views for file comparisons
+
+**Internal Tools** (not exposed via MCP):
+
+- `getDiagnostics`, `getWorkspaceFolders`, `saveDocument`, etc.
+
+**Tool Architecture:**
+
+- Centralized registration with `M.register(name, schema, handler)`
+- Dynamic tool list generation via `M.get_tool_list()`
+- Schema validation and JSON-RPC parameter handling
+- Automatic MCP exposure based on schema presence
 
 Each tool follows a request/response pattern:
 
@@ -95,7 +108,62 @@ Claude CLI                            Neovim Plugin
     │                                      │
 ```
 
-### 4. Selection Tracking
+### 4. Diff Integration System
+
+The plugin provides a configurable diff system that Claude can use to show file changes:
+
+**Diff Providers:**
+
+- `native` - Uses Neovim's built-in diff mode with `diffthis`
+- `auto` - Automatically selects the best available provider
+- `diffview` - (Future) Integration with diffview.nvim plugin
+
+**Diff Configuration:**
+
+```lua
+diff_opts = {
+  auto_close_on_accept = true,    -- Auto-close when accepting changes
+  show_diff_stats = true,         -- Show diff statistics
+  vertical_split = true,          -- Use vertical split for diff view
+  open_in_current_tab = true,     -- Open in current tab (reduces clutter)
+}
+```
+
+**Native Diff Features:**
+
+- Current-tab mode (default) - opens diff in current tab to reduce clutter
+- Helpful keymaps in current-tab mode:
+  - `<leader>dq` - Exit diff mode and cleanup
+  - `<leader>da` - Accept all changes
+  - `]c` / `[c` - Navigate between changes (standard Neovim)
+- Automatic temporary file cleanup
+- Configurable split orientation (vertical/horizontal)
+
+**Diff Flow:**
+
+```
+Claude Request ──► openDiff MCP tool ──► diff.lua provider
+                                              │
+                                              ▼
+                                      ┌─────────────────┐
+                                      │ Create temp file│
+                                      │ with new content│
+                                      └─────────────────┘
+                                              │
+                                              ▼
+                                      ┌─────────────────┐
+                                      │ Open original   │
+                                      │ file in editor  │
+                                      └─────────────────┘
+                                              │
+                                              ▼
+                                      ┌─────────────────┐
+                                      │ Create split &  │
+                                      │ enable diffthis │
+                                      └─────────────────┘
+```
+
+### 5. Selection Tracking
 
 The plugin monitors text selections in Neovim:
 
@@ -105,7 +173,7 @@ The plugin monitors text selections in Neovim:
 - Sends updates to Claude via WebSocket
 - Supports sending `at_mentioned` notifications for visual selections using the `:ClaudeCodeSend` command, providing focused context to Claude.
 
-### 5. Terminal Integration
+### 6. Terminal Integration
 
 The plugin provides a dedicated terminal interface for Claude Code CLI:
 
@@ -123,7 +191,7 @@ The plugin provides a dedicated terminal interface for Claude Code CLI:
 └─────────────┘    └─────────────────┘    └─────────────┘
 ```
 
-### 6. Environment Integration
+### 7. Environment Integration
 
 The plugin manages the environment for Claude CLI:
 
@@ -186,7 +254,8 @@ lua/claudecode/
 │   └── mock.lua          # Mock server for testing
 ├── lockfile.lua          # Lock file management
 ├── tools/
-│   └── init.lua          # Tool registration and dispatch
+│   └── init.lua          # MCP tool registration, schema management, and dispatch
+├── diff.lua              # Diff provider system (native Neovim diff support)
 ├── selection.lua         # Selection tracking and notifications
 ├── terminal.lua          # Terminal management (Snacks.nvim or native)
 └── meta/

CLAUDE.md

@@ -33,16 +33,37 @@ The plugin follows a modular architecture with these main components:
    - Creates and manages lock files at `~/.claude/ide/[port].lock`
    - Enables Claude CLI to discover the Neovim integration
 
-3. **Selection Tracking** (`lua/claudecode/selection.lua`)
+3. **MCP Tool System** (`lua/claudecode/tools/init.lua`)
+
+   - Dynamic tool registration with schema validation
+   - Implements openFile, openDiff, getCurrentSelection, getOpenEditors
+   - Follows Model Context Protocol 2025-03-26 specification
+   - Centralized tool definitions and automatic MCP exposure
+
+4. **Diff Integration** (`lua/claudecode/diff.lua`)
+
+   - Native Neovim diff support with configurable options
+   - Current-tab mode (default) to reduce tab clutter
+   - Helpful keymaps: `<leader>dq` (exit), `<leader>da` (accept all)
+   - Automatic temporary file cleanup
+
+5. **Selection Tracking** (`lua/claudecode/selection.lua`)
 
    - Monitors text selections and cursor position in Neovim
    - Sends updates to Claude via WebSocket
 
-4. **Configuration** (`lua/claudecode/config.lua`)
+6. **Terminal Integration** (`lua/claudecode/terminal.lua`)
+
+   - Supports both Snacks.nvim and native Neovim terminals
+   - Vertical split terminal with configurable positioning
+   - Commands: `:ClaudeCode`, `:ClaudeCodeOpen`, `:ClaudeCodeClose`
+
+7. **Configuration** (`lua/claudecode/config.lua`)
 
    - Handles user configuration validation and merging with defaults
+   - Includes diff provider and terminal configuration
 
-5. **Main Plugin Entry** (`lua/claudecode/init.lua`)
+8. **Main Plugin Entry** (`lua/claudecode/init.lua`)
    - Exposes setup and control functions
    - Manages plugin lifecycle
 
@@ -54,8 +75,11 @@ The plugin is in beta stage with:
 - Complete WebSocket server with RFC 6455 compliance
 - Enhanced selection tracking with multi-mode support
 - Lock file management implemented
-- MCP tool framework implemented
-- Comprehensive test suite (55 tests passing)
+- Complete MCP tool framework with dynamic registration
+- Core MCP tools: openFile, openDiff, getCurrentSelection, getOpenEditors
+- Native Neovim diff integration with configurable options
+- Terminal integration (Snacks.nvim and native support)
+- Comprehensive test suite (55+ tests passing)
 
 ## Testing Approach
 
@@ -73,7 +97,7 @@ The project uses the Busted testing framework:
 
 Current priorities for development are:
 
-1. Enhancing MCP tools with additional file operations and editor features
+1. Implementing diffview.nvim integration for the diff provider system
 2. Adding Neovim-specific tools (LSP integration, diagnostics, Telescope)
 3. Performance optimization for large codebases
 4. Integration testing with real Claude Code CLI
@@ -109,10 +133,11 @@ Current priorities for development are:
 
 The plugin provides these user-facing commands:
 
-- `:ClaudeCodeStart` - Start the Claude Code integration
-- `:ClaudeCodeStop` - Stop the integration
-- `:ClaudeCodeStatus` - Show connection status
-- `:ClaudeCodeSend` - Send current selection to Claude
+- `:ClaudeCode` - Toggle the Claude Code interactive terminal
+- `:ClaudeCodeOpen` - Open/focus the Claude Code terminal
+- `:ClaudeCodeClose` - Close the Claude Code terminal
+- `:ClaudeCodeSend` - Send current selection to Claude as at-mentioned context
+- `:ClaudeCodeStatus` - Show connection status (via Lua API)
 
 ## Debugging
 
@@ -135,12 +160,29 @@ require("claudecode").setup({
   auto_start = true,
 
   -- Custom terminal command to use when launching Claude
-  terminal_cmd = nil, -- e.g., "toggleterm"
+  terminal_cmd = nil, -- e.g., "claude --project-foo"
 
   -- Log level (trace, debug, info, warn, error)
   log_level = "info",
 
   -- Enable sending selection updates to Claude
   track_selection = true,
+
+  -- Diff provider configuration for openDiff MCP tool
+  diff_provider = "auto", -- "auto", "native", or "diffview"
+  diff_opts = {
+    auto_close_on_accept = true,    -- Auto-close diff when accepting changes
+    show_diff_stats = true,         -- Show diff statistics
+    vertical_split = true,          -- Use vertical split for diff view
+    open_in_current_tab = true,     -- Open diff in current tab (reduces clutter)
+  },
+
+  -- Terminal configuration
+  terminal = {
+    split_side = "right",           -- "left" or "right"
+    split_width_percentage = 0.30,  -- 0.0 to 1.0
+    provider = "snacks",            -- "snacks" or "native"
+    show_native_term_exit_tip = true, -- Show tip for Ctrl-\\ Ctrl-N
+  },
 }
 ```

DEVELOPMENT.md

@@ -9,11 +9,13 @@ claudecode.nvim/
 ├── .github/workflows/       # CI workflow definitions
 ├── lua/claudecode/          # Plugin implementation
 │   ├── server/              # WebSocket server implementation
-│   ├── tools/               # MCP tool implementations
+│   ├── tools/               # MCP tool implementations and schema management
 │   ├── config.lua           # Configuration management
+│   ├── diff.lua             # Diff provider system (native Neovim support)
 │   ├── init.lua             # Plugin entry point
 │   ├── lockfile.lua         # Lock file management
-│   └── selection.lua        # Selection tracking
+│   ├── selection.lua        # Selection tracking
+│   └── terminal.lua         # Terminal management
 ├── plugin/                  # Plugin loader
 ├── tests/                   # Test suite
 │   ├── unit/                # Unit tests
@@ -27,25 +29,28 @@ claudecode.nvim/
 
 ## Core Components Implementation Status
 
-| Component              | Status     | Priority | Notes                                    |
-| ---------------------- | ---------- | -------- | ---------------------------------------- |
-| Basic plugin structure | ✅ Done    | -        | Initial setup complete                   |
-| Configuration system   | ✅ Done    | -        | Support for user configuration           |
-| WebSocket server       | ✅ Done    | -        | Pure Lua RFC 6455 compliant              |
-| Lock file management   | ✅ Done    | -        | Basic implementation complete            |
-| Selection tracking     | ✅ Done    | -        | Enhanced with multi-mode support         |
-| MCP tools              | 🚧 Started | Medium   | Basic framework, need more tools         |
-| Tests                  | ✅ Done    | -        | 56 tests passing, comprehensive coverage |
-| CI pipeline            | ✅ Done    | -        | GitHub Actions configured                |
-| Documentation          | ✅ Done    | -        | Complete documentation                   |
+| Component              | Status  | Priority | Notes                                                   |
+| ---------------------- | ------- | -------- | ------------------------------------------------------- |
+| Basic plugin structure | ✅ Done | -        | Initial setup complete                                  |
+| Configuration system   | ✅ Done | -        | Support for user configuration                          |
+| WebSocket server       | ✅ Done | -        | Pure Lua RFC 6455 compliant                             |
+| Lock file management   | ✅ Done | -        | Basic implementation complete                           |
+| Selection tracking     | ✅ Done | -        | Enhanced with multi-mode support                        |
+| MCP tools framework    | ✅ Done | -        | Dynamic tool registration and schema system             |
+| Core MCP tools         | ✅ Done | -        | openFile, openDiff, getCurrentSelection, getOpenEditors |
+| Diff integration       | ✅ Done | -        | Native Neovim diff with configurable options            |
+| Terminal integration   | ✅ Done | -        | Snacks.nvim and native terminal support                 |
+| Tests                  | ✅ Done | -        | 55+ tests passing, comprehensive coverage               |
+| CI pipeline            | ✅ Done | -        | GitHub Actions configured                               |
+| Documentation          | ✅ Done | -        | Complete documentation                                  |
 
 ## Development Priorities
 
-1. **MCP Tool Enhancement**
+1. **Advanced MCP Tools**
 
-   - Implement additional tools from the findings document
-   - Add Neovim-specific tools (LSP, diagnostics, Telescope integration)
-   - Enhance existing tool implementations
+   - Add Neovim-specific tools (LSP integration, diagnostics, Telescope integration)
+   - Implement diffview.nvim integration for the diff provider system
+   - Add Git integration tools (branch info, status, etc.)
 
 2. **Performance Optimization**
 
@@ -127,18 +132,35 @@ The WebSocket server is implemented in pure Lua with zero external dependencies:
 - **Security**: Pure Lua SHA-1 implementation for WebSocket handshake
 - **Performance**: Optimized with lookup tables and efficient algorithms
 
-### Custom Tools
+### MCP Tool System
 
-Custom tools beyond the basic VS Code implementation could include:
+The plugin implements a sophisticated tool system following MCP 2025-03-26:
+
+**Current Tools:**
+
+- `openFile` - Opens files with optional line/text selection
+- `openDiff` - Native Neovim diff views with configurable options
+- `getCurrentSelection` - Gets current text selection
+- `getOpenEditors` - Lists currently open files
+
+**Tool Architecture:**
+
+- Dynamic registration: `M.register(name, schema, handler)`
+- Automatic MCP exposure based on schema presence
+- JSON schema validation for parameters
+- Centralized tool definitions in `tools/init.lua`
+
+**Future Tools:**
 
 - Neovim-specific diagnostics
-- LSP integration
+- LSP integration (hover, references, definitions)
 - Telescope integration for file finding
-- Git integration
+- Git integration (status, branch info, blame)
 
 ## Next Steps
 
-1. Enhance MCP tool implementations with Neovim-specific features
-2. Add integration tests with real Claude Code CLI
-3. Optimize performance for large codebases
-4. Create example configurations for popular Neovim setups (LazyVim, NvChad, etc.)
+1. Implement diffview.nvim integration for the diff provider system
+2. Add advanced MCP tools (LSP integration, Telescope, Git)
+3. Add integration tests with real Claude Code CLI
+4. Optimize performance for large codebases
+5. Create example configurations for popular Neovim setups (LazyVim, NvChad, etc.)