dsh-mcp-manager: Instructions file for Codex

AGENTS.md

DSH plugin: MCP server manager for DeepSeek Harness (web profile). Settings → MCP page for HTTP (OAuth PKCE + RFC 7591 dynamic client registration, or static Bearer token) and local stdio MCP servers, whose tools are registered as mcp__<name>__<rawName> native tools.

Layout

Plugin source is two files — keep it that way unless a refactor is explicitly requested (tests live under test/):

• lib/index.js — host half (Node.js): HTTP API on the DSH GUI webserver under /mcp-manager/api/*, OAuth flow (redirect receiver at /mcp-manager/callback/:id), both MCP transports, tool registration into ctx.tools, state persistence.
• lib/client.js — client half (browser): a window.__ModuleLoader__.load(...) factory using react.createElement (no JSX, no bundler). Registers the Settings → MCP tab via the settings.section slot. UI is bilingual (Simplified Chinese and English; follows DSH’s Settings → General → Language preference) — every user-visible string is resolved through t from the mcp locale namespace, never hardcoded.
• cordis.patch.yml — bundle patch that activates the plugin row (dsh.bundle.patch in package.json).
• test/*.test.js — node --test unit tests over the host half's exported helpers plus a stubbed-context apply() API smoke test (not shipped: files lists only lib/*).
• README.md / README.zh-CN.md — keep both in sync on behavior changes.

Architecture rules

• Two halves talk only through the same-origin JSON API /mcp-manager/api/*; the client never touches Node APIs and the host never renders UI.
• OAuth redirect origin is derived per-request from the Host header — never hardcode a host/port. Client registration is bound to the exact redirect URI and re-registers if the origin changes.
• Token state (~/.dsh/mcp-manager.json) contains secrets — never log tokens; treat the file as sensitive.
• Tool name convention mcp__<server>__<raw> with [^A-Za-z0-9_-] → _ normalization and a 64-char cap (sha256 suffix on overflow) — must match the built-in @deepseek-ai/dsh-mcp-client.
• Tool schemas must pass through sanitizeValue/convParams (registry accepts only a raw JSON-Schema subset; unsupported vocabulary degrades to unconstrained).
• stdio transport: child_process.spawn, newline-delimited JSON-RPC over stdin/stdout. Reconnect must reap the old child first; ctx.effect teardown kills all children on unload. args are quote-aware tokenized with no shell expansion. On Windows shell: true makes Node join command + args with bare spaces and add no quoting, so every token must pass through quoteWindowsToken (idempotent for already-quoted values) or cmd.exe truncates paths containing spaces.
• Loaded state is migrated once in apply() via migrateLoadedState: missing or duplicate server.id values are backfilled (live status and /servers/:id/* are id-keyed, so a missing id 404s every id-addressed API) and legacy [{ name, value }] env/header arrays are normalized to maps. Persist immediately when it reports a change.
• HTTP transport: streamable HTTP (JSON-RPC POST, Mcp-Session-Id header, SSE-or-JSON response fallback in parseRpc). A 401 triggers one refresh_token retry, then reconnect.
• Disable/enable is global per profile: disable unregisters tools + drops the connection but persists config and tokens; enable reconnects without re-auth.
• UI is bilingual: the mcp locale namespace holds zh and en dictionaries with the same key set — add new strings to both. Register them with ctx.effect(() => ctx.locale.register("mcp", { zh, en }), "dsh-mcp-manager: dictionaries"). The client injects locale and declares @deepseek-ai/dsh-client-locale in dsh.client.inject. Register settings.section with locale: "mcp": its component receives the standard t prop and passes it to children. Use a bound t for the slot label callback. DSH owns language selection (Settings → General → Language), browser fallback, persistence, and live updates. Do not add a plugin language selector, language state, or language API. GET /settings exposes only onDemandToolInjection; legacy language values in the plugin state file remain untouched and unused. Server-supplied diagnostics (MCP error text, tool descriptions) stay in their original language.