bingshuo/guanghu
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
guanghu/docs/adr/0120-stable-appimage-mcp-server-path-with-opencode-registration.md
Guanghu Domestic Migration 9b41d51231
Some checks are pending
Auto-update PR branches / Update open PR branches (push) Waiting to run
Details
CI / Frontend Static Quality Checks (push) Waiting to run
Details
CI / Frontend Tests & Coverage (push) Waiting to run
Details
CI / Rust Tests & Quality Checks (push) Waiting to run
Details
CI / Linux build verification (push) Waiting to run
Details
Deploy docs / Build VitePress site (push) Waiting to run
Details
Deploy docs / Deploy to GitHub Pages (push) Blocked by required conditions
Details
Release (Alpha) / Compute alpha version (push) Waiting to run
Details
Release (Alpha) / Build release artifacts (push) Blocked by required conditions
Details
Release (Alpha) / GitHub Release (alpha) (push) Blocked by required conditions
Details
Release (Alpha) / Update docs and release pages (push) Blocked by required conditions
Details
chore: import sanitized domestic snapshot for REPO-004 
Source snapshot: 514ab1975951d94342ea38e64101d5a0f1c51c77
2026-07-17 15:55:28 +08:00

2.1 KiB
Raw 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.