用途
overseer-nvim-mcp 是一个 MCP（Model Context Protocol）服务器，旨在弥合编码智能体的 shell 工具与 Neovim 中 overseer.nvim 任务列表之间的鸿沟。智能体在自己的 shell 中启动的开发服务器等长期运行命令，原本在 overseer 任务列表中不可见、无法从列表停止，且会话结束时进程树会孤立。该服务器让智能体的长期运行命令成为真正的 overseer 任务，从而获得与用户手动启动任务相同的控制能力。
主要能力
服务器提供七个工具，每个都是通过 msgpack-RPC 对 overseer 执行 nvim_exec_lua：
- overseer_list_tasks：列出任务，报告来源（agent 或 user）。
- overseer_tail：跟踪任务输出，支持 wait_for 正则等待匹配行、任务退出或超时，并返回 total 游标和 from 索引。
- overseer_run：运行不自行退出的命令（如开发服务器、文件监视器、--watch 测试），支持 settle_ms 短暂等待输出或退出。
- overseer_restart：重启任务，需 force 才能操作运行中的用户任务。
- overseer_stop：停止任务，需 force 才能操作运行中的用户任务。
- overseer_dispose：销毁任务，需 force 才能操作运行中的用户任务。
- overseer_list_templates：列出 overseer 提供者发现的任务模板，返回原始结果，包括描述、参数、运行中的任务 ID 等。 任务可通过数字 ID 或大小写不敏感的名称子串寻址。子串匹配多个任务时会报错并列出候选，要求使用数字 ID。
使用方式
服务器通过 stdio 通信，由 MCP 客户端启动。命令始终相同。客户端必须运行在 Neovim 终端缓冲区中，因为服务器需要继承 $NVIM 套接字。工具在下次会话启动时出现，因为 MCP 服务器在启动时连接。如果工具未出现，通常是因为 $NVIM 未到达服务器环境。
配置示例：
- Codex：在 ~/.codex/config.toml 中添加 env_vars 行，必须包含 NVIM。
- Gemini：在 ~/.gemini/config/mcp_config.json 中配置，用户全局文件是唯一加载 MCP 服务器的位置。
- Antigravity：在 settings.json 或 opencode.json 中配置。
- mcphub：在 servers 配置中添加 env 块，必须包含 NVIM。
- LazyVim：启用 overseer.nvim extra（:LazyExtras 选择 editor.overseer），重启 Neovim，然后按上述配置 MCP 客户端。
服务器还发布两个可驱动的功能：
- Prompts：以斜杠命令形式出现（如 /mcp__overseer__...），包括 directory_local_task（为没有 npm 脚本、Makefile 或 Taskfile 的项目定义任务）和 diagnose（解释 overseer 为何未显示预期任务）。
- Resources：可附加资源，包括 overseer://tasks（整个任务列表 JSON）和 overseer://task/{id}/output（单个任务输出）。
适用场景
- 智能体需要启动开发服务器、文件监视器或 --watch 测试运行等长期运行命令。
- 用户希望这些命令出现在 overseer 任务列表中，并能从列表监控和停止。
- 需要避免智能体 shell 中启动的进程在会话结束后孤立。
- 需要智能体检查任务模板、按名称运行任务、跟踪输出并清理自己的任务。
限制
- 需要 Neovim 和 overseer.nvim（针对 v2.1.0 测试）。
- MCP 客户端必须运行在 Neovim 终端缓冲区中，以继承 $NVIM 套接字。
- 如果 $NVIM 未设置，服务器不注册任何工具，运行在 Neovim 外是无操作而非错误。
- 某些客户端（如 Codex CLI、Antigravity CLI）不会自动使用服务器，需要在提示中明确提及 overseer 或在项目上下文文件（如 AGENTS.md、GEMINI.md）中添加指令。
- overseer_run 适用于不自行退出的命令；短命令应使用智能体常规 shell 工具。
- overseer_list_templates 返回空列表是正常情况，表示没有可运行的任务。
- 服务器不包含提供者特定知识，不筛选或重写结果。
- 等待操作在 Node 中执行，避免阻塞 Neovim。
- 输出中的 exit_code 在任务运行时缺失，退出后出现。
- 许可证为 MIT。
