dsh-mcp — MCP server management plugin (MCP Server Manager for DSH)

Provides MCP (Model Context Protocol) server management capabilities for the DSH Web GUI:

• Server list: Add / edit / delete MCP servers on the "Settings → MCP" page, supporting stdio (child process), Streamable HTTP and SSE (server-sent events) transports, and you can also add multiple servers from JSON; configuration is stored in ~/.dsh/dsh-mcp.json (0600, atomic writes).

• Enable / disable: Each server has a global switch; disabling it disconnects the server and its tools are no longer registered.

• Session-level connection selection: The session bar (title row) adds an "MCP" selector where you can choose which MCP servers to connect for this session (all enabled servers are selected by default; you can also explicitly choose "Connect to none"); servers that are not checked are not used in this session; the "Session connections" tab on the "Settings → MCP" page can also be adjusted, and changes take effect immediately.

• Tool registration: Tools from connected servers are registered as session-scoped tools under the name mcp__<服务器id>__<工具名> (via agent.ctx.tools.register), visible only to the selected session; invocations are forwarded through the MCP protocol.

• Connection management: On disconnect, automatically reconnects with exponential backoff (up to 10 times); supports hot-syncing the tool list via notifications/tools/list_changed; the GUI provides one-click connection testing; clicking a server's "tool count" lists the tools that server provides.

• OAuth browser authorization: For HTTP/SSE servers that require Bearer authorization (401 challenge), click "Authorize" to open the authorization panel and complete login in an external browser (RFC 9728/8414 discovery + dynamic client registration + PKCE); the token is persisted to ~/.dsh/dsh-mcp-oauth/<id>.json (0600) and then automatically attached, and is automatically refreshed on reconnect after disconnection; the callback listens on fixed port 3085 (if occupied, falls back to a random port and automatically clears invalid registrations before re-registering); after authorization completes, the server automatically reconnects, and deleting the server also clears its token.

• Session bar MCP selector: The drop-down panel of the "MCP n" button in the title row adaptively expands its direction — no matter how short the session name or how narrow the window, the panel is fully visible and never clipped by the window edge.

• Agent tool: mcp_list lists configured servers and their running status; the system prompt automatically announces this plugin to the model.

Architecture

