@geohar/opencode-mcp-combiner

中文文档
0.23.1发布于 2026/11/10MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 4222

OpenCode plugin: run the mcp-combiner MCP aggregator via sharedserver and register its endpoint with OpenCode.

原始使用文档
文档目录12 节
  1. What it does
  2. Requirements
  3. Install
  4. Options
  5. Inbound authentication
  6. Combiner command resolution
  7. servers.json auto-probe
  8. Host-owned mode
  9. Environment variables
  10. Relationship to opencode-sharedserver
  11. Development
  12. License

@geohar/opencode-mcp-combiner

An OpenCode plugin that makes the mcp-combiner MCP aggregator available to OpenCode: it starts the combiner (supervised by sharedserver) and registers its HTTP MCP endpoint with OpenCode.

It is the OpenCode counterpart of the Claude Code plugin mcp-combiner, and shares the same combiner and the same sharedserver instance — so OpenCode, Claude Code, and Neovim can all talk to one refcounted combiner process.

What it does

The plugin has two independent responsibilities (mirroring the Claude plugin, which uses session hooks + a static .mcp.json):

  1. Run the combiner — drives sharedserver:

    sharedserver use <name> --pid <opencode-pid> --grace-period <g> \
        -- <combiner> --mcp --config <servers.json> --port <port>
    

    sharedserver refcounts by PID with a grace period, so the combiner is shared across clients and outlives any single one. The plugin runs unuse on OpenCode exit.

  2. Register the endpoint — via the OpenCode config hook it injects a remote MCP server into your config:

    { "mcp": { "mcp-combiner": { "type": "remote", "url": "http://127.0.0.1:9741/mcp", "enabled": true } } }
    

    (OpenCode has no static .mcp.json, so registration is programmatic.)

The two halves are independent: registration is unconditional — OpenCode tracks connection state (McpStatus) and reconnects if the endpoint is briefly absent while the combiner binds its port. After startup the plugin polls client.mcp.status() and toasts connected / failed accordingly.

Requirements

  • sharedserver on PATH (or $SHAREDSERVER_BIN) — cargo install sharedserver.
  • mcp-combiner available as a command (uv tool install mcp-combiner, a console script on PATH), or a checkout runnable via uv run. Requires combiner ≥ 0.8.0 (the --mcp serve flag; version-gated automatically).
  • A combiner servers.json (see auto-probe locations below).

Install

Add it to ~/.config/opencode/config.json under plugin, tuple form [spec, options]:

{
  "plugin": [
    ["@geohar/opencode-mcp-combiner@latest", {
      "port": 9741,
      "config": "~/.config/mcp-combiner/servers.json",
      "gracePeriod": "30m"
    }]
  ]
}

Bare-string form ("@geohar/opencode-mcp-combiner@latest") also works and uses all defaults.

Options

OptionDefaultDescription
port9741HTTP port the combiner serves on.
host127.0.0.1HTTP host the combiner binds.
config(auto-probed)Path to the combiner's servers.json.
command(auto-resolved)Override the combiner command.
args[]Extra combiner args (before the serve args).
checkout—Combiner checkout for uv run --project <checkout> python -m mcp_combiner.
namemcp-combinersharedserver instance name.
gracePeriod30msharedserver grace period (30m, 1h, …).
logFile~/.local/state/mcp-combiner/mcp-combiner.logCapture the combiner's stdout/stderr (sharedserver --log-file); "none" disables.
pyLogFile~/.local/state/mcp-combiner/mcp-combiner-py.logThe combiner's own --log-file (fastmcp/OAuth/httpx detail); "none" disables.
logLevelinfoThe combiner's --log-level.
binary(auto-resolved)Path to the sharedserver binary.
lockdir—Override SHAREDSERVER_LOCKDIR.
mcpNamemcp-combinerKey under OpenCode's mcp config.
urlhttp://127.0.0.1:<port>/mcpExplicit MCP URL to register.
registertrueRegister the endpoint with OpenCode.
managetrueStart the combiner. false → register only (something else runs it).
notifytrueShow TUI toasts for attach/health outcomes.

Inbound authentication

If the combiner is locked down with an inbound bearer token (see the combiner README), set MCP_COMBINER_AUTH_TOKEN in this plugin's environment. When present, the registered mcp entry carries Authorization: Bearer <token> on every request (and the same var is passed to the combiner when this plugin starts it). Unset → no header, and an unauthenticated combiner returns 200 as before. The token is read from the env only — never written to OpenCode's config.

Combiner command resolution

In priority order: command option → $OPENCODE_MCP_COMBINER_COMMAND (+$OPENCODE_MCP_COMBINER_ARGS) → mcp-combiner on PATH → uv run --project <checkout> python -m mcp_combiner (when checkout / $OPENCODE_MCP_COMBINER_CHECKOUT is set).

servers.json auto-probe

config option → $OPENCODE_MCP_COMBINER_CONFIG → ~/.cache/secrets/<user>.mcpservers.json → ~/.config/mcp-combiner/servers.json → ~/.config/mcp/servers.json.

Host-owned mode

If $MCP_COMPANION_COMBINER_URL is set, an editor/host (e.g. Neovim) already owns and refcounts the combiner. The plugin then only registers that URL and never starts or stops the process — the same early-exit as the Claude Code mcp-combiner plugin. Equivalent to setting manage: false with an explicit url.

Environment variables

VariableEffect
MCP_COMPANION_COMBINER_URLHost owns the combiner → register only, don't launch.
OPENCODE_MCP_COMBINER_COMMAND / _ARGSOverride the combiner invocation.
OPENCODE_MCP_COMBINER_CHECKOUTCheckout path for uv run.
OPENCODE_MCP_COMBINER_CONFIGservers.json path.
OPENCODE_MCP_COMBINER_PORTPort the combiner serves on. Default 9741.
OPENCODE_MCP_COMBINER_NAMEsharedserver instance name. Default mcp-combiner.
OPENCODE_MCP_COMBINER_GRACEsharedserver grace period. Default 30m.
OPENCODE_MCP_COMBINER_LOGStdout/stderr capture path (default ~/.local/state/mcp-combiner/mcp-combiner.log; none disables).
OPENCODE_MCP_COMBINER_PYLOGThe combiner's own --log-file (default …/mcp-combiner-py.log; none disables).
OPENCODE_MCP_COMBINER_LOG_LEVELThe combiner's --log-level. Default info.
SHAREDSERVER_BINPath to the sharedserver binary.
SHAREDSERVER_LOCKDIRsharedserver lock directory.

Plugin options take precedence over the environment. These mirror the Claude plugin's CLAUDE_MCP_COMBINER_* set, so running both clients means one namespace per client rather than options in one place and env vars in the other.

If mcp-combiner is on PATH but older than 0.8.0, the plugin logs and toasts a warning, then falls back to a pinned release fetched with uvx — it will not silently use a stale binary, nor silently route around one you installed deliberately.

Relationship to opencode-sharedserver

@geohar/opencode-sharedserver is a generic process supervisor plugin. This plugin is combiner-specific: it knows the correct serve invocation (--mcp --config --port, version-gated) and — unlike the generic one — registers the MCP endpoint with OpenCode. It vendors the same sharedserver attach/detach logic rather than depending on the generic plugin, so either can be used independently.

Development

bun install        # or npm install
npm run typecheck
npm run build      # emits dist/ (not committed; built on publish)

License

MIT © George Harker

版本与发布记录

@geohar/opencode-mcp-combiner 共发布 50 个版本,首次发布于 2026/07/18;过去 12 个月发布了 50 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.23.1latest2026/11/106 天前
0.23.02026/11/106 天前
0.22.02026/11/097 天前
0.21.42026/11/0610 天前
0.21.32026/11/0511 天前
0.21.22026/11/0412 天前

其他发布通道:dev → 0.21.2-dev.1。

关于 @geohar/opencode-mcp-combiner 的常见问题

@geohar/opencode-mcp-combiner 是什么?

OpenCode plugin: run the mcp-combiner MCP aggregator via sharedserver and register its endpoint with OpenCode.

如何安装 @geohar/opencode-mcp-combiner?

在项目目录运行 npm install @geohar/opencode-mcp-combiner,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@opencode-ai/plugin(>=1.3.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geohar/opencode-mcp-combiner 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geohar/opencode-mcp-combiner 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geohar/opencode-mcp-combiner 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geohar/opencode-mcp-combiner 可以商用吗?

@geohar/opencode-mcp-combiner 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geohar/opencode-mcp-combiner 的下载量有多少?

根据 npm 官方下载统计,@geohar/opencode-mcp-combiner 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,222 次,日均约 141 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geohar/opencode-mcp-combiner 还在维护吗?

最新版本 0.23.1 发布于 2026/11/10(6 天前);至今共发布 50 个版本,其中过去 12 个月发布了 50 个;首次发布于 2026/07/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。