dsh-mcp-panel 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # dsh-mcp-panel
 
-**Read-only runtime management panel for the official DeepSeek Harness MCP client — see every MCP server's status, tools, errors, and reconnect counts, without touching your config.**
+**The MCP management console for the official DeepSeek Harness MCP client — add, edit, remove, and trial-call MCP servers from a settings page, with honest status, health diagnostics, and safe, reversible profile writes.**
 
 [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
 
@@ -11,52 +11,83 @@
 [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
 [![deepseek-harness](https://img.shields.io/badge/runtime-deepseek--harness-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)
 
-> 🔭 **Observability-first.** [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) keeps its connection state private — logs only. This plugin shows everything it *can* observe (config, tool registry, loader state) and says **"unknown"** for what it cannot, instead of guessing. It also proposes the minimal upstream seam that would make status real: see the [upstream proposal](docs/upstream-proposal.md).
+## Architecture: official client = bridge, this plugin = console
 
-## Compatibility
+[`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) is the **only bridge**: one plugin instance per MCP server, configured as a hand-written `cordis.yml` row, connecting the transport, syncing tools, and registering `mcp__<server>__<tool>` names. This plugin never replaces it — it is the **experience layer on top**:
 
-- **Runtime**: DeepSeek Harness ≥ `0.1.0-rc.5` (peer dependencies pin the `0.1.0-rc.6` package line).
-- **Latest release**: v0.3.0 (2026-08-15) — full gate green on the TypeScript 7 / Vitest 4 / jsdom 30 toolchain, 109 tests.
-- **Last verified**: 2026-08-14 against a source checkout of deepseek-harness (workspace packages at `0.1.0-rc.5`, mainline `7b9644f`) — headless `/mcp` end-to-end plus a live web profile; evidence in [docs/research-notes.zh.md](docs/research-notes.zh.md). Re-verified the same day against mainline `47f9438` with the `mcp/status` seam branch (`feat/mcp-client-status-observability-seam`): a real `server-everything` row renders `status: connected (source: upstream-event)` through the packed plugin, plus the launcher-faithful compat flow; record in [docs/optimization-plan-v2.zh.md](docs/optimization-plan-v2.zh.md).
+```
+                    ┌────────────────────────────────────────────┐
+ profile            │  cordis.yml / cordis.patch.yml             │
+ composition        │   - id: mcp-github                          │
+ (one row per       │     name: '@deepseek-ai/dsh-mcp-client'     │
+  server, hand-     │     config: { serverName, transport, … }    │
+  written)          │   - id: mcp-panel                           │
+                    │     name: dsh-mcp-panel   ◄── this plugin   │
+                    └───────────────┬────────────────────────────┘
+                                    │
+        ┌───────────────────────────┴───────────────────────────┐
+        │                                                        │
+   ┌────▼──────────────┐        ┌───────────────────────────┐    │
+   │ @deepseek-ai/dsh- │        │ dsh-mcp-panel (console)   │    │
+   │ mcp-client        │        │                           │    │
+   │ • transport       │        │ • /mcp command            │    │
+   │ • tool sync       │        │ • Settings → Plugins →    │    │
+   │ • mcp__* tools    │◄──────►│   MCP tab: CRUD, trial    │    │
+   │ • mcp/status seam │ status │ • health diagnostics      │    │
+   └───────────────────┘        │ • probes, capabilities    │    │
+                                └───────────────────────────┘    │
+```
+
+The console **reads** the client through its shipped `mcp/status` observability seam (event + `mcpStatus` query service), the tool registry, and the loader; it **writes** only the profile's patch layer — append-only, approval-gated, always backed up. Transport, OAuth, and protocol stay untouched.
+
+## Console vs. hand-written cordis.yml
+
+| | Hand-written cordis.yml | dsh-mcp-panel console |
+|---|---|---|
+| Add a server | Edit YAML, mind indent/quoting | Form → patch fragment → **copy** or **write** (approval + auto backup) |
+| Edit a server | Edit YAML, restart/hot-reload | Form pre-filled from the live row; unchanged secrets keep their raw values host-side |
+| Remove a server | Delete the row | `set disabled: true` operation (the patch vocabulary has no remove) — re-enableable anytime |
+| See status | Read logs | Badges + reconnects + last error, live from the `mcp/status` seam |
+| Try a tool | Ask the model to call it | Trial console → official `ctx.tools.execute()` pipeline (permission & approval stay in force) |
+| Diagnose failures | Grep logs | `/mcp <server> health` with derived self-heal suggestions |
+| Mistakes | Manual revert | Every write is append-only and leaves a timestamped backup |
+
+The console's output IS `cordis.patch.yml` vocabulary — the same lines you would write by hand, generated, previewed, and applied safely.
 
 ## What you get
 
-| Surface | What it shows |
+| Surface | What it does |
 |---|---|
-| **`/mcp` command** | transport, target, tool count, connection status, last error, reconnect count — model-readable, session-log reconstructable, five output languages (`outputLanguage: en\|zh\|es\|pt\|hi`) |
-| **Settings → Plugins → MCP tab** | the same snapshot read-only, with status badges, expandable tool lists, sanitized errors, probe results |
-| **At a glance** | summary counts above the cards, a server search box, and expand-all / collapse-all buttons |
-| **Panel probe button** | one-click connectivity probe of one streamable-http server from the tab; results stay panel-only |
-| **Passive probes** | optional background reachability badges per server, kept separate from connection status |
-| **Auto refresh** | the host suggests a refresh interval (`refreshIntervalMs`); the tab polls and pauses while hidden |
-| **`/mcp <server> disable\|enable`** | the exact `cordis.patch.yml` line to apply — a *suggestion*, never a write |
-| **`mcp_probe` tool** | one-shot Streamable HTTP connectivity probe as a background job; results are **panel-only** |
+| **`/mcp` command** | one row per server: transport, target, tool count, connection status (from the upstream seam; `unknown` when unobserved), last error, reconnect count — model-readable, session-log reconstructable, five output languages |
+| **`/mcp <server> tools`** | model-visible `mcp__*` tool names + descriptions |
+| **`/mcp <server> health`** | derived self-heal suggestions (ENOENT → missing dependency, ECONNREFUSED, timeouts, 401/403/404, DNS, rate limit, reconnect exhaustion…); exit code / stderr tail honestly labeled *pending upstream support* until the client exposes them |
+| **`/mcp <server> call <tool> [json]`** | trial-call through the **official tool pipeline** — pre-execute permission policy, approval (routed through the command's agent), guards, post-execute all apply |
+| **`/mcp <server> disable\|enable`** | the exact `set` patch line, as before |
+| **Settings → Plugins → MCP tab** | status cards with badges, diagnostics, probes, plus the three consoles below |
+| **Server CRUD** | add/edit/remove forms → `insert`/`set`/`set disabled` fragments → clipboard copy or approval-gated write with automatic backups (`cordis.patch.yml.bak-<ts>`, newest `backupCount` kept) |
+| **Tool trial console** | server → `mcp__*` tool → JSON args → canonical JSON result + rendered content; capped by `trialMaxResultChars`; panel-only, never model context |
+| **Capabilities board** | Resources / Prompts availability, feature-detected; both read *pending upstream support* today (the official client bridges tools only) |
+| **Probes** | one-click / passive Streamable HTTP connectivity probes (panel-only results) |
 
 ## Quick start
 
 ```sh
 # git channel (builds via the package's prepare script)
-dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.3.0
+dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.4.0
 # npm channel (published tarball, no build approval needed)
-dsh plugin --profile web add dsh-mcp-panel@0.3.0
+dsh plugin --profile web add dsh-mcp-panel@0.4.0
 ```
 
-Then restart (or let the web surface hot-reload its `cordis.patch.yml`) and:
+Then restart (or let the web surface hot-reload `cordis.patch.yml`) and open **Settings → Plugins → MCP**, or run:
 
 ```text
 /mcp
 /mcp everything tools
-/mcp everything disable
-```
-
-```text
-MCP servers (1):
-- everything [mcp-everything] stdio node …/server-everything/dist/index.js
-  | 13 tools | enabled | status: unknown (source: derived) | reconnects: — | last error: —
+/mcp everything health
+/mcp everything call echo '{"message": "hi"}'
 ```
 
-Manual install: put `dsh-mcp-panel` into the profile's `node_modules` (or the shared
-`$DSH_HOME/profiles/node_modules` fallback) and add the row to `cordis.patch.yml`:
+Manual install: put `dsh-mcp-panel` into the profile's `node_modules` (or the shared `$DSH_HOME/profiles/node_modules` fallback) and add the row to `cordis.patch.yml`:
 
 ```yaml
 - insert:
@@ -64,7 +95,6 @@ Manual install: put `dsh-mcp-panel` into the profile's `node_modules` (or the sh
       name: dsh-mcp-panel
       config:
         probeEnabled: true
-        probeTimeoutMs: 10000
 ```
 
 ### Uninstall
@@ -75,67 +105,48 @@ Manual install: put `dsh-mcp-panel` into the profile's `node_modules` (or the sh
 
 ## Honest by contract
 
-- **Read-only.** No configuration file is ever written. `disable`/`enable` prints a suggestion you apply yourself.
-- **No fake status.** Connection fields without upstream data read `unknown` / `—`, with `statusSource: derived`.
-- **Sanitized display.** URL query credentials, userinfo passwords, header values, bearer tokens, and JWTs are redacted before rendering; configured `headers` never enter any snapshot.
-- **Panel-only results.** Probe details live in the settings tab, never in model context; `/mcp` output is the model-readable surface and is fully reconstructable from the session log.
-- **No mcp-client changes.** Transport, OAuth, and protocol stay untouched — the observability gap is covered by the [upstream proposal](docs/upstream-proposal.md), which this plugin already consumes (typed `mcp/status` event + `mcpStatus` query service, feature-detected at runtime).
+- **The bridge stays the bridge.** No transport, OAuth, or protocol changes; one mcp-client row per server, exactly as hand-written.
+- **No fake status.** Connection fields without upstream observations read `unknown` / `—` with `statusSource: 'derived'`; exit codes / stderr tails are never invented.
+- **Sanitized display.** URL query credentials, userinfo passwords, header values, bearer tokens, and JWTs are redacted before rendering; configured `headers` never enter any snapshot; env/header **values** never leave the host (the editor sees keys only).
+- **Writes are append-only, approval-gated, and backed up.** The console never rewrites `cordis.patch.yml`: it appends generated operations. When an approval service exists and the caller's session has a live agent inside an open turn, the write asks `ctx.approval` (only `allowed-once` proceeds); otherwise the explicit interactive confirmation is the approval channel. `writeEnabled: false` is a hard kill switch.
+- **No prompt injection.** The panel registers **no prompt sections**; its only model-facing text is the two tool/command descriptions, in the official client's minimal style.
 
-## Configuration
+## Config
 
-| Field | Default | Description |
+| Key | Default | Description |
 |---|---|---|
-| `probeEnabled` | `true` | Register the `mcp_probe` tool (needs `ctx.jobs` in the composition) |
-| `probeTimeoutMs` | `10000` | Per-probe timeout |
-| `maxProbes` | `10` | Cap on probe records shown in the panel |
-| `refreshIntervalMs` | `0` | Suggested panel refresh interval in ms (`0` = on demand only) |
-| `outputLanguage` | `en` | Output language of the `/mcp` command (`en` \| `zh` \| `es` \| `pt` \| `hi`) |
-| `passiveProbeEnabled` | `false` | Periodically probe streamable-http servers in the background |
-| `passiveProbeIntervalMs` | `60000` | Passive probe interval in milliseconds |
-
-## Permissions & data
-
-- **Reads**: loader entries, the tool registry (`mcp__<server>__` names), and — when upstream ships it — `mcp/status` events.
-- **Writes**: none. No configuration file is ever modified.
-- **Network**: only the one-shot `mcp_probe` (and the optional passive probe) POSTs one MCP `initialize` request to endpoints you configured; configured headers are used for the request and are never displayed or logged.
-- No telemetry, no external services, no background work beyond the optional probe timers.
-
-## Troubleshooting
-
-- Row not visible? Run `dsh web --dump-config` and check that the `mcp-panel` insert landed with a unique id.
-- Panel shows `status: unknown (source: derived)` — expected until the upstream seam lands; see [docs/upstream-proposal.md](docs/upstream-proposal.md).
-- Panel looks stale? Set `refreshIntervalMs` to a positive value (e.g. `5000`) in the `mcp-panel` config row to poll automatically.
-- Boot log shows a FAILED `mcp-panel` fiber — the package must resolve from the profile (bare `name: dsh-mcp-panel` resolves via the profile's `node_modules` or the shared fallback).
-- Rollback: remove the row (see Uninstall).
-
-## Security
-
-Found a security issue? Open a GitHub issue **without** pasting secrets, keys, or tokens — redact everything first. This plugin holds the credentials of your configured MCP servers only in memory for probe requests; they never reach logs or snapshots.
-
-## How it works
-
-- **Host half** — a `mcpPanel` Typert Remote service assembles the snapshot from three read-only sources: loader rows (`@deepseek-ai/dsh-mcp-client` entries), `ctx.tools.schemas()` grouped by the `mcp__<server>__` namespace, and upstream `mcp/status` observations. The hand-written `./typert` manifest registers `mcpPanel/status` with the gateway; `zod` is bundled, so the host bundle is self-contained.
-- **Browser half** — a `dsh.client` bundle (served at `/plugins/dsh-mcp-panel/client.js`) mounts the same descriptor via `ctx.remote.$mount` and registers a read-only `settings.plugins.tab` entry (`id: mcp`). The presenter is a pure function; styles are scoped and token-driven.
-- **The `/mcp` command** goes through the standard command registry — every line lands in `command/run` + `command/done` session events.
+| `probeEnabled` | `true` | register the `mcp_probe` background-job tool (panel-only results) |
+| `probeTimeoutMs` | `10000` | per-probe timeout in ms |
+| `maxProbes` | `10` | probe records shown in the panel |
+| `refreshIntervalMs` | `0` | suggested panel refresh in ms; `0` = on demand |
+| `outputLanguage` | `en` | `/mcp` output language: `en\|zh\|es\|pt\|hi` |
+| `passiveProbeEnabled` | `false` | periodically probe streamable-http servers |
+| `passiveProbeIntervalMs` | `60000` | passive probe interval in ms |
+| `trialEnabled` | `true` | tool trial console (settings tab + `/mcp call`) |
+| `trialTimeoutMs` | `120000` | panel-side deadline per trial call |
+| `trialMaxResultChars` | `60000` | cap on the trial result payload |
+| `writeEnabled` | `true` | kill switch: `false` rejects every profile write (copy still works) |
+| `backupCount` | `5` | `cordis.patch.yml` backups retained per write |
+
+## Resources & Prompts
+
+The official client documents *"Tools are the only bridged MCP capability"* — Resources and Prompts are deferred. The console feature-detects a proposed upstream catalog seam and will show read-only lists the day it ships; until then the capabilities board marks both **pending upstream support** (see the harness `docs/upstream-proposal.md` addendum for the follow-up proposals).
 
 ## Development
 
 ```sh
-pnpm install
-pnpm run typecheck    # local gate: resolves the harness checkout's fresh type faces via tsconfig paths
-pnpm run typecheck:ci # npm gate: resolves the published 0.1.0-rc.6 type faces (what CI runs)
-pnpm test             # 109 tests: sanitizer extremes, grouping, aggregation tolerance, command output (5 languages), probe gating, client wiring, presenter (badges, summary, filter)
-pnpm run build        # tsc declarations → lib/types; tsdown → lib/index.js + lib/typert.host.js + lib/client.js
-pnpm run verify:self-contained
-pnpm run verify:artifacts
-pnpm pack
+pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build && pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm pack
 ```
 
-Release: `node scripts/release.mjs <x.y.z>` bumps the version, stamps the changelog, re-runs the gate, commits and tags; pushing the tag publishes npm + the GitHub Release automatically (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+- `src/patch.ts` — validation, keep-semantics merge, YAML fragment rendering (pure).
+- `src/write.ts` — backup + append + retention (the only file-write module).
+- `src/trial.ts` — official-pipeline trial calls via `ctx.tools.execute()`.
+- `src/diagnostics.ts` — error-pattern → suggestion mapping (pure).
+- `src/client/` — the settings console (server editor, trial console, diagnostics).
+- `scripts/verify-headless.mjs` boots the real web profile and prints exact `/mcp` output.
 
-Verification against a real harness checkout:
-`node --import tsx/esm scripts/verify-headless.mjs` boots the full web profile in process (ephemeral port) and prints the exact `/mcp`, `/mcp <server> tools`, and `/mcp <server> disable` output.
+Releases: `node scripts/release.mjs <x.y.z>` runs the full gate, commits, and tags `v<x.y.z>` locally (never pushes).
 
 ## License
 
-[Apache License 2.0](LICENSE) © 2026 dsh-mcp-panel contributors
+Apache-2.0 — see [LICENSE](LICENSE).

package/README.pt.md

@@ -1,141 +1,80 @@
 # dsh-mcp-panel
 
-**Painel de gerenciamento em tempo de execução, somente leitura, para o cliente MCP oficial do DeepSeek Harness: veja status, ferramentas, erros e contadores de reconexão de cada servidor MCP sem tocar na sua configuração.**
+**Console de gerenciamento MCP para o cliente MCP oficial do DeepSeek Harness: adicione, edite, remova e teste servidores MCP numa página de configurações, com status honesto, diagnósticos de saúde e gravações de perfil seguras e reversíveis.**
 
 [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/dsh-mcp-panel)](https://www.npmjs.com/package/dsh-mcp-panel)
-[![downloads](https://img.shields.io/npm/dm/dsh-mcp-panel)](https://www.npmjs.com/package/dsh-mcp-panel)
 [![CI](https://github.com/PerryLink/dsh-mcp-panel/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-mcp-panel/actions/workflows/ci.yml)
 [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
-[![deepseek-harness](https://img.shields.io/badge/runtime-deepseek--harness-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)
 
-> 🔭 **Observabilidade em primeiro lugar.** [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) mantém seu estado de conexão privado — apenas logs. Este plugin mostra tudo o que *consegue* observar (configuração, registro de ferramentas, estado do Loader) e diz **"unknown"** para o que não consegue, em vez de adivinhar. Ele também propõe a costura mínima que tornaria o status real: veja a [proposta upstream](docs/upstream-proposal.md).
+## Arquitetura: o cliente oficial é a ponte; este plugin é o console
 
-## Compatibilidade
+[`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) é a **única ponte**: uma instância por servidor MCP, configurada como linha escrita à mão no `cordis.yml`, que conecta o transporte, sincroniza ferramentas e registra os nomes `mcp__<servidor>__<ferramenta>`. Este plugin nunca a substitui: é a **camada de experiência** por cima:
 
-- **Runtime**: DeepSeek Harness ≥ `0.1.0-rc.5` (as peerDependencies fixam a linha `0.1.0-rc.6`).
-- **Última versão**: v0.3.0 (2026-08-15) — porta completa em verde com a cadeia TypeScript 7 / Vitest 4 / jsdom 30, 109 testes.
-- **Última verificação**: 2026-08-14 contra um checkout do código-fonte do deepseek-harness (pacotes do workspace em `0.1.0-rc.5`, mainline `7b9644f`) — `/mcp` headless de ponta a ponta mais um perfil web ao vivo; evidências em [docs/research-notes.zh.md](docs/research-notes.zh.md). Reverificado no mesmo dia contra mainline `47f9438` com o ramo da costura `mcp/status` (`feat/mcp-client-status-observability-seam`): uma linha real de `server-everything` mostra `status: connected (source: upstream-event)` através do plugin empacotado, além do fluxo de compatibilidade fiel ao lançador; registro em [docs/optimization-plan-v2.zh.md](docs/optimization-plan-v2.zh.md).
-
-## O que você ganha
-
-| Superfície | O que mostra |
-|---|---|
-| **Comando `/mcp`** | transporte, alvo, contagem de ferramentas, status de conexão, último erro, contador de reconexões — legível pelo modelo e reconstruível pelo log, cinco idiomas de saída (`outputLanguage: en\|zh\|es\|pt\|hi`) |
-| **Configurações → Plugins → aba MCP** | o mesmo snapshot somente leitura, com selos de status, listas expansíveis de ferramentas, erros sanitizados e resultados de sondas |
-| **De relance** | contagens de resumo acima dos cartões, um campo de busca de servidores e botões de expandir/recolher tudo |
-| **Botão de sonda do painel** | sonda de conectividade em um clique para um servidor streamable-http a partir da aba; os resultados continuam somente do painel |
-| **Sondas passivas** | selos de alcançabilidade opcionais em segundo plano por servidor, separados do status de conexão |
-| **Atualização automática** | o host sugere um intervalo de atualização (`refreshIntervalMs`); a aba consulta e pausa enquanto oculta |
-| **`/mcp <server> disable\|enable`** | a linha exata de `cordis.patch.yml` a aplicar — uma *sugestão*, nunca uma escrita |
-| **Ferramenta `mcp_probe`** | sonda de conectividade de uso único para Streamable HTTP como tarefa em segundo plano; resultados são **somente do painel** |
-
-## Início rápido
-
-```sh
-# canal git (compila pelo script prepare do pacote)
-dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.3.0
-# canal npm (tarball publicado, sem aprovação de compilação)
-dsh plugin --profile web add dsh-mcp-panel@0.3.0
 ```
-
-Reinicie (ou deixe a superfície web recarregar seu `cordis.patch.yml`) e execute:
-
-```text
-/mcp
-/mcp everything tools
-/mcp everything disable
-```
-
-```text
-MCP servers (1):
-- everything [mcp-everything] stdio node …/server-everything/dist/index.js
-  | 13 tools | enabled | status: unknown (source: derived) | reconnects: — | last error: —
+ profile/composição            dsh-mcp-client (ponte)       dsh-mcp-panel (console)
+ - id: mcp-github              • transporte                 • comando /mcp
+   name: '@deepseek-ai/…'      • sincronização de tools     • Configurações → Plugins →
+   config: { serverName, … }   • ferramentas mcp__*           MCP: CRUD, banco de testes,
+ - id: mcp-panel               • seam mcp/status ◄─status─►  diagnósticos, sondas
+   name: dsh-mcp-panel
 ```
 
-Instalação manual: coloque `dsh-mcp-panel` no `node_modules` do perfil (ou no
-respaldo compartilhado `$DSH_HOME/profiles/node_modules`) e adicione a linha a `cordis.patch.yml`:
-
-```yaml
-- insert:
-    - id: mcp-panel
-      name: dsh-mcp-panel
-      config:
-        probeEnabled: true
-        probeTimeoutMs: 10000
-```
+O console **lê** pelo seam `mcp/status` (evento + serviço `mcpStatus`), pelo registro de ferramentas e pelo loader; **escreve** apenas na camada de patches do perfil: somente anexa, com aprovação e backup automático. Transporte, OAuth e protocolo permanecem intocados.
 
-### Desinstalação
+## Console vs. cordis.yml escrito à mão
 
-1. Remova a linha `mcp-panel` de `cordis.patch.yml` (a superfície web a recarrega em quente; outras superfícies reiniciam).
-2. Apague o pacote do `node_modules` do perfil (ou do respaldo compartilhado `profiles/node_modules`).
-3. Confirme com `dsh web --dump-config` que nenhuma linha `mcp-panel` restou.
-
-## Honestidade por contrato
-
-- **Somente leitura.** Nenhum arquivo de configuração é gravado. `disable`/`enable` imprime uma sugestão que você aplica.
-- **Sem status falso.** Campos de conexão sem dados upstream mostram `unknown` / `—`, com `statusSource: derived`.
-- **Exibição sanitizada.** Credenciais em query strings, senhas userinfo, valores de cabeçalhos, tokens bearer e JWTs são removidos antes da renderização; os `headers` configurados nunca entram em nenhum snapshot.
-- **Resultados somente do painel.** Os detalhes das sondas ficam na aba de configurações, nunca no contexto do modelo; `/mcp` é a superfície legível pelo modelo e é totalmente reconstruível a partir do log da sessão.
-- **Sem mudanças no mcp-client.** Transporte, OAuth e protocolo permanecem intactos — a lacuna de observabilidade é coberta pela [proposta upstream](docs/upstream-proposal.md), que este plugin já consome (evento tipado `mcp/status` + serviço de consulta `mcpStatus`, detectados em tempo de execução).
-
-## Configuração
-
-| Campo | Padrão | Descrição |
+| | cordis.yml à mão | Console dsh-mcp-panel |
 |---|---|---|
-| `probeEnabled` | `true` | Registra a ferramenta `mcp_probe` (requer `ctx.jobs` na composição) |
-| `probeTimeoutMs` | `10000` | Tempo limite por sonda |
-| `maxProbes` | `10` | Limite de registros de sonda exibidos no painel |
-| `refreshIntervalMs` | `0` | Intervalo de atualização sugerido para o painel em ms (`0` = somente sob demanda) |
-| `outputLanguage` | `en` | Idioma de saída do comando `/mcp` (`en` \| `zh` \| `es` \| `pt` \| `hi`) |
-| `passiveProbeEnabled` | `false` | Sondear periodicamente servidores streamable-http em segundo plano |
-| `passiveProbeIntervalMs` | `60000` | Intervalo da sonda passiva em milissegundos |
-
-## Permissões e dados
+| Adicionar servidor | Editar YAML | Formulário → fragmento de patch → **copiar** ou **gravar** (aprovação + backup) |
+| Editar servidor | Editar YAML e reiniciar | Formulário pré-preenchido; segredos inalterados preservam o valor no host |
+| Remover servidor | Apagar a linha | Operação `set disabled: true` (o vocabulário de patches não tem remove); re-habilitável |
+| Ver status | Ler logs | Selos + reconexões + último erro, ao vivo do `mcp/status` |
+| Testar uma ferramenta | Pedir ao modelo | Banco de testes → pipeline oficial `ctx.tools.execute()` (permissões e aprovação em vigor) |
+| Diagnosticar | grep de logs | `/mcp <servidor> health` com sugestões derivadas |
 
-- **Lê**: linhas do Loader, o registro de ferramentas (nomes `mcp__<server>__`) e, quando o upstream implementar, eventos `mcp/status`.
-- **Escreve**: nada. Nenhum arquivo de configuração é modificado.
-- **Rede**: apenas a sonda de uso único `mcp_probe` (e a sonda passiva opcional) envia uma requisição MCP `initialize` para os endpoints que você configurou; os cabeçalhos configurados são usados na requisição e nunca são exibidos nem registrados.
-- Sem telemetria, sem serviços externos, sem trabalho em segundo plano além dos temporizadores de sonda opcionais.
+## O que você ganha
 
-## Solução de problemas
+- **`/mcp`**: uma linha por servidor — transporte, destino, contagem de ferramentas, status de conexão (honesto: `unknown` sem dados upstream), último erro, reconexões; legível pelo modelo, reconstruível do log da sessão, cinco idiomas de saída.
+- **`/mcp <servidor> tools | health | call <tool> [json] | disable | enable`**: lista de ferramentas; diagnósticos derivados (ENOENT → dependência ausente, ECONNREFUSED, timeouts, 401/403/404, DNS, rate limit, reconexão esgotada); chamada de teste pelo **pipeline oficial** (permissões + aprovação em vigor); sugestões de patch exatas.
+- **Configurações → Plugins → MCP**: cartões de status com selos e diagnósticos, **CRUD de servidores** (fragmentos `insert`/`set`/`set disabled`, cópia para a área de transferência ou gravação com aprovação e backup `cordis.patch.yml.bak-<ts>`), **banco de testes de ferramentas** (JSON canônico + conteúdo renderizado, limitado por `trialMaxResultChars`, somente painel) e o **painel de capacidades**: Resources e Prompts marcados como *aguardando suporte upstream* (hoje o cliente oficial só pontua ferramentas).
+- **Sondas**: conectividade Streamable HTTP com um clique ou passiva (resultados somente do painel).
 
-- A linha não aparece? Rode `dsh web --dump-config` e confira se o insert `mcp-panel` foi aplicado com um id único.
-- O painel mostra `status: unknown (source: derived)` — esperado até a costura upstream aterrissar; veja [docs/upstream-proposal.md](docs/upstream-proposal.md).
-- O painel parece desatualizado? Defina `refreshIntervalMs` com um valor positivo (ex.: `5000`) na linha de configuração `mcp-panel` para consultar automaticamente.
-- O log de boot mostra um fiber `mcp-panel` FAILED — o pacote precisa resolver a partir do perfil (o `name: dsh-mcp-panel` simples resolve via o `node_modules` do perfil ou o respaldo compartilhado).
-- Rollback: remova a linha (ver Desinstalação).
+## Início rápido
 
-## Segurança
+```sh
+dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.4.0
+# ou pelo canal npm:
+dsh plugin --profile web add dsh-mcp-panel@0.4.0
+```
 
-Encontrou um problema de segurança? Abra uma issue no GitHub **sem** colar segredos, chaves ou tokens — redija tudo antes. Este plugin mantém as credenciais dos seus servidores MCP configurados apenas em memória para as requisições de sonda; elas nunca chegam a logs ou snapshots.
+Reinicie (ou deixe a superfície web recarregar o `cordis.patch.yml`) e abra **Configurações → Plugins → MCP**, ou execute `/mcp`.
 
-## Como funciona
+## Honesto por contrato
 
-- **Metade host** — um serviço Typert Remote `mcpPanel` monta o snapshot a partir de três fontes somente leitura: linhas do Loader (entradas `@deepseek-ai/dsh-mcp-client`), `ctx.tools.schemas()` agrupadas pelo namespace `mcp__<server>__`, e observações upstream `mcp/status`. O manifesto `./typert` escrito à mão registra `mcpPanel/status` no gateway; o `zod` é empacotado, então a metade host é autocontida.
-- **Metade navegador** — um bundle `dsh.client` (servido em `/plugins/dsh-mcp-panel/client.js`) monta o mesmo descritor via `ctx.remote.$mount` e registra uma entrada `settings.plugins.tab` somente leitura (`id: mcp`). O apresentador é uma função pura; os estilos têm escopo e usam tokens de tema.
-- **O comando `/mcp`** passa pelo registro de comandos padrão — cada linha cai nos eventos de sessão `command/run` + `command/done`.
+- **A ponte continua sendo a ponte**: nenhuma mudança de transporte/OAuth/protocolo.
+- **Sem status falso**: `unknown` / `—` com `statusSource: 'derived'` sem dados upstream; códigos de saída e stderr nunca inventados (marcados *aguardando suporte upstream*).
+- **Exibição saneada**: credenciais em URLs, userinfo, valores de headers, tokens bearer e JWTs redigidos; os **valores** de env/headers nunca saem do host (o editor vê apenas chaves).
+- **Gravações somente-anexar, com aprovação e backup**: o console nunca reescreve o `cordis.patch.yml`; havendo serviço de aprovação e um agente em turno aberto, pergunta ao `ctx.approval` (apenas `allowed-once` prossegue); caso contrário, a confirmação interativa é o canal de aprovação. `writeEnabled: false` é o interruptor de segurança.
+- **Sem injeção de prompts**: o console não registra seções de prompt; apenas as descrições de suas duas ferramentas/comandos, no estilo minimalista do cliente oficial.
 
-## Desenvolvimento
+## Config
 
-```sh
-pnpm install
-pnpm run typecheck    # porta local: resolve as faces de tipo frescas do checkout do harness via caminhos tsconfig
-pnpm run typecheck:ci # porta npm: resolve as faces de tipo publicadas 0.1.0-rc.6 (o que o CI executa)
-pnpm test             # 109 testes: extremos do sanitizador, agrupamento, tolerância de agregação, saída do comando (5 idiomas), controle de sondas, fiação do cliente, apresentador (selos/resumo/filtro)
-pnpm run build        # declarações tsc → lib/types; tsdown → lib/index.js + lib/typert.host.js + lib/client.js
-pnpm run verify:self-contained
-pnpm run verify:artifacts
-pnpm pack
-```
+| Chave | Valor | Descrição |
+|---|---|---|
+| `probeEnabled` / `probeTimeoutMs` / `maxProbes` | `true` / `10000` / `10` | ferramenta de sonda, prazo, registros exibidos |
+| `refreshIntervalMs` | `0` | atualização sugerida do painel (`0` = sob demanda) |
+| `outputLanguage` | `en` | idioma do `/mcp`: `en\|zh\|es\|pt\|hi` |
+| `passiveProbeEnabled` / `passiveProbeIntervalMs` | `false` / `60000` | sondas passivas e seu intervalo |
+| `trialEnabled` / `trialTimeoutMs` / `trialMaxResultChars` | `true` / `120000` / `60000` | banco de testes e seus limites |
+| `writeEnabled` / `backupCount` | `true` / `5` | interruptor de gravações; backups retidos |
 
-Publicação: `node scripts/release.mjs <x.y.z>` sobe a versão, sela o CHANGELOG, reexecuta a porta, faz commit e cria a tag; ao empurrar a tag, npm e GitHub Release são publicados automaticamente (ver [CONTRIBUTING.md](CONTRIBUTING.md)).
+## Resources e Prompts
 
-Verificação contra um checkout real do harness:
-`node --import tsx/esm scripts/verify-headless.mjs` inicializa o perfil web completo em processo (porta efêmera) e imprime a saída exata de `/mcp`, `/mcp <server> tools` e `/mcp <server> disable`.
+O cliente oficial documenta "Tools are the only bridged MCP capability": ambos estão adiados. O console detecta um seam de catálogo proposto e exibirá listas somente-leitura quando chegar; até lá o painel marca *aguardando suporte upstream* (adendo em `docs/upstream-proposal.md` do harness).
 
 ## Licença
 
-[Apache License 2.0](LICENSE) © 2026 colaboradores do dsh-mcp-panel
+Apache-2.0 — veja [LICENSE](LICENSE).