qf MCP

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 来修改标记元素的显示属性。

快速启动

# 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中所述修改相应参数的值。

输入架构：

{
  "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获取项目。

输入架构：

{}

出力:

{
  "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在列表中导航。

输入架构：

{
  "operation": "next"
}

支持的操作：

• next / prev -跳至下一个/上一个项目
• first / last -跳至第一个/最后一个项目
• open / close - quickfix打开/关闭窗口
• cc -跳转到当前项目

4.qf.add_hooks

quickfix将动态挂接添加到操作中。

注意：此工具包括： vim-qfhooks 插件 中所述修改相应参数的值。

输入架构：

{
  "contextKey": "my-context",
  "hooks": {
    "on_qf_open": "echo 'Quickfix opened'",
    "on_qf_close": "echo 'Quickfix closed'"
  }
}

使用例:

• quickfix打开时自动执行操作
• 根据特定上下文定制工作流
• 编辑程序和AI自动化助手之间的交互

5.vim.cmd

已注册白名单Vim命令。

输入架构：

{
  "command": "copen"
}

白名单注册命令：

• copen, cclose, lopen, lclose - Quickfix/location list窗口
• cnext, cprev, lnext, lprev -导航
• cnfile, cpfile, lnfile, lpfile -文件间导航
• cfirst, clast, cc -跳转命令

安全注意事项：其他命令将被阻止以防止任何代码执行。

6.健康检查

Neovim检查连接和挂接系统的可用性。

输入架构：

{}

出力:

{
  "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添加到：

{
  "mcpServers": {
    "qf-mcp": {
      "command": "/usr/local/bin/qf-mcp",
      "args": ["--nvim-address", "/tmp/nvim.sock"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Neovim的RPC带启动

Unix套接字（建议）：

nvim --listen /tmp/nvim.sock

TCP套接字：

nvim --listen localhost:6666

init.vim自动启动：

" ~/.config/nvim/init.vim
call serverstart('/tmp/nvim.sock')

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修复错误

1. Claudeに依頼: "全てのlintエラーを修正して"
2. Claudeがlintコマンドを実行して出力をパース
3. qf.set_listでエラーをquickfixリストに追加
4. qf.jumpで各エラーに移動
5. 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-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

开発

从源构建

# リポジトリをクローン
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/                # 統合テスト

貢献

欢迎贡献！您可以通过以下方式参加：

1. Issue创建错误报告和功能建议
2. PR提交代码改善
3. 文档改进
4. 共享用例和工作流

许可证

MIT License - 了解更多信息LICENSE 浏览文件

相关项目

• vim问答 - Vim的，之quickfix挂钩插件（qf.add_hooks功能需要）

- https://github.com/kis9a/vim-qfhooks

• 模型上下文协议 - MCP仕様
• go客户端 - Neovim Go RPC客户机

支持

• 问题：
• 讨论：

谢辞

使用以下项目构建：

• MCP Go SDK - MCP协议实现
• neovim/go-client - Neovim RPC客户机
• zerolog -结构化日志
• vim问答 - Quickfix挂钩插件