OpenCode 高级玩法：自定义工具、MCP 服务器与命令系统完整指南

OpenCode 高级玩法：自定义工具、MCP 服务器与命令系统完整指南

在前两篇文章中，我们介绍了 OpenCode 的安装配置和模型提供商设置。当你已经能够熟练使用 OpenCode 完成日常编码任务后，下一步就是探索它的高级扩展能力。OpenCode 提供了三种强大的扩展机制：自定义工具（Custom Tools）、MCP 服务器（Model Context Protocol） 和 自定义命令（Commands）。本文将深入讲解这三种机制，帮你把 OpenCode 打造成真正贴合个人工作流的开发利器。

一、自定义工具：让 LLM 拥有你的专属能力

自定义工具是 OpenCode 最灵活的扩展方式。你可以创建 LLM 能够调用的函数，让 AI 助手不仅仅能读写文件和执行命令，还能执行你定义的任何逻辑——比如查询数据库、调用内部 API、运行特定的业务脚本。

1.1 工具的基本结构

自定义工具以 TypeScript 文件定义，放在项目的 .opencode/tools/ 目录下（或全局目录 ~/.config/opencode/tools/）。文件名即为工具名。

最基本的工具定义如下：

// .opencode/tools/database.ts
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "查询项目数据库",
  args: {
    query: tool.schema.string().describe("要执行的 SQL 查询"),
  },
  async execute(args) {
    // 你的数据库查询逻辑
    return `执行查询: ${args.query}`
  },
})

每个工具需要定义三个核心部分：

• description：描述工具功能，LLM 据此决定何时调用
• args：参数定义，使用 Zod schema 进行类型校验
• execute：执行函数，返回字符串结果

1.2 多工具导出与名称冲突

一个文件可以导出多个工具，工具名称为 <文件名>_<导出名>：

// .opencode/tools/math.ts
import { tool } from "@opencode-ai/plugin"

export const add = tool({
  description: "两数相加",
  args: {
    a: tool.schema.number().describe("第一个数"),
    b: tool.schema.number().describe("第二个数"),
  },
  async execute(args) {
    return (args.a + args.b).toString()
  },
})

这会生成 math_add 和 math_multiply 两个工具。如果自定义工具与内置工具同名，自定义工具会覆盖内置工具，因此命名时需谨慎。

1.3 使用其他语言编写工具逻辑

工具定义文件必须是 TypeScript/JavaScript，但执行逻辑可以调用任何语言编写的脚本。例如调用 Python 脚本：

# .opencode/tools/add.py
import sys
a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

// .opencode/tools/python-add.ts
import { tool } from "@opencode-ai/plugin"
import path from "path"

export default tool({
  description: "使用 Python 计算两数相加",
  args: {
    a: tool.schema.number().describe("第一个数"),
    b: tool.schema.number().describe("第二个数"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

这里的 context 对象提供了会话上下文信息，包括 agent、sessionID、directory（会话工作目录）和 worktree（Git 工作树根目录），方便工具定位项目文件。

二、MCP 服务器：接入海量第三方工具

MCP（Model Context Protocol）是由 Anthropic 推出的开放协议，旨在为 LLM 提供标准化的工具调用接口。OpenCode 原生支持 MCP，可以接入本地或远程的 MCP 服务器，瞬间获得大量现成的工具能力。

2.1 配置本地 MCP 服务器

本地 MCP 服务器是通过执行命令启动的进程。以官方的测试服务器为例：

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

配置后，在对话中直接让 LLM 使用即可：

使用 mcp_everything 工具计算 3 + 4

2.2 配置远程 MCP 服务器

远程 MCP 服务器通过 HTTP 协议提供服务。以 Sentry 的错误监控 MCP 为例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

配置完成后，需要通过命令行完成 OAuth 认证：

opencode mcp auth sentry

认证成功后，就可以在对话中查询 Sentry 的 issue 和项目数据了：

使用 sentry 工具查看项目中最新未解决的问题

2.3 MCP 服务器的管理技巧

当 MCP 服务器数量增多时，可以通过 tools 配置进行精细控制：

{
  "tools": {
    "my-mcp*": false        // 全局禁用所有 my-mcp 开头的工具
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true     // 仅在特定 agent 下启用
      }
    }
  }
}

MCP 工具名以服务器名作为前缀，因此禁用某个服务器的所有工具可以写成 "sentry_*": false。

需要注意的是，MCP 服务器会增加上下文消耗。某些工具（如 GitHub MCP）会产生大量 token，容易超出上下文限制，建议按需启用。

三、自定义命令：一键执行重复任务

自定义命令让你将复杂提示词封装成简单易记的 / 命令，极大提升日常开发效率。

3.1 创建你的第一个命令

在 .opencode/commands/ 目录下创建 Markdown 文件，文件名即为命令名：

---description: 运行测试并生成覆盖率报告
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整的测试套件，生成覆盖率报告，并显示所有失败的测试。
重点分析失败原因并提出修复建议。

使用方式是在 TUI 中输入：

/test

3.2 使用参数和动态内容

命令模板支持 $ARGUMENTS 和位置参数 $1、$2：

---description: 创建新的 React 组件---
创建一个名为 $1 的 TypeScript React 组件，放在 src/components/ 目录下。
包含完整的类型定义和基础结构。

执行：

/component UserProfile

还可以通过 ! 语法注入 shell 命令的输出：

---description: 分析最近的代码变更---
最近的 Git 提交：!`git log --oneline -10`

基于这些变更，检查是否有潜在问题或改进空间。

结合 @ 文件引用功能，可以创建强大的代码审查命令：

---description: 审查指定组件---
审查 @src/components/$1.tsx 的性能问题，检查不必要的重渲染和状态管理优化。

3.3 命令的 JSON 配置方式

除了 Markdown 文件，也可以在 opencode.jsonc 中通过 command 字段配置：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "analyze": {
      "template": "分析项目的依赖关系，检查是否有循环依赖或过期的包",
      "description": "分析项目依赖",
      "agent": "plan"
    }
  }
}

四、三者协同的实战场景

这三种扩展机制不是孤立的，它们可以互相配合形成强大的工作流。

场景：一键修复 Sentry 错误

通过 MCP 服务器拉取 Sentry issue 数据

自定义命令触发自动化分析流程

自定义工具执行数据库查询定位根因

---description: 修复 Sentry 错误---
使用 sentry 工具获取最新的未解决问题。
然后查看项目中的相关代码，分析错误原因。
如果需要数据库查询，使用 database 工具。
最后给出修复方案并实施。

五、总结

OpenCode 的扩展能力让它远不止是一个"编码助手"——通过自定义工具、MCP 服务器和自定义命令，你可以将 OpenCode 深度集成到你的开发工作流中。自定义工具适合封装项目特定的业务逻辑，MCP 服务器提供了丰富的第三方生态集成，而自定义命令则让重复性工作一键完成。

建议从自定义命令开始入手，快速感受效率提升；遇到需要第三方数据时探索 MCP 生态；最后用自定义工具封装团队特有的操作逻辑，逐步将 OpenCode 打造成你的"超级开发助手"。