• Host side (Host, src/index.ts): a cordis plugin with name = 'mcp', mounting the /api/dsh-mcp/* routes (loopback fence), the mcp_list tool, and the system prompt section, and listening for agent/created / agent/disposed to maintain per-session scoped tool registrations.

• Engine (src/engine.ts + src/engine/connection.ts + src/engine/bridge.ts): one connection per server (@modelcontextprotocol/sdk), sharing connections and registering per session.

• Storage (src/store.ts): server CRUD + session selection, pure file I/O, no cordis dependency.

• Client (src/client/*): mounted on official slots — the settings.section in the "Settings" sidebar (id mcp, with two tabs: Servers / Sessions) plus the MCP selector in conversation.session.header.actions of the session bar; colors use the --dsw-alias-* theme variables (automatically adapting to light/dark themes).

Related MCP server: MCP Proxy Server

Installation

# 在 dsh web profile（默认 web）中安装（link 方式，随源码热更新）
dsh plugin --profile web add "link:<本包绝对路径>"

After installation, restart dsh (dsh --profile web) for it to take effect: the host loads the Node side, and the Web GUI loads the browser side (/plugins/dsh-mcp/client.js).

Handing off installation to someone else

Just hand over the entire dsh-mcp folder (no node_modules needed, but keep the lib/ build output — it contains the host-side lib/index.js and the browser-side lib/client.js, which is what dsh actually loads). The other person's steps:

# 1. 放到任意位置（如 ~/plugins/dsh-mcp）
# 2. 安装依赖（需 pnpm；lock 文件保证版本一致）
cd dsh-mcp
pnpm install

# 3. 若 lib/ 缺失（例如通过 git 交付且 .gitignore 忽略了它），先构建
pnpm run build

# 4. 可选：验证（34 个测试，含真实 stdio/SSE MCP 服务器与 OAuth 端到端）
pnpm run typecheck && pnpm test

# 5. 安装到 dsh web profile（link 方式，源码改动即热更新）
dsh plugin --profile web add "link:C:/path/to/dsh-mcp"

# 6. 重启 dsh 生效
dsh --profile web

Windows notes:

• If pnpm install reports ERR_PNPM_UNEXPECTED_STORE (pnpm store path conflict), write store-dir=你的 pnpm store 路径 (e.g. C:/Users/<你>/AppData/Local/pnpm/store/v11) into the profile's ~/.dsh/profiles/web/.npmrc.

• If dsh plugin add fails to install, you can install manually: run pnpm add --store-dir <同上的 store 路径> link:C:/path/to/dsh-mcp under ~/.dsh/profiles/web, add dsh-mcp to the profile's dsh.profile.bundles list, and restart.

• Runtime requirement: Node ≥ 22.19 (package.json engines).

Usage

1. Open "Settings" and select "MCP" in the sidebar to enter the server management page.

2. "Servers" tab: add a server (via the form or "Add from JSON"; for stdio, fill in the launch command/arguments/environment variables, or for Streamable HTTP / SSE fill in the URL/request headers), click "Test" to verify connectivity; click "Tool count" to list the tools; when editing, the form automatically pre-fills the saved arguments/environment variables, and you can also switch to "View JSON" to see the full configuration and copy it.

3. In the session bar title row, click the "MCP" selector and check the servers to connect for this session (or click "All enabled" / "Connect to none"); it takes effect immediately — the model in that session can then call the corresponding mcp__… tools; the "Settings → MCP → Session connections" tab can also be adjusted.

4. When a server requires Bearer authorization: edit the server, turn on "Enable OAuth browser authorization" in the HTTP/SSE form, save, then click "Authorize" in the list — the browser opens the authorization page, and after completion it automatically connects (the token is stored in ~/.dsh/dsh-mcp-oauth/<id>.json); "Clear authorization" allows re-authorizing.

5. In a session, you can directly ask the agent "What MCP servers are there?" — it will answer using mcp_list.

Security model

• Configuration (stdio environment variables, HTTP headers such as Authorization) is stored in plaintext in the local private file ~/.dsh/dsh-mcp.json — the same trust model as dsh-ssh password storage. The list API does not return secret values; only the "edit details" API (loopback-only) returns the full configuration for form pre-filling and "View JSON", to avoid accidentally clearing saved arguments and environment variables when editing.

• The stdio transport launches user-configured commands with the host process's privileges; MCP tool output is returned as-is and may contain sensitive information.

• OAuth tokens (access/refresh token and PKCE verifier) are stored in plaintext in ~/.dsh/dsh-mcp-oauth/<serverId>.json (0600) — the same trust model as the configuration file; the authorization callback listens on a 127.0.0.1 loopback port, accessible only from this machine. The callback listens on fixed port 3085 (falls back to a random port when occupied), ensuring that after a dsh restart the registered client still matches and invalid redirect_uri does not occur; if a port change is detected, the old registration is automatically cleared and re-registered.

• All /api/dsh-mcp/* routes are loopback-only (to prevent LAN exposure).

Development

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm test            # vitest（store / bridge / engine 端到端）
pnpm run build       # tsc 声明 + tsdown（lib/index.js + lib/client.js）

Engine end-to-end tests actually launch a stdio MCP server subprocess to verify connection, discovery, scoped registration, and invocation forwarding.

Known limitations

• MCP tools that require taskSupport: required are not supported (the bridge layer rejects them and reports an error).

• Image-type tool results are degraded to text placeholders (not wired into attachment storage).

• Renaming a server does not affect tool names (tool names are namespaced by id); deleting a server disconnects it and removes it from all session selections.

Version history

• 0.2.0: Improved OAuth browser authorization — authorization panel (completed in an external browser, auto-detected), callback fixed on port 3085, automatic re-registration on port change (fixes invalid redirect_uri), deleting a server also clears its token, the Authorize button is always visible (allowing re-authorization), automatic reconnect after authorization completes (verifier snapshot is immune to stale connection overwrites; a 401 on the connection no longer automatically starts the authorization flow and disrupts the user's workflow), the session bar selector drop-down adapts to prevent clipping, and mcp_list output is aligned with its schema.

• 0.1.0: Base version — server list add/delete/edit, enable/disable, testing, session-level connection selection, per-session scoped tool registration, reconnect on disconnect, hot-syncing of the tool list, SSE transport support, bulk add from JSON, edit pre-fill / view JSON.