CodeCompanion.nvim 的 MCP 服务器配置完全指南从基础接入到工具行为定制【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim导读Model Context ProtocolMCP是连接 AI 应用与外部系统、数据源与工具的开源标准。CodeCompanion.nvim 自 PR #2549 起加入了对 MCP 的支持让 Neovim 用户能够把检索、网页搜索、文件系统、顺序思考等各类 MCP 服务器直接接入聊天缓冲区由 LLM 以 Agent 的方式调用其暴露的工具。本文将完整讲解 CodeCompanion 中 MCP 的配置骨架mcp.servers、环境变量注入、Roots 能力、默认服务器、工具行为覆盖tool_overrides/tool_defaults等核心主题并结合仓库源码说明底层实现原理帮助你从零开始把 MCP 服务器稳定地接入自己的 Neovim 工作流。前置认知CodeCompanion 实现了哪些 MCP 能力在动手配置前先明确 CodeCompanion 对 MCP 协议的支持边界。根据 doc/model-context-protocol.md 的说明插件实现了 2025-11-25 版本的协议子集聚焦于开发者编码体验所需的核心特性特性类别支持情况说明传输层Stdio✅ 支持通过子进程标准输入输出通信传输层Streamable HTTP❌ 不支持—基础取消Cancellation✅ 支持超时或用户手动取消基础进度Progress❌ 不支持—基础任务Task❌ 不支持—客户端Roots✅ 支持默认禁用需显式开启客户端Sampling / Elicitation❌ 不支持—服务端Tools✅ 支持目前仅支持文本Text Content类型输出服务端Pagination✅ 支持支持nextCursor分页拉取工具列表服务端Prompts / Resources / Completion❌ 不支持—服务端Tool list changed notification❌ 不支持—当前 CodeCompanion 中 MCP 工具的主要使用场景是聊天交互chat interactions即通过聊天缓冲区让 LLM 调用 MCP 服务器暴露的工具。了解这些边界有助于你选择兼容的 MCP 服务器避免依赖未实现的能力。基础配置注册一个 MCP 服务器CodeCompanion 通过mcp.servers配置项让插件获知 MCP 服务器的存在。它是一个服务器定义列表每一项描述如何连接到对应的 MCP 服务器require(codecompanion).setup({ mcp { servers { [tavily-mcp] { cmd { npx, -y, tavily-mcplatest }, }, }, }, })最简配置只需cmd字段——它是一个字符串数组会被作为子进程命令启动。在 lua/codecompanion/mcp/init.lua 的类型定义中ServerConfig包含以下字段cmdstring[]必填启动 MCP 服务器的命令行envtablestring, string可选传递给子进程的环境变量rootsfunction可选返回 Roots 列表的函数register_roots_list_changedfunction可选Roots 列表变化时的通知回调server_instructionsstring 或 function可选覆盖服务器自带的 instructionstool_defaults/tool_overridestable可选工具行为定制见后文。配置完成后被标记为默认服务器的条目会在首次打开聊天缓冲区时自动启动其工具会加入聊天缓冲区其余服务器可通过/mcp斜杠命令按需启停详见下文默认服务器一节。环境变量安全注入 API Key 等敏感信息很多 MCP 服务器如 Tavily、各类检索服务需要 API Key 才能工作。env字段可以把环境变量传给子进程require(codecompanion).setup({ mcp { servers { [tavily-mcp] { cmd { npx, -y, tavily-mcplatest }, env { TAVILY_API_KEY cmd:op read op://personal/Tavily_API/credential --no-newline, }, }, }, }, })上面的例子使用 1Password CLI 动态获取 API Key避免把密钥明文写死在配置文件里。你也可以直接复用 CodeCompanion 内置的环境变量插值能力详见 doc/configuration/adapters-http.md从任意来源取值普通环境变量名字符串直接填入已设置的环境变量名如HOME、GEMINI_API_KEY插件运行时读取其值命令cmd:前缀以cmd:开头的值会通过 shell 执行例如cmd:op read op://personal/Gemini/credential --no-newline函数提供一个以 adapter 为唯一参数的 Lua 函数返回字符串Schema 引用点号记法引用配置表中其他字段如schema.model.default文件file:前缀以file:开头的值会从磁盘读取支持相对 cwd 或~路径每次请求时重新读取而非缓存。在 lua/codecompanion/mcp/client.lua 的StdioTransport:start中可以看到启动子进程前会调用adapter_utils.get_env_vars(self)解析这些env值再通过adapter_utils.set_env_vars把解析结果注入命令行与进程环境——也就是说环境变量插值能力与 HTTP 适配器共用同一套实现。Lazy / Deferred 配置按需求值如果你希望配置项在服务器首次被需要时才求值例如某些环境变量在 Neovim 启动后才被设置可以把服务器定义写成一个函数。该函数只会被调用一次结果会被缓存memoizedrequire(codecompanion).setup({ mcp { servers { -- The function is called once, only when the server is first needed. [tavily-mcp] function() return { cmd { npx, -y, tavily-mcplatest }, env { TAVILY_API_KEY os.getenv(TAVILY_API_KEY), }, } end, }, }, })这一机制在 lua/codecompanion/mcp/init.lua 的get_server_config中实现当config.mcp.servers[name]是函数时先执行一次并把结果存入resolved_configs缓存后续读取直接返回缓存值。Roots声明服务器可访问的目录MCP 的 Roots 机制允许客户端声明服务器可以访问的目录。CodeCompanion 支持 Roots但出于安全考虑默认禁用。启用方式是在服务器配置中加入roots字段require(codecompanion).setup({ mcp { servers { filesystem { cmd { npx, -y, modelcontextprotocol/server-filesystem }, roots function() -- Return a list of names and directories as per: -- https://modelcontextprotocol.io/specification/2025-11-25/client/roots#listing-roots end, }, }, }, })roots是一个函数返回形如{ name?: string, uri: string }的列表。在 lua/codecompanion/mcp/client.lua 中可以看到客户端初始化时会把capabilities.roots声明为{ listChanged self.cfg.register_roots_list_changed ~ nil }当服务器发起roots/list请求时会调用配置的roots函数并校验返回值若函数抛错或返回非法值则以错误响应回复服务器见 lua/codecompanion/mcp/client.lua。监听 Roots 列表变化如果 Roots 列表可能在运行时变化例如由其他插件动态调整可通过register_roots_list_changed注册通知回调require(codecompanion).setup({ mcp { servers { filesystem { cmd { npx, -y, modelcontextprotocol/server-filesystem }, ---param notify fun() register_roots_list_changes function(notify) -- Call notify() whenever the list of roots changes. end, }, }, }, })当调用notify()时客户端会向服务器发送notifications/roots/list_changed通知见 lua/codecompanion/mcp/client.lua 与 lua/codecompanion/mcp/methods.lua。[!IMPORTANT] Roots 特性对 MCP 服务器而言只是一个提示hint。合规的服务器会据此限制文件系统访问范围但 CodeCompanion无法强制服务器遵守。对于不受信任的服务器请使用容器等隔离机制而不是依赖 Roots。默认服务器自动启动与按需启动mcp.opts.default_servers控制哪些服务器会随聊天缓冲区自动启动、其工具自动加入聊天缓冲区。不在该列表中的服务器可以通过/mcp斜杠命令按需启动require(codecompanion).setup({ mcp { servers { [sequential-thinking] { cmd { npx, -y, modelcontextprotocol/server-sequential-thinking }, }, [tavily-mcp] { cmd { npx, -y, tavily-mcplatest }, }, }, opts { default_servers { sequential-thinking }, }, }, })在上述配置下sequential-thinking会在打开聊天缓冲区时自动启动而tavily-mcp则需要通过/mcp手动启动。在 lua/codecompanion/config.lua 中可以看到mcp配置的完整默认值mcp { servers {}, opts { default_servers {}, -- List of server names to auto-start and add to chat acp_enabled true, -- Enable MCP servers with ACP adapters? timeout 30e3, -- Timeout for MCP server responses (milliseconds) }, },其中timeout默认 30 秒是 MCP 服务器响应的超时时间对应客户端代码中每个 JSON-RPC 请求的计时器——超时后请求会被取消发送notifications/cancelled并返回超时错误见 lua/codecompanion/mcp/client.lua。与 prompt library 的优先级关系[!NOTE] 如果在某个 prompt library 条目中显式指定了mcp_servers则该条目优先default_servers的逻辑会为该聊天缓冲区跳过。这一行为在 lua/codecompanion/interactions/chat/init.lua 中得到印证聊天初始化时若args.mcp_servers none则完全不启动 MCP 服务器若显式传入args.mcp_servers则启动指定列表否则才回落到helpers.mcp_servers_to_add_to_chat()计算出的默认服务器列表。使用/mcp斜杠命令手动管理服务器/mcp斜杠命令允许你随时查看并切换所有已配置 MCP 服务器的启停状态。其实现位于 lua/codecompanion/interactions/chat/slash_commands/builtin/mcp.lua命令入口会检查config.mcp.servers是否为空若没有任何配置则禁用该命令并提示[MCP] No servers found in your configuration执行时会通过mcp.get_status()拉取所有服务器的状态ready、tool_count、started、default以vim.ui.select默认 provider或 Snacks.nvim 选择器展示每条目形如✓ sequential-thinking (ready, tools: 3)选中服务器后调用mcp.toggle_server(name)完成启停切换并在通知中提示MCP server xxx started/stopped。服务器启动后其工具会以mcp:前缀出现在聊天缓冲区的补全菜单中输入即可看到例如mcp:tavily-mcp_search。工具加载完成后还会触发MCPServerToolsLoaded与ChatRefreshCache事件刷新聊天缓冲区缓存见 lua/codecompanion/mcp/client.lua。覆盖工具行为tool_overridesMCP 服务器通常会暴露多个工具。以数学服务器为例它可能提供add、subtract、multiply、divide四个工具。tool_overrides允许你按单个工具定制其选项、输出处理、系统提示词与超时时间。[!IMPORTANT]tool_overrides的键是MCP 工具名如divide而不是 CodeCompanion 内部使用的带前缀名称如math-server_divide。这一点在 lua/codecompanion/mcp/tool_bridge.lua 中可以看到client.cfg.tool_overrides[mcp_tool.name]直接以 MCP 原始工具名为键查找。示例一要求批准Requiring Approval让某个工具在每次执行前都需要用户批准require(codecompanion).setup({ mcp { servers { [math-server] { cmd { npx, -y, math-mcp-server }, tool_overrides { divide { opts { require_approval_before true, }, }, }, }, }, }, })示例二自定义输出处理Custom Output自定义工具成功执行后的输出格式化。下面的例子把结果重新格式化为a b 结果的友好形式require(codecompanion).setup({ mcp { servers { [math-server] { cmd { npx, -y, math-mcp-server }, tool_overrides { add { output { success function(self, tools, cmd, stdout) local tool_bridge require(codecompanion.mcp.tool_bridge) local content stdout and stdout[#stdout] local output tool_bridge.format_tool_result_content(content) local msg string.format(%d %d %s, self.args.a, self.args.b, output) tools.chat:add_tool_output(self, output, msg) end, }, }, }, }, }, }, })这里用到了tool_bridge.format_tool_result_content——它会把 MCP 返回的内容块解析为纯文本当内容为单元素且类型是text时直接返回文本否则用vim.inspect序列化见 lua/codecompanion/mcp/tool_bridge.lua。示例三定制系统提示词System Prompt为特定工具追加系统提示词引导 LLM 的使用方式require(codecompanion).setup({ mcp { servers { [math-server] { cmd { npx, -y, math-mcp-server }, tool_overrides { multiply { system_prompt When using the multiply tool, always show your working., }, }, }, }, }, })Tool Defaults为所有工具设置默认值tool_defaults可以为服务器暴露的全部工具设置默认选项。注意tool_overrides的优先级高于tool_defaultsrequire(codecompanion).setup({ mcp { servers { [math-server] { cmd { npx, -y, math-mcp-server }, tool_defaults { require_approval_before true, }, -- Per-tool overrides take precedence over tool_defaults tool_overrides { add { opts { require_approval_before false, }, }, }, }, }, }, })在这个例子中math-server的全部工具默认都需要批准但add工具被显式豁免。Override Options 参数总览每个工具覆盖项ToolOverride可包含以下字段选项类型说明optstable工具选项如require_approval_before、require_approval_afteroutputtable自定义输出处理器success、error、prompt、rejected、cancelledsystem_promptstring该工具追加的系统提示词文本timeoutnumber该工具的自定义超时时间毫秒enabledboolean该工具是否启用这些字段与 lua/codecompanion/mcp/init.lua 中CodeCompanion.MCP.ToolOverride的类型定义一一对应其中enabled还支持传入函数形式的动态判断。源码视角MCP 工具如何接入聊天缓冲区理解底层调用链有助于你调试和深度定制。整个流程大致如下启动与初始化默认服务器在打开聊天缓冲区时由M.start_servers()启动lua/codecompanion/mcp/init.lua。Client:start()启动 Stdio 子进程后通过 JSON-RPC 发送initialize请求协议版本2025-11-25随后发送notifications/initialized通知标记ready true并触发MCPServerReady事件lua/codecompanion/mcp/client.lua。拉取工具列表客户端调用tools/list获取服务器工具清单并通过nextCursor处理分页单服务器工具数上限为 100MAX_TOOLS_PER_SERVER工具加载完成后由tool_bridge.setup_tools注册到工具注册表lua/codecompanion/mcp/client.lua。工具桥接tool_bridge.build把每个 MCP 工具包装成 CodeCompanion 工具——名称加mcp:前缀并合并 override/default 配置把 MCP 的inputSchema作为 OpenAI 函数调用 schemastrict true执行时通过tools/call调用服务器lua/codecompanion/mcp/tool_bridge.lua。工具组group以Tools from MCP Server xxx的形式出现在聊天缓冲区中并默认折叠为单个上下文项collapse_tools true。执行与取消工具调用支持按聊天缓冲区维度取消——Client:cancel_request_from_chat会遍历待处理请求向服务器发送notifications/cancelled通知lua/codecompanion/mcp/client.lua。此外CodeCompanion 在VimLeavePre时自动停止所有 MCP 服务器退出时采用先关 stdin → 超时 SIGTERM → 再超时 SIGKILL的三段式优雅停机见 lua/codecompanion/mcp/client.lua。刷新配置修改 MCP 配置后无需重启 NeovimM.refresh()会停止并重新启动所有服务器让新配置立即生效lua/codecompanion/mcp/init.lua。实用建议与注意事项敏感信息不要硬编码优先使用cmd:前缀配合密码管理器 CLI或引用已设置的环境变量避免 API Key 落入配置文件与版本控制。区分默认启动与按需启动把轻量、常用的服务器放入default_servers重量级或偶发使用的服务器留待/mcp手动启动以控制聊天缓冲区工具数量与上下文开销。Roots 仅作提示不要依赖 Roots 约束不可信服务器容器化隔离才是更可靠的安全边界。按工具收紧权限对破坏性工具如删除、写文件通过tool_overrides设置require_approval_before true必要时配合require_approval_after利用tool_defaults一次性收紧全部工具的默认权限再用 override 为可信工具放行。注意协议边界CodeCompanion 目前仅支持 Stdio 传输与文本内容选择 MCP 服务器时需确认其兼容 2025-11-25 协议版本且输出为文本类型。配置即时生效调整mcp.servers后调用require(codecompanion.mcp).refresh()或触发相关命令即可热更新无需重启 Neovim。延伸阅读doc/model-context-protocol.mdMCP 支持能力矩阵与协议版本说明doc/usage/chat-buffer/agents-tools.md工具与 Agent 在聊天缓冲区中的使用方式doc/usage/chat-buffer/slash-commands.md/mcp等斜杠命令的完整清单doc/configuration/adapters-http.md环境变量插值语法cmd:、file:、函数等的详细说明lua/codecompanion/mcp/init.lua、lua/codecompanion/mcp/client.lua、lua/codecompanion/mcp/tool_bridge.luaMCP 模块的核心实现tests/mcp/MCP 相关的测试用例可作为理解行为边界的参考。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考