OpenCode Native Tools MCP

一个独立的 MCP stdio Server，把 OpenCode 1.18.9 的公开内置工具带给 Codex、Claude Code 和其他 MCP Code CLI。

它不启动、不调用、也不依赖本机 opencode CLI。

工具

task、question、lsp、OpenCode UI ask、插件 hooks 和内部控制工具不包含在内，因为它们依赖 OpenCode 的交互界面、子代理、LSP 会话或插件运行时。

Related MCP server: codex-cli-mcp-tool

紧凑输出

read 默认只返回带行号的正文；grep 默认返回 文件:行号:内容。两者不会再把正文复制到 preview 或 display.text。读取被截断时，正文末尾会给出 startLine、endLine、totalLines 和 nextOffset；受字节上限影响而无法确认总行数时，totalLines=unknown。

需要机器可读元数据时传入 responseFormat: "detailed"。此时 structuredContent 只包含分页或匹配统计字段，不会重复正文。readMany 最多读取 8 个文件，默认每个文件 200 行，整批输出最多 100 KB；单个文件失败会作为该文件的结果返回，不会中断其他文件。

安装到 Codex

需要 Node.js 20 或更高版本。选择以下任一种方式；通常推荐 方式 A，它启动更快且不依赖每次执行时下载包。

方式 A：全局安装

npm install -g opencode-native-tools-mcp

在 Codex 配置文件中加入：

[mcp_servers.opencode_native_tools]
command = "opencode-native-tools"
args = []
startup_timeout_sec = 30.0

默认情况下，服务使用 MCP Client 启动它时的工作目录作为项目根目录。

方式 B：使用 npx，不做全局安装

不需要先执行 npm install -g。在 Codex 配置文件中加入：

[mcp_servers.opencode_native_tools]
command = "npx"
args = ["-y", "opencode-native-tools-mcp@latest"]
startup_timeout_sec = 30.0

安装 MCP 后，建议执行一次配置器，让 Codex 自动优先使用本服务进行读取和搜索：

opencode-native-tools apply
opencode-native-tools status

如果使用的是本节的 npx 方式，执行 npx -y opencode-native-tools-mcp@latest apply。apply 会保留已有 MCP 的 command 和 args，并更新全局 AGENTS.md 中的标记块。它不会把本 MCP 加入 direct_only_tool_namespaces：文件修改必须交给 Codex 原生的 write / edit / apply_patch，这样 Codex 才能显示文件修改 Diff。完成后重启 Codex 或新建 task。需要撤销自动规则时执行 opencode-native-tools unapply。

默认情况下，服务使用 MCP Client 启动它时的工作目录作为项目根目录。

如果需要固定操作某个项目，再额外添加：

[mcp_servers.opencode_native_tools.env]
OPENCODE_TOOLS_ROOT = "D:/path/to/your-project"

Windows 的全局 Codex 配置文件通常是：

C:\Users\<你的用户名>\.codex\config.toml

保存后重启 Codex Desktop，或新建一个 task，让 Codex 重新读取 MCP 配置。

验证是否接入成功

在终端执行：

codex mcp list

应该能看到：

opencode_native_tools  ...  enabled

然后在新的 Codex task 中输入：

使用 opencode_native_tools 的 glob 查找 package.json，再用 read 读取它。

Codex 应调用 read、glob、grep、write、edit、apply_patch、bash 等同名 MCP 工具。

项目根目录

OPENCODE_TOOLS_ROOT 用于固定该 MCP 默认操作的项目目录。未设置时，服务使用 MCP Client 启动时的工作目录；只有在全局配置需要固定到某个仓库时，才需要设置它。

如果不设置它，服务会使用 Codex 启动 MCP 进程时的工作目录。

权限与禁用工具

OpenCode 的 ask 是其自身 UI 的交互能力，通用 MCP Server 无法复刻。文件修改和 shell 命令的批准应由 Codex 在调用前负责。

推荐为有副作用的工具要求批准：

[mcp_servers.opencode_native_tools.tools.write]
approval_mode = "approve"

[mcp_servers.opencode_native_tools.tools.edit]
approval_mode = "approve"

[mcp_servers.opencode_native_tools.tools.apply_patch]
approval_mode = "approve"

