convez.ai
MCP ServerAutomaçãoAvançado
arctan303

OpenCode MCP Agent

arctan303/opencode-mcp-agent

Delega tarefas de código para OpenCode com controle total via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que integra OpenCode como um sub-agente gerenciado, permitindo delegar tarefas de desenvolvimento com rastreamento de progresso, reutilização de sessões e seleção de modelos. Otimiza custo separando decisões (modelos premium) da execução (modelos econômicos).

Instalação

$npx convez-ai arctan303/opencode-mcp-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 5 meses
Versão
v1.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Separar planejamento arquitetural de implementação com modelos diferentes
  • Executar múltiplas tarefas de desenvolvimento em paralelo com tracking
  • Otimizar custos usando modelos premium para decisão e econômicos para execução
  • Integrar OpenCode em workflows multi-agente sem copiar contexto manualmente

Veredito

Solução madura e bem testada para orquestração de agentes de IA com foco em otimização de custo. Ideal para quem trabalha com múltiplos agentes e precisa delegar execução mantendo controle fino sobre progresso e permissões.

README

A tradução para o português deste README ainda está na fila.

OpenCode MCP Agent

CI License: MIT Node.js Version npm version

简体中文 | 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.jsv24.15.0
主力 AgentCodex(GPT-5.5)
执行 AgentOpenCode(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_BINOpenCode 可执行文件路径
OPENCODE_CONFIGOpenCode 配置文件路径
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

Ver o original no GitHub

Bom para

Relacionados