OpenCode MCP Agent

简体中文 | English

让你的主力 AI Agent 直接把任务派发给 OpenCode —— 用最强的模型做方案，用最经济的模型跑执行。

为什么需要这个工具？

在多 Agent 工作流中，你可能遇到这样的问题：

• 🧠 方案制定需要最强模型（GPT-5.5、Claude Opus 4.6），但这些模型价格昂贵
• ⚡ 代码执行消耗大量 Token（读文件、写代码、跑测试），用顶级模型很浪费
• 🔄 Agent 切换需要手动复制文件、粘贴上下文，流程割裂

OpenCode MCP Agent 解决了这些问题：

主力 Agent（GPT-5.5 / Opus 4.6）
  → 制定方案、设计架构、拆分任务
  → 通过 MCP 直接派发给 OpenCode
      → OpenCode 使用便宜模型（DeepSeek / Mimo）执行
      → 自动返回结果、状态和权限请求

一句话总结：用最强的大脑做决策，用最经济的双手做执行，中间零摩擦。

工作原理

MCP 客户端（如 Codex、Claude Desktop）
  → OpenCode MCP Agent（MCP 服务器）
    → 受管的 opencode serve（本地 runtime）
      → OpenCode agent、session、model 和 tools

• runtime 绑定 127.0.0.1 随机端口，凭证仅存于进程内存
• 不需要 OpenCode Desktop
• 支持任意 MCP 客户端

已验证的环境

组件	版本
操作系统	Windows 11 25H2
Node.js	v24.15.0
主力 Agent	Codex（GPT-5.5）
执行 Agent	OpenCode（DeepSeek v4 Pro）

这是作者的第一个 MCP 工具项目。如果你在其他环境中遇到问题，欢迎 提交 Issue 报告 bug 或提出改进建议，我会持续优化。

当前状态

核心工作流已完成，并经过自动化测试和真实 runtime 测试验证：

• 受管的本地 OpenCode runtime
• 显式指定工作空间和模型
• 异步任务与持久化任务记录
• 会话创建与复用
• 进度、运行中工具和阻塞工具上报
• OpenCode 权限发现与回复
• 快速两阶段取消
• 模型和会话发现

1.0 版本提供首个稳定的面向任务的 MCP 接口。

环境要求

• Node.js 18 或更新版本
• 已安装并配置 OpenCode CLI
• 支持 stdio 服务器的 MCP 客户端

确认 OpenCode 可用：

opencode --version

如果 OpenCode 不在 PATH 中，请设置 OPENCODE_BIN 指向其可执行文件路径。

快速开始

从 npm 安装

npm install -g opencode-mcp-agent

然后在 MCP 客户端中注册：

{
  "mcpServers": {
    "opencode-control": {
      "command": "opencode-mcp-agent"
    }
  }
}

从源码安装

git clone https://github.com/arctan303/opencode-mcp-agent.git
cd opencode-mcp-agent
npm run check

在 Codex 中注册：

codex mcp add opencode-control -- node /path/to/opencode-mcp-agent/server.mjs

通用 stdio MCP 配置：

{
  "mcpServers": {
    "opencode-control": {
      "command": "node",
      "args": ["/absolute/path/to/opencode-mcp-agent/server.mjs"]
    }
  }
}

更改配置后需重启 MCP 客户端。

典型使用场景

场景 1：方案制定 + 代码执行分离

1. 在 Codex 中使用 GPT-5.5 制定项目方案和设计文档
2. GPT-5.5 通过 opencode_task_start 直接将实现任务派发给 OpenCode
3. OpenCode 使用 DeepSeek v4 Pro 等经济模型执行代码编写
4. 主力 Agent 通过 opencode_task_status 跟踪进度
5. 完成后通过 opencode_task_result 收集结果

场景 2：批量任务并行

1. 主力 Agent 拆分大任务为多个子任务
2. 依次调用 opencode_task_start（wait: false）派发
3. 并行查询各任务状态和结果

推荐的任务流程

1. 调用 opencode_model_list 查看已配置的模型。
2. 调用 opencode_task_start，显式指定 workspace，通常使用 wait: false。
3. 轮询 opencode_task_status。
4. 如果任务进入 waiting_permission 状态，调用 opencode_permission_list 查看请求，然后调用 opencode_permission_reply 回复。
5. 使用 opencode_task_result 读取最终结果。

任务参数示例：

{
  "workspace": "C:\\projects\\example",
  "model": "provider/model",
  "prompt": "分析这个项目并报告性能风险。不要修改文件。",
  "wait": false,
  "timeoutMs": 600000
}

timeoutMs 是 OpenCode 模型和工具请求的最大生存时间。即使 wait 为 false 也会生效，且独立于 MCP 客户端的超时设置。

MCP 工具

工具	用途
opencode_task_start	创建或继续 OpenCode 任务
opencode_task_list	查找已持久化的桥接任务
opencode_task_status	刷新任务、工具、会话和权限状态
opencode_task_result	读取完整的任务结果
opencode_task_cancel	请求取消，不阻塞等待确认
opencode_session_list	列出 OpenCode 会话
opencode_session_messages	读取紧凑或原始会话消息
opencode_model_list	列出 OpenCode 可用模型
opencode_permission_list	列出真实的待处理权限
opencode_permission_reply	以 once、always 或 reject 回复
opencode_runtime_status	检查受管 runtime 状态
opencode_runtime_start	启动受管 runtime
opencode_runtime_stop	停止受管 runtime

长时间运行的调用应使用 wait: false。MCP 请求是并发处理的，因此在另一个请求等待时仍可查询状态和回复权限。

取消是两阶段的：opencode_task_cancel 首先返回 cancelRequested: true；在 OpenCode 确认会话中止后，任务变为 cancelled。

配置

环境变量	用途
OPENCODE_BIN	OpenCode 可执行文件路径
OPENCODE_CONFIG	OpenCode 配置文件路径
OPENCODE_BRIDGE_STATE	任务状态 JSON 文件路径
OPENCODE_BRIDGE_DEBUG_TOOLS=1	暴露 legacy/debug MCP 工具

默认情况下，任务状态存储在仓库外的用户本地应用状态目录中。

安全模型

• 受管服务器仅监听 127.0.0.1。
• 每次 runtime 启动时生成随机端口和随机 Basic Authentication 凭证。
• runtime 凭证仅存在于桥接器进程内存中。
• 桥接器不存储模型供应商凭证。
• OpenCode 权限被转发，而非绕过。
• always 授权应在检查权限类型和模式后才批准。

安全问题报告请参阅 SECURITY.md。

开发

npm run check

check 命令运行语法检查和 Node.js 测试套件。

构建 npm 发布产物：

npm run build

构建会运行所有检查，并将 tarball、SHA256SUMS 和 manifest.json 写入 dist/。

项目文档：

• 项目背景 / BACKGROUND.md
• 架构设计 / ARCHITECTURE.md
• 功能进度 / ROADMAP.md
• 贡献指南 / CONTRIBUTING.md
• 更新日志 / CHANGELOG.md

许可证

MIT