bingshuo/guanghu
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
guanghu/docs/adr/0119-vault-neutral-mcp-registration-with-mounted-workspace-guidance.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.3 KiB
Raw Permalink Blame History

0119. Vault-Neutral MCP Registration With Mounted Workspace Guidance

Status: active

Date: 2026-05-14

Context

Tolaria used to register external MCP clients with a durable VAULT_PATH environment variable. That made the copied config easy to inspect, but it also meant Claude Code, Cursor, Gemini CLI, and generic MCP clients stayed pinned to whichever vault was active at setup time.

Domenico Lupinetti's dynamic-vault MCP proposal in PR #603 pointed in the right direction: MCP clients should follow Tolaria's current workspace state instead of requiring users to reconnect after each vault change. The current app model has also moved from one selected vault toward mounted workspaces, so the MCP server needs to operate on every active mounted vault and load local agent guidance from each vault.

Decision

Durable external MCP registration is vault-neutral. Tolaria still writes an explicit stdio MCP entry, but that entry contains only the Node command, mcp-server/index.js, and WS_UI_PORT=9711. It no longer writes VAULT_PATH.

The Node MCP entrypoints resolve vaults at tool-call time:

  • Explicit VAULT_PATH and VAULT_PATHS environment variables continue to win for app-owned bridge launches and legacy/manual launches.
  • When those env vars are absent, the MCP server reads Tolaria's vaults.json.
  • active_vault is returned first.
  • Every workspace in vaults[] is included unless it is explicitly marked mounted: false.
  • Paths are deduplicated and blank paths are ignored.

Vault context now checks each active mounted workspace root for AGENTS.md and returns those instructions with the vault summary. The MCP server also exposes list_vaults so agents can discover the active workspace set and whether each vault has root guidance.

We are not adding a session-local switch_vault tool. A switch tool would create a second source of truth inside the MCP process, while Tolaria already owns mounted workspace state.

Consequences

External MCP config survives vault switches and mounted-workspace changes without reconnecting.

Agents can work across all active mounted vaults and receive the per-vault AGENTS.md instructions needed to respect local rules.

Manual users can still override the resolved workspace set with VAULT_PATH or VAULT_PATHS when they intentionally want a static or scripted MCP session.