07 · 工具、MCP、LSP 与格式化器

Coding agent 的质量不只取决于模型，也取决于它能接触哪些工具。OpenCode 的工具系统把本地开发环境、MCP、LSP 和 formatter 接到 agent 工作流里。

内置工具先够用

大多数任务先用内置能力就够：

• 读取文件。
• 修改文件。
• 运行 shell 命令。
• 查看项目结构。
• 执行测试和格式化。
• 根据命令输出继续修复。

不要一开始就接很多 MCP server。工具越多，权限边界越复杂，模型选择错误工具的概率也会增加。

MCP 适合什么

MCP server 适合把外部系统变成 agent 可调用工具。例如：

• GitHub issue / PR。
• 数据库查询。
• 内部 API。
• 文档搜索。
• 设计稿读取。
• 浏览器自动化。
• 项目管理系统。

MCP 的价值是让 agent 获取“项目外部上下文”。如果信息已经在本地文件里，就不一定需要 MCP。

LSP 的价值

LSP 给 agent 提供更接近 IDE 的代码理解能力，包括符号、诊断、跳转和类型信息。对大型代码库来说，这比单纯全文搜索更可靠。

适合依赖 LSP 的任务：

• 找函数定义和引用。
• 判断类型错误。
• 理解跨文件调用关系。
• 修复编译诊断。
• 做局部重命名或接口调整。

但 LSP 不是万能。项目依赖没装好、语言服务器没启动、monorepo 配置复杂时，LSP 信息也可能不完整。关键改动仍要靠测试验证。

Formatter 的边界

Formatter 适合做机械格式化，不适合掩盖逻辑问题。

推荐流程：

1. 让 agent 完成最小代码改动
2. 跑测试或类型检查
3. 再运行 formatter
4. 检查 diff 是否只包含预期范围

不要一开始就全仓库格式化。大范围格式化会淹没真实逻辑 diff，也增加回滚风险。

Custom Tools 什么时候需要

当一个 shell 命令反复使用，并且输出需要被 agent 稳定解释时，可以封装成 custom tool。

适合封装的例子：

• 查询内部服务状态。
• 运行项目专用诊断。
• 读取结构化配置。
• 生成固定格式报告。
• 调用公司内部 API。

不要把危险操作封装成“一键执行”的工具，例如删除数据、发布生产、重置数据库。即使封装，也必须加确认和 dry-run。

工具治理原则

OpenCode 接工具时，按这个顺序推进：

本地只读工具
本地可写工具
项目测试/检查工具
MCP 只读外部工具
MCP 可写外部工具
发布/生产工具

每往后一层，权限和审计要求都要更严格。