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, static Bearer token, or no auth) 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; every 401 also parses WWW-Authenticate for resource_metadata and caches that URL on server.oauth.
• OAuth discovery is ordered, never a single guess: cached/401-advertised RFC 9728 protected-resource metadata (path-inserted, then bare) → its authorization_servers[0] → RFC 8414 metadata at the path-inserted well-known URL (wellKnownUrl), then openid-configuration, then the naive ${issuer}/.well-known/oauth-authorization-server; guessing ${origin}/oauth/* is the last resort and returns source: 'fallback'. issuerOf must stay pure (no I/O) because the editor compares issuers across a config edit to decide whether cached OAuth state survives; server.oauth.authorizationServer / server.oauth.resourceMetadataUrl are the only non-secret discovery caches, and discoverAndPersist writes them only when they changed.
• OAuth client credentials: clientId (manual, non-secret — skips RFC 7591 entirely and is never re-registered), clientSecretEnv (an environment-variable name only; the value is read per request and sent as client_secret — client_secret_post is the only supported method), and scope (sent as the scope authorization parameter). All three are OAuth-only: switching to static/none/stdio deletes them, and a changed clientId/clientSecretEnv/issuer drops server.oauth. Validation lives in parseOauthFields (pure) + applyOauthFields; sameServerConfig and both *View helpers must carry the fields or workspace edits silently no-op.
• HTTP auth modes are oauth | static | none, normalized in exactly one place (normalizeAuthMode). none is exempt from the credential gate (hasToken → true) and accessToken must return '' for it so a stale attached OAuth token is never sent; switching to none in the editor also drops server.oauth.
• Disable/enable is global per profile: disable unregisters tools + drops the connection but persists config and tokens; enable reconnects without re-auth.
• Diagnostics are an in-memory Map<serverId, entry[]> ring buffer (20 entries/server, ≤500 chars each) written by recordAttempt and read by GET /mcp-manager/api/servers/:id/logs. Redaction happens on write, never on render: query-string code/state/client_secret/access_token/refresh_token are stripped, Authorization values are never stored, and Bearer … is masked. Logs are never persisted (a log file would be a new secret-at-rest surface) — the durable record stays ctx.logger. Workspace logs survive a rescan because their ids are deterministic (workspaceServerId); deleting a server clears its log.
• 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.