qf-mcp
Model Context Protocol (MCP) 服务器。AI我的助手Neovim的，之RPC通过接口Vim的，之quickfix以及location list中所述修改相应参数的值。Claude或者其他MCP客户机在编辑器中的代码错误、搜索结果和自定义quickfix可以直接操作条目。
概要
qf-mcp单击功能区上AI助手和Vim强大的quickfix做系统的桥梁。quickfix单击功能区上MCP作为工具公开AI可以：
- 各种源（lint错误、搜索结果、git diff）从quickfix创建/添加列表
- quickfix按程序导航项目
- 以受控的安全方式Vim执行命令
- 高级工作流自动化quickfix向操作添加动态挂接
服务器是Neovim和RPC (msgpack-rpc) 进行通信X11自动化工具无法正常工作Wayland所有的Neovim与安装兼容。
机能
-
6个MCP工具 综合的quickfix控制：
-
qf.set_list- quickfix或location list创建/添加 qf.get_cursor_item-当前quickfix获取项目详细信息qf.jump- quickfix在项目之间导航qf.add_hooks- quickfix向操作添加动态挂接vim.cmd-已注册白名单Vim执行命令-
health_check-检查服务器状态 -
Neovim RPC统合 - Unix套接字或TCP直接通信
-
Wayland互换 - X11无依赖关系Neovim在所有运行的环境中运行
-
安全优先设计 -命令白名单可防止执行任何代码
-
可扩展的挂钩系统 - quickfix向操作添加自定义行为
-
结构化错误处理 -用于调试的详细错误代码和消息
前提条件
必须
- 新 0.9+ (
--listen支持） - 转到1.21+ （从源构建时）
选项（高级功能）
- vim-qfhooks 插件 -
qf.add_hooks工具和高级quickfix操作所需 - 存储库：https://github.com/kis9a/vim-qfhooks
- 注意：核心quickfix功能（set_list，get_cursor_item，jump等）即使没有这个插件也能工作
- 如果没有此插件
qf.add_hooks工具不可用，某些高级功能是标准的Vim API后退
安装
详细的安装步骤是 安装.md 来修改标记元素的显示属性。
快速启动```bash
1. NeovimをRPCリスナー付きで起動
nvim --listen /tmp/nvim.sock
2. MCPサーバーを実行
qf-mcp --nvim-address /tmp/nvim.sock
服务器是stdio在传输上启动MCP准备好接收协议消息。
## MCP工具
### 1.qf.set_list
提供的项目quickfix或location list中所述修改相应参数的值。
**输入架构：**```json
{
"items": [
{
"file": "/path/to/file.go",
"lnum": 42,
"col": 10,
"text": "undefined variable: foo"
}
],
"title": "Lint Errors",
"contextKey": "lint-context",
"useLocationList": false
}
使用例:
- linter/从编译器输出quickfix添加到
- 创建可从搜索结果导航的列表
- 用于代码审核git diff导入汉克
2.qf.get_cursor_item
当前光标位置的quickfix获取项目。
输入架构：```json
{}
**出力:**```json
{
"file": "/path/to/file.go",
"lnum": 42,
"col": 10,
"text": "undefined variable: foo",
"title": "Lint Errors",
"context": {
"type": "lint",
"severity": "error"
}
}
3.qf.jump
quickfix在列表中导航。
输入架构：```json
{
"operation": "next"
}
**支持的操作：**
- `next` / `prev` -跳至下一个/上一个项目
- `first` / `last` -跳至第一个/最后一个项目
- `open` / `close` - quickfix打开/关闭窗口
- `cc` -跳转到当前项目
### 4.qf.add_hooks
quickfix将动态挂接添加到操作中。
**注意**：此工具包括： **vim-qfhooks 插件** 中所述修改相应参数的值。
**输入架构：**```json
{
"contextKey": "my-context",
"hooks": {
"on_qf_open": "echo 'Quickfix opened'",
"on_qf_close": "echo 'Quickfix closed'"
}
}
使用例:
- quickfix打开时自动执行操作
- 根据特定上下文定制工作流
- 编辑程序和AI自动化助手之间的交互
5.vim.cmd
已注册白名单Vim命令。
输入架构：```json
{
"command": "copen"
}
**白名单注册命令：**
- `copen`, `cclose`, `lopen`, `lclose` - Quickfix/location list窗口
- `cnext`, `cprev`, `lnext`, `lprev` -导航
- `cnfile`, `cpfile`, `lnfile`, `lpfile` -文件间导航
- `cfirst`, `clast`, `cc` -跳转命令
**安全注意事项**：其他命令将被阻止以防止任何代码执行。
### 6.健康检查
Neovim检查连接和挂接系统的可用性。
**输入架构：**```json
{}
出力:```json
{
"neovimConnected": true,
"hookSystemAvailable": true,
"version": {
"nvim": "0.10.0",
"api": "12"
}
}
## 设定
### 环境变数
- `NVIM_LISTEN_ADDRESS` - Neovim套接字地址（`--nvim-address`标记可覆盖）
- `LOG_LEVEL` -日志级别： `debug`, `info`, `warn`, `error` （默认值： `info`)
### Claude Desktop设定
`~/Library/Application Support/Claude/claude_desktop_config.json`添加到：```json
{
"mcpServers": {
"qf-mcp": {
"command": "/usr/local/bin/qf-mcp",
"args": ["--nvim-address", "/tmp/nvim.sock"],
"env": {
"LOG_LEVEL": "info"
}
}
}
}
Neovim的RPC带启动
Unix套接字（建议）：```bash
nvim --listen /tmp/nvim.sock
**TCP套接字：**```bash
nvim --listen localhost:6666
init.vim自动启动：```vim
" ~/.config/nvim/init.vim
call serverstart('/tmp/nvim.sock')
**Lua设定：**```lua
-- ~/.config/nvim/init.lua
vim.fn.serverstart('/tmp/nvim.sock')
体系结构```
┌─────────────────┐
│ Claude / AI │
│ Assistant │
└────────┬────────┘
│ MCP Protocol (stdio)
┌────────▼────────┐
│ qf-mcp │
│ MCP Server │
└────────┬────────┘
│ msgpack-rpc
│
┌────────▼────────┐
│ Neovim │
│ ┌───────────┐ │
│ │ Quickfix │ │ - Quickfix/location list
│ │ System │ │ - ナビゲーション
│ └───────────┘ │ - フックシステム (vim-qfhooks使用)
│ │ - コンテキスト管理
│ │ - 動的フック
└─────────────────┘
## 示例工作流
### Git Diff代码审核```
1. Claudeに依頼: "現在のgit diffの全変更をquickfixリストに作成して"
2. Claudeがqf.set_listを使用してdiffハンクをquickfixに追加
3. Claudeがqf.jumpを使用して変更を順にナビゲート
4. 各アイテムについて、Claudeがqf.get_cursor_itemでコンテキストを読み取り
5. Claudeが各変更に基づいてレビューコメントを提供
Lint修复错误```
- Claudeに依頼: "全てのlintエラーを修正して"
- Claudeがlintコマンドを実行して出力をパース
- qf.set_listでエラーをquickfixリストに追加
- qf.jumpで各エラーに移動
- qf.get_cursor_itemで詳細を取得し、修正を提案
## 故障排除
### Neovim挂牵
**症状:** `Error code 1004: Connection failed`
**解决方法：**
- Neovim确认是否正在运行： `ls -l /tmp/nvim.sock`
- Neovim 的`--listen`确认是否带标记启动
- qf-mcp和Neovim检查两个套接字路径是否匹配
### 挂接系统不可用
**症状:** health_check的 `hookSystemAvailable: false`
**解决方法：**
- 挂钩系统是可选的，基本功能没有这个也可以运行
- 单击功能区上的vim-qfhooks安装插件：```vim
" vim-plug の場合
Plug 'kis9a/vim-qfhooks'
- Neovim确认是否在中装入插件
命令不允许
症状: Error code 4001: Command not allowed
说明： 由于安全原因，命令未注册到白名单中。
解决方法：
- 仅使用白名单登录命令（参照vim.cmd文档）
- 将新命令添加到白名单PR提交
- 定制VimScript要执行qf.add_hooks使用
权限错误
症状: Permission denied 在插座上
解决方法：
- qf-mcp的Neovim中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积
- 检查套接字文件权限：
ls -l /tmp/nvim.sock
开発
从源构建```bash
リポジトリをクローン
git clone https://github.com/kis9a/qf-mcp.git
cd qf-mcp
バイナリをビルド
go build -o qf-mcp ./cmd/qf-mcp
テストを実行
go test ./... -v
統合テストを実行（Neovim必須）
./test/setup_test.sh go test ./test/... -v
### 项目结构```
qf-mcp/
├── cmd/qf-mcp/ # メインエントリポイント
├── internal/
│ ├── mcp/ # MCPサーバー実装
│ ├── nvim/ # Neovim RPCクライアント
│ ├── tools/ # MCPツール実装
│ ├── errors/ # エラーコード定義
│ └── logz/ # 構造化ログ
└── test/ # 統合テスト
貢献
欢迎贡献！您可以通过以下方式参加：
- Issue创建错误报告和功能建议
- PR提交代码改善
- 文档改进
- 共享用例和工作流
许可证
MIT License - 了解更多信息LICENSE 浏览文件
相关项目
- vim问答 - Vim的，之quickfix挂钩插件（
qf.add_hooks功能需要） - https://github.com/kis9a/vim-qfhooks
- 模型上下文协议 - MCP仕様
- go客户端 - Neovim Go RPC客户机
支持
- 问题： GitHub 问题
- 讨论： GitHub讨论
谢辞
使用以下项目构建：
- MCP Go SDK - MCP协议实现
- neovim/go-client - Neovim RPC客户机
- zerolog -结构化日志
- vim问答 - Quickfix挂钩插件
