sky-unicorn / dsh-mcp-server-manager

dsh-mcp-server-manager

English | 中文

Settings-driven MCP servers as one installable deepseek-harness plugin. One package, two halves:

• Host half — the mcp-manager plugin: registers the mcp settings namespace, validates its resolved format, reconciles its servers record into live mcp-client connections (each server mounts as an independent cordis fiber), and serves the mcpConfig Typert Remote (describe / mutate / import).
• Browser half — a polished "MCP servers" card in Web UI → Settings → Plugins: format status, transport-labelled server rows, one-click Claude Code + Codex import, manual add (stdio or Streamable HTTP), and remove. Staged edits land on one save under revision fencing; env / headers values are masked on read and never restated on write.

The card styles exclusively with the harness theme's --dsw-alias-* semantic tokens (CSS Modules, no color literals, no theme selectors), so it follows the tool's appearance setting — light, dark, or follow-system — automatically, exactly like the built-in cards.

Install

Requirements: a dsh CLI or a harness source checkout (the peers resolve from the harness deployment).

# from a local checkout (this repo)
dsh plugin --profile web add /path/to/dsh-mcp-server-manager

# or prebuilt from a tarball
npm pack && dsh plugin --profile web add ./dsh-mcp-server-manager-0.1.0.tgz

dsh plugin add initializes the profile if needed (@deepseek-ai/dsh-base first, then this bundle) and appends the bundle's cordis.patch.yml layer. Verify and start:

dsh --profile web --dump-config   # shows the "# == dsh-mcp-server-manager" layer
dsh web                           # open http://127.0.0.1:3080

From a harness source checkout, prefix with pnpm: pnpm dsh plugin --profile web add <path>. Git-based installs pull source, not build output — this repo's prepare script builds lib/ on install; allow it once in the profile's pnpm-workspace.yaml (allowBuilds: { dsh-mcp-server-manager: true }) when pnpm asks. Tarball/npm installs arrive prebuilt and need no build authorization.

In the Web UI: Settings → Plugins → MCP servers. Add a server, e.g. stdio npx -y @modelcontextprotocol/server-everything, save, and the server's tools appear to the agent as mcp__<name>__<tool>. Removing and saving disconnects it. The record itself lives in the mcp: section of the profile's settings.yaml, so a hand edit of that file reaches the same reconcile loop.

One-click import

Choose Import Claude Code & Codex in the card. Discovery runs on the Host and reads only the current Host user's known configuration locations and the nearest files above the running project/composition roots:

• Claude Code: ~/.claude.json, the nearest .mcp.json, and matching project-local entries in ~/.claude.json; precedence is local → project → user.
• Codex: $CODEX_HOME/config.toml (or ~/.codex/config.toml) and the nearest project .codex/config.toml; project entries override global entries with the same name.

The importer supports stdio and Streamable HTTP, resolves documented environment references in the Host process, fills this plugin's defaults, and validates every converted entry. The current DSH settings record is authoritative: an external entry whose normalized name is already configured is skipped, even when its content differs. Exact normalized definitions are also skipped when their names differ. Name collisions only between newly imported external entries use deterministic -2, -3, … suffixes; external names outside DSH's name contract are normalized.

Unsupported transports/authentication, disabled entries, missing environment variables, and malformed files are skipped and reported without returning configuration values. Claude Code SSE/WebSocket and dynamic auth helpers, Codex OAuth/remote-executor settings, and client-specific tool/startup policy cannot be represented by the installed DSH mcp-client; Codex policy options are reported and ignored while the compatible connection is imported.

Imported environment/header values never cross into the browser. They are resolved by the Host and persisted through the mcp settings owner, so protect settings.yaml like any other credential-bearing deployment file.

Format validation

Every describe response includes a value-free audit shown at the top of the card. The Host schema and commit validator check the DSH server-name contract, required command, positive timeout, HTTP(S) URL without embedded credentials, HTTP header names, control characters, and hidden surrounding whitespace. Errors reject the write; whitespace warnings remain usable and are called out by server and field path. The current stdio and Streamable HTTP record shapes match the target checkout's public mcp-client schema.

Develop

npm install     # also runs prepare -> build
npm run build   # tsc (host, NodeNext ESM) + esbuild (browser bundle)
npm test        # vitest unit tests (host logic + card controller)

Layout:

src/index.ts        browser package's Cordis stub
host/src/index.ts   host apply: settings namespace + reconcile + Remote mount
host/src/manager.ts McpServerManager: ctx.plugin(mcp-client) per server, fiber dispose on change
host/src/schema.ts  Schemastery schema: servers record (stdio | streamable-http)
host/src/remote.ts  masked describe + fenced path mutate + Host-only import
host/src/importers.ts Claude Code/Codex discovery, conversion, and de-duplication
host/src/validation.ts value-free resolved-format audit and commit validator
host/src/types.ts   Remote wire types
src/client/         browser half: card registration, locale, stores, React card, CSS Modules
build.mjs           standalone build (no harness toolchain needed)
cordis.patch.yml    the one insert row the bundle layer contributes

Type-checking resolves the @deepseek-ai/* peers through tsconfig.json / tsconfig.client.json paths pointing at a sibling ../deepseek-harness checkout's built lib/ — adjust the paths if your harness lives elsewhere. The harness RC packages on npm currently publish unsatisfiable peer graphs, which is why they are peers only (satisfied by the deployment), never devDependencies; unit tests stub the few value imports.

Known limitations

• No in-place editing of an existing server's fields. A saved server can be removed and re-added, but its stored (masked) fields cannot be edited in place — editing around the masked read would restate credentials the card never sees. Remove + re-add instead.
• Reconnect policy follows the installed mcp-client version. The definition record intentionally omits reconnect; whatever default the deployment's mcp-client schema carries applies.
• Import is intentionally loss-aware. Source-only options that DSH cannot express are never guessed; each is skipped or explicitly reported as ignored.
• Headless profiles get the host half only. Without a browser surface the write path is a hand-edited settings.yaml; the reconcile loop is the same.