[mcp_servers.opencode_native_tools.tools.bash]
approval_mode = "approve"

可以禁用不希望 Codex 使用的工具：

[mcp_servers.opencode_native_tools]
disabled_tools = ["bash", "webfetch", "websearch"]

或者只保留白名单中的工具：

[mcp_servers.opencode_native_tools]
enabled_tools = ["read", "glob", "grep", "write", "edit", "apply_patch"]

这些是 Codex 的 MCP 配置，只影响 Codex；其他 MCP Client 仍会看到服务公开的完整工具列表。

apply_patch 的目标路径位于 patchText 中。宿主应在调用前解析 *** Add File、*** Update File、*** Delete File 和 *** Move to，并按自身策略批准工作区外访问。结果中的 metadata.externalPaths 用于审计，不能替代调用前批准。

让 Codex 优先使用本 MCP

服务会在 MCP 初始化时声明对文件读取和搜索的工具偏好。文件修改使用 Codex 原生工具，以便 Codex 记录并显示文件 Diff。要让 Codex 在项目中更稳定地优先使用本 MCP，可以在目标仓库根目录放置 AGENTS.md。

仓库提供了可直接使用的模板：templates/AGENTS.md。它要求 Codex 使用 opencode_native_tools 进行读取和搜索，并使用 Codex 原生编辑工具修改文件，以保留 Codex 的 Diff 展示。

搜索与可选依赖

glob 和 grep 优先使用系统 PATH 中的 rg。找不到时，服务会下载兼容版本的 ripgrep 并写入自己的缓存；普通用户通常不需要手动安装 rg。离线或受限网络环境可以自行安装 ripgrep，或设置：

OPENCODE_TOOLS_RG_PATH=/path/to/rg

Windows 下服务会按 PATH 优先级查找 rg.exe，但会跳过 Codex Desktop WindowsApps 中不可由 MCP 启动的内置副本。其他候选和缓存副本会在服务首次使用时验证一次可执行性；成功路径会在进程内缓存，后续 glob 和 grep 不产生额外探测开销。

没有可用的 ripgrep 时，服务会下载并验证自己的缓存版本。受限网络环境可通过 OPENCODE_TOOLS_RG_PATH 指定允许启动的 rg.exe 绝对路径。

websearch 是可选工具。要启用它，在 MCP 的 env 中提供一个 provider 的 key：

[mcp_servers.opencode_native_tools.env]
EXA_API_KEY = "..."
# 或 PARALLEL_API_KEY = "..."

可通过 OPENCODE_WEBSEARCH_PROVIDER = "exa" 或 "parallel" 固定 provider。Parallel 还可设置 OPENCODE_TOOLS_MODEL_NAME。

OpenCode 兼容配置

服务会读取兼容的 OpenCode JSON / JSONC 配置数据，但不会加载 OpenCode runtime、插件或 hooks。支持以下配置来源：

• OPENCODE_CONFIG

• OPENCODE_CONFIG_CONTENT

• OPENCODE_CONFIG_DIR

• OPENCODE_DISABLE_PROJECT_CONFIG

兼容 shell、tool_output、formatter、skills 和 websearch runtime flags。Windows 默认按 pwsh、powershell、Git Bash、cmd 选择 shell；OPENCODE_TOOLS_SHELL 和 OPENCODE_GIT_BASH_PATH 可覆盖。

默认不会格式化文件。要在 write、edit、apply_patch 后启用 formatter，在项目的 opencode.json 或 opencode.jsonc 中设置：

{
  "formatter": true
}

兼容性边界

本实现以 OpenCode 1.18.9 为固定对照基线。以下差异是通用 MCP 协议限制或有意保留的独立实现选择：

• 宿主 Code CLI 负责批准；不提供 OpenCode UI ask。

• LSP diagnostics、watcher 和 OpenCode event bus 未迁移。

• 标准 MCP content / structuredContent 是对 OpenCode 内部 Tool result 的协议适配。

• apply_patch 会先计算全部变更，再原子提交；OpenCode 原实现为审批后按顺序应用。

• ripgrep、formatter、URL skills 和 shell 输出使用本服务的独立缓存，不与 OpenCode 全局缓存共享。