Helix MCP Server

Helix MCP服务器

一种模型上下文协议（MCP）服务器，通过开放代码为Helix编辑器提供高级文件打开功能。

特性

• 多文件支持：在Helix中同时打开多个文件
• 行号跳转：使用Helix直接导航到特定的行号 file:line 语法
• Git集成：通过创建临时文件查看来自不同提交、分支或标记的文件
• 文件修改跟踪：检测在编辑会话期间修改了哪些文件
• 自动清理：临时git ref文件会自动清理

安装

1. 构建服务器：

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

1. 在opencode中配置(opencode.json):

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

用法

服务器提供了一个工具： helix_open

参数

• 文件 （必填）：文件对象数组，每个对象包含：

- 文件路径 （必需）：要打开的文件的路径 - 行号 （可选）：要跳转到的行号（至少1个） - gitRef （可选）：Git commit/branch/tag打开文件 - 标签 （可选）：文件的自定义标签（适用于git参考）

例子

带行号的单个文件

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

结果如下： hx src/main.rs:42

多个文件

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

结果如下： hx src/main.rs:10 src/lib.rs:25 Cargo.toml

Git提交比较

{
  "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" }
  ]
}

创建临时文件并打开： hx src/config.rs /tmp/config-HEAD~1-Previous.rs /tmp/config-main-Main_branch.rs

历史文件视图

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

结果如下： hx /tmp/parser-abc123-Bug_fix_commit.rs:89

实现细节

文件处理

1. 验证：检查文件是否存在并解析路径
2. Git参考：创建包含以下内容的临时文件 git show ${gitRef}:${filePath}
3. 状态跟踪：记录打开前的文件修改次数
4. Helix发射：用途 spawn('hx', args) 随着 stdio: 'inherit'
5. 修改检测：比较Helix关闭后的文件状态
6. 清理：删除临时git ref文件

安全功能

• 使用路径验证 resolve() 防止目录遍历
• Git命令验证和错误处理
• 硬编码 hx 命令（无外壳注入）
• 自动清理临时文件

错误处理

• 找不到文件错误
• 无效的git引用
• 在PATH中找不到螺旋
• Git存储库不可用
• 权限问题

终端行为

该工具提供阻塞操作，其中：

1. 用户请求通过opencode打开文件
2. 终端切换到Helix并加载文件
3. 用户在Helix中编辑文件
4. 用户退出Helix(:q)
5. 终端返回opencode并显示结果

输出格式

Helix会话完成后，工具返回：

• 退出代码和持续时间
• 已打开的文件列表
• 已修改的文件列表
• 临时文件指示符

输出示例：

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

需求

• Node.js（用于运行MCP服务器）
• 螺旋编辑器(hx PATH中可用的命令）
• Git（用于Git ref功能）
• 支持MCP的开放代码