bingshuo/guanghu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
guanghu/docs/adr/0120-stable-appimage-mcp-server-path-with-opencode-registration.md
冰朔 8739805f99
Some checks failed
Auto-update PR branches / Update open PR branches (push) Has been cancelled
Details
CI / Frontend Static Quality Checks (push) Has been cancelled
Details
CI / Frontend Tests & Coverage (push) Has been cancelled
Details
CI / Rust Tests & Quality Checks (push) Has been cancelled
Details
CI / Linux build verification (push) Has been cancelled
Details
Release (Alpha) / Compute alpha version (push) Has been cancelled
Details
Release (Alpha) / Build release artifacts (push) Has been cancelled
Details
Release (Alpha) / GitHub Release (alpha) (push) Has been cancelled
Details
Release (Alpha) / Update docs and release pages (push) Has been cancelled
Details
Deploy docs / Build VitePress site (push) Has been cancelled
Details
Deploy docs / Deploy to GitHub Pages (push) Has been cancelled
Details
光湖开源源码快照 · Tolaria AGPL 分叉基线 · 独立更新链
2026-07-05 17:45:16 +08:00

2.1 KiB
Raw Permalink Blame History

0120. Stable AppImage MCP Server Path With OpenCode Registration

Status: active

Date: 2026-05-14

Context

Domenico Lupinetti's PR #600 identified two gaps in durable external MCP setup:

  • Linux AppImage launches expose bundled resources through a mount path that can change between app starts, so external clients can keep a stale mcp-server/index.js path.
  • OpenCode uses ~/.config/opencode/opencode.json with a different MCP schema from Claude Code, Cursor, Gemini, and generic mcpServers clients.

ADR-0119 made durable MCP registration vault-neutral, so PR #600 could not be merged directly: its registered entries still carried VAULT_PATH. The stable-path and OpenCode work is still valid, but it has to preserve the current mounted-workspace resolution model.

Decision

On Linux AppImage startup, Tolaria extracts the bundled mcp-server/ directory to ~/.local/share/tolaria/mcp-server/. The extracted directory is version-gated by a .tolaria-version marker. Extraction runs on first launch or after an app version change, uses a staging directory plus rename, and uses a process lock so concurrent app launches do not write the stable directory at the same time.

Durable external registration prefers the stable extracted server directory when it is ready. Otherwise it falls back to the packaged resource resolver.

OpenCode is added to durable MCP registration and removal. Tolaria writes an OpenCode-specific entry under the top-level mcp key using:

  • type: "local"
  • command: [node, index.js]
  • enabled: true
  • environment.WS_UI_PORT = "9711"

OpenCode registration remains vault-neutral. It does not write VAULT_PATH; the Node MCP server resolves active mounted workspaces from Tolaria state per ADR-0119.

Consequences

Linux AppImage users can register external MCP clients once and keep a valid index.js path across restarts and updates.

OpenCode participates in the same connect, disconnect, and status flow as Claude Code, Cursor, Gemini, and generic MCP clients while preserving its own config schema.

The stable path fixes the packaging lifecycle without reintroducing static vault pinning.