代码协作服务器

OpenCode MCP Server 是一个将 OpenCode 作为子代理暴露给 IDE 和 AI 客户端的 MCP 服务器,支持代码实现、文件操作、代码分析、多轮编码会话等功能。

  • by Traves-Theberge
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 Traves-Theberge/opencode-mcp

使用说明

OpenCode MCP服务器

MCP服务器,将OpenCode作为IDE和AI客户端的工具/子代理公开

概述

OpenCode MCP Server允许任何兼容MCP的客户端(Cursor、Windsurf、Claude Desktop、Claude Code、OpenCode、Antigravity、Zed等)将编码任务委托给OpenCode作为子代理。这实现了强大的多工具工作流程,您的主要AI助手可以调用OpenCode来:

  • 代码实现和重构
  • 文件操作和搜索
  • 代码分析和规划
  • 多圈编码会话
  • 代理委托(构建、规划、定制代理)
  • 模型和提供商管理
  • 技能发现和创造
  • 子MCP服务器管理

特性

  • 完整的OpenCode集成:通过MCP工具访问所有OpenCode功能
  • 21工具:简化了用于编码、配置、代理、技能和MCP管理的工具集
  • 混合配置持久性:配置更改会立即应用并持续到 opencode.json
  • 工具注释:符合MCP的注释,可更好地发现LLM
  • 双重运输:stdio(本地)和HTTP(远程),具有无状态/有状态模式
  • 类型安全:通过Zod v4验证完全支持TypeScript
  • 可操作错误:错误消息包括具体的解决建议
  • 请求超时:可配置的超时处理,并进行适当的清理
  • 结构化日志记录:通过环境变量调试、信息、警告、错误级别
  • 会话管理:创建和管理编码会话
  • 代理委托:将任务委托给专业代理(构建、规划、探索)
  • 技能系统:发现并创建可重复使用的技能定义
  • MCP管理:列出并启用/禁用MCP服务器

快速开始

安装

# Clone the repository
git clone https://github.com/Traves-Theberge/opencode-mcp.git
cd opencode-mcp

# Install dependencies and build
npm install
npm run build

先决条件

  1. 已安装OpenCode: 安装OpenCode
  2. OpenCode服务器正在运行:从以下内容开始 opencode serve 或TUI
  3. 已配置API密钥:在OpenCode中设置LLM提供者密钥
  4. 此MCP服务器已构建:运行 npm run build 在项目目录中

在IDE中配置

OpenCode MCP Server适用于所有主要的支持AI的IDE:

IDE 配置文件 安装指南
Codex CLI ~/.codex/config.toml 完整指南
Gemini CLI ~/.gemini/settings.json 完整指南
Roo代码 mcp_settings.json 或 .roo/mcp.json 完整指南
反重力 ~/.gemini/antigravity/mcp_config.json 完整指南
光标 ~/.cursor/mcp.json 完整指南
帆板运动 ~/.codeium/windsurf/mcp_config.json 完整指南
克劳德桌面版 ~/Library/Application Support/Claude/claude_desktop_config.json 完整指南
VS代码(副本) .vscode/mcp.json 完整指南
克莱恩 cline_mcp_settings.json 完整指南
Continue.dev .continue/mcpServers/ 完整指南
泽德 ~/.config/zed/settings.json 完整指南
开源代码 opencode.json 完整指南
MCP服务器助手 aider-mcp 命令 完整指南

快速配置(反重力)

增添 ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/dist/index.js"],
      "env": {
        "OPENCODE_SERVER_URL": "http://localhost:4096",
        "OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
      }
    }
  }
}

注: 替换 /path/to/opencode-mcp 使用克隆存储库的实际路径。

快速配置(光标)

增添 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/dist/index.js"],
      "env": {
        "OPENCODE_SERVER_URL": "http://localhost:4096",
        "OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
      }
    }
  }
}

快速配置(克劳德桌面)

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/dist/index.js"],
      "env": {
        "OPENCODE_SERVER_URL": "http://localhost:4096",
        "OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
      }
    }
  }
}

看 文档/设置指南/ 有关所有支持的IDE的完整设置说明。

可用工具(21)

执行(5)

工具 说明
opencode_run 通过OpenCode执行编码任务
opencode_session_create 创建新会话
opencode_session_prompt 向会话发送提示
opencode_session_list 列出所有会话
opencode_session_abort 中止正在运行的会话

文件(4)

工具 说明
opencode_file_read 从项目中读取文件
opencode_file_search 在文件中搜索文本
opencode_find_files 按名称/模式查找文件
opencode_find_symbols 查找工作空间符号

配置(5)

工具 说明
opencode_model_list 列出可用型号
opencode_model_configure 配置模型选项
opencode_provider_list 列出提供者
opencode_config_get 获取配置
opencode_config_update 更新配置

代理商(2)

工具 说明
opencode_agent_list 列出可用代理
opencode_agent_delegate 委派给代理人

技能(2)

工具 说明
opencode_skill_list 列出可用技能
opencode_skill_create 创造技能

MCP管理(2)

工具 说明
opencode_mcp_list 列出MCP服务器
opencode_mcp_enable 启用/禁用MCP服务器

工具配置(1)

工具 说明
opencode_tool_list 列出所有工具

用法示例

基本任务执行

Use opencode_run to implement a React hook for fetching data with loading and error states

与规划代理进行代码审查

Use opencode_agent_delegate to have the plan agent review the authentication module for security issues

文件搜索

Use opencode_file_search to find all uses of deprecated functions

模型配置

Use opencode_model_configure to set reasoningEffort to high for deep thinking tasks

创造技能

Use opencode_skill_create to create a skill for database migration patterns

配置文件

该项目包括各种AI编码代理的预配置文件:

根级别配置文件

文件 格式 使用人
AGENTS.md 通用 Codex、Cursor、Gemini CLI、Claude Code、Windsurf、Zed、Cline
CLAUDE.md 克劳德代码 克劳德代码
.cursorrules 纯文本 光标
.windsurfrules 纯文本 Windsurf
.clinerules/rules.md Markdown Cline
.continue/rules/opencode.md YAML+Markdown 继续开发
.github/copilot-instructions.md Markdown GitHub副本

配置/目录

configs/
├── agents/
│   ├── AGENTS.md      # Universal agent format
│   └── CLAUDE.md      # Claude Code specific
├── skills/
│   └── SKILL.md       # Agent Skills format (agentskills.io)
├── rules/
│   ├── cursor.md      # Cursor rules
│   ├── continue.md    # Continue rules (YAML frontmatter)
│   └── copilot-instructions.md
├── mcp/
│   └── templates.md   # MCP config templates
└── README.md          # Config documentation

代理技能格式(SKILL.md)

基于 agentskills.io 网站 规范:

---
name: skill-name
description: When to use this skill
---

# Instructions...

看 configs/README.md 有关安装说明。

运输方式

stdio(默认)

  • 最适合本地IDE集成
  • 单客户端连接
  • 无需配置

超文本传输协议

  • 最适合远程访问和多个客户端
  • 支持无状态和有状态会话
  • 使用环境变量进行配置:
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @opencode-mcp/server

端点:

端点 方法 描述
/health GET 健康检查
/api 获取 API文档
/mcp POST 无状态MCP请求
/mcp GET SSE流媒体(无状态)
/mcp/:sessionId POST 有状态的MCP请求
/mcp/:sessionId GET SSE流式传输(有状态)
/mcp/:sessionId DELETE 关闭有状态会话

模式:

  • 无状态 (默认):请求之间没有会话状态,更有利于扩展
  • 有状态的:通过sessionId维护会话状态,这是多回合上下文所必需的

环境变量

变量 默认值 描述
OPENCODE_SERVER_URL http://localhost:4096 OpenCode服务器URL
OPENCODE_AUTO_START true 自动启动OpenCode
OPENCODE_DEFAULT_MODEL - 默认型号
OPENCODE_TIMEOUT 120000 请求超时(毫秒)
OPENCODE_DEFAULT_PROJECT - 默认项目目录(未指定工作目录时使用)
OPENCODE_CONFIG_PATH 自动检测 用于配置持久性的opencode.json路径
OPENCODE_LOG_LEVEL info 日志级别(调试、信息、警告、错误、无)
OPENCODE_LOG_TIMESTAMP false 在日志中包含时间戳
MCP_TRANSPORT stdio 传输模式(stdio或http)
MCP_HTTP_PORT 3000 HTTP端口
MCP_CORS_ORIGINS * CORS起源(逗号分隔,生产中限制)

配置持久性

配置工具(opencode_model_configure, opencode_config_update)使用a 混合方法:

  1. API更新 -更改将立即应用于正在运行的OpenCode服务器
  2. 文件持久性 -更改已保存到 opencode.json 用于跨重启的持久性

配置路径检测

配置文件位置在此优先级中自动检测:

  1. OPENCODE_CONFIG_PATH 环境变量(显式覆盖)
  2. 项目本地: {workingDirectory}/.opencode/opencode.json
  3. 全球: ~/.config/opencode/opencode.json

更改与现有配置深度合并,保留其他设置。

项目目录检测

OpenCode MCP服务器使用此优先级来确定工作目录:

  1. 明确的 workingDirectory 参数 -传入工具调用
  2. OPENCODE_DEFAULT_PROJECT 环境变量 -在MCP配置中设置
  3. 自动检测 -搜索 .git, package.json,等从当前目录
  4. 后备方案 -MCP服务器进程的当前工作目录

推荐: 集 OPENCODE_DEFAULT_PROJECT 在MCP配置中,避免每次都指定目录:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/dist/index.js"],
      "env": {
        "OPENCODE_SERVER_URL": "http://localhost:4096",
        "OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
      }
    }
  }
}

错误处理

所有工具都以一致的格式返回错误,并提供可操作的建议:

Error: <operation> failed.

Details: <error message>

Suggestions:
  1. <actionable suggestion>
  2. <another suggestion>

看 错误处理指南 了解详情。

发展

# Clone and install
git clone https://github.com/opencode-mcp/server.git
cd server
npm install

# Run in dev mode
npm run dev

# Run tests
npm test

# Run linting
npm run lint

# Build
npm run build

安全

OpenCode MCP服务器的设计考虑了安全性:

  • stdio传输(默认):仅限本地访问,需要系统访问权限
  • 无凭据存储:由OpenCode管理的API密钥,而不是MCP服务器
  • 输入验证:所有输入均已Zod模式验证
  • CORS可配置:限制HTTP传输的来源
  • 请求限制:可配置的车身尺寸限制和超时

有关使用HTTP传输的生产部署,请参阅 安全指南.

文档

贡献

欢迎投稿!请阅读我们的 贡献指南 了解详情。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