opencode-mcp-agent

v1.1.0

Published

20 days ago

Let your primary AI agent dispatch tasks to OpenCode — best model for planning, cost-effective model for execution.

0High
0Medium
0Low

arctan303

mcp model-context-protocol opencode sub-agent agent

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：方案制定 + 代码执行分离

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

场景 2：批量任务并行

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

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/。

项目文档：

许可证

MIT