Desos/helix-mcp-server

Helix MCP Server

A Model Context Protocol (MCP) server that provides advanced file opening capabilities for the Helix editor through opencode.

Features

• Multiple file support: Open several files simultaneously in Helix
• Line number jumping: Navigate directly to specific line numbers using Helix's file:line syntax
• Git integration: View files from different commits, branches, or tags by creating temporary files
• File modification tracking: Detect which files were modified during the editing session
• Automatic cleanup: Temporary git ref files are automatically cleaned up

Installation

1. Build the server:

cd /home/peter/Environment/helix-mcp-server
npm install
npm run build

2. Configure in opencode (opencode.json):

{
  "mcp": {
    "helix-editor": {
      "type": "local",
      "command": ["node", "/home/peter/Environment/helix-mcp-server/dist/index.js"],
      "enabled": true
    }
  }
}

Usage

The server provides a single tool: helix_open

Parameters

• files (required): Array of file objects, each containing:
  • filePath (required): Path to the file to open
  • lineNumber (optional): Line number to jump to (minimum 1)
  • gitRef (optional): Git commit/branch/tag to open file from
  • label (optional): Custom label for the file (useful with git refs)

Examples

Single file with line number

{
  "files": [
    { "filePath": "src/main.rs", "lineNumber": 42 }
  ]
}

Results in: hx src/main.rs:42

Multiple files

{
  "files": [
    { "filePath": "src/main.rs", "lineNumber": 10 },
    { "filePath": "src/lib.rs", "lineNumber": 25 },
    { "filePath": "Cargo.toml" }
  ]
}

Results in: hx src/main.rs:10 src/lib.rs:25 Cargo.toml

Git commit comparison

{
  "files": [
    { "filePath": "src/config.rs", "label": "Current" },
    { "filePath": "src/config.rs", "gitRef": "HEAD~1", "label": "Previous" },
    { "filePath": "src/config.rs", "gitRef": "main", "label": "Main branch" }
  ]
}

Creates temporary files and opens: hx src/config.rs /tmp/config-HEAD~1-Previous.rs /tmp/config-main-Main_branch.rs

Historical file view

{
  "files": [
    { 
      "filePath": "src/parser.rs", 
      "gitRef": "abc123", 
      "lineNumber": 89, 
      "label": "Bug fix commit" 
    }
  ]
}

Results in: hx /tmp/parser-abc123-Bug_fix_commit.rs:89

Implementation Details

File Processing

1. Validation: Checks file existence and resolves paths
2. Git refs: Creates temporary files with content from git show ${gitRef}:${filePath}
3. State tracking: Records file modification times before opening
4. Helix launch: Uses spawn('hx', args) with stdio: 'inherit'
5. Modification detection: Compares file states after Helix closes
6. Cleanup: Removes temporary git ref files

Security Features

• Path validation using resolve() to prevent directory traversal
• Git command validation and error handling
• Hardcoded hx command (no shell injection)
• Automatic cleanup of temporary files

Error Handling

• File not found errors
• Invalid git refs
• Helix not found in PATH
• Git repository not available
• Permission issues

Terminal Behavior

The tool provides a blocking operation where:

1. User requests file opening via opencode
2. Terminal switches to Helix with files loaded
3. User edits file(s) in Helix
4. User quits Helix (:q)
5. Terminal returns to opencode with results

Output Format

After the Helix session completes, the tool returns:

• Exit code and duration
• List of files that were opened
• List of files that were modified
• Temporary file indicators

Example output:

Helix editor session completed
Exit code: 0
Duration: 45s

Files opened:
  - src/config.rs:10 (Current)
  - /tmp/config-HEAD~1-Previous.rs (Previous) [temporary]
  - /tmp/config-main-Main_branch.rs (Main branch) [temporary]

Modified files:
  - src/config.rs

Requirements

• Node.js (for running the MCP server)
• Helix editor (hx command available in PATH)
• Git (for git ref functionality)
• opencode with MCP support