dsh-mcp — MCP-Serververwaltungs-Plugin (MCP Server Manager for DSH)

Bietet MCP-Serververwaltungsfunktionen (Model Context Protocol) für die DSH-Web-GUI:

• Serverliste: MCP-Server auf der Seite „Einstellungen → MCP" hinzufügen/bearbeiten/löschen, unterstützt stdio (Unterprozess), Streamable HTTP und SSE (Server-Sent Events) als Übertragungsarten, auch Massenhinzufügen aus JSON möglich; Konfiguration wird in ~/.dsh/dsh-mcp.json gespeichert (0600, atomares Schreiben).

• Aktivieren/Deaktivieren: Jeder Server hat einen globalen Schalter; nach dem Deaktivieren wird die Verbindung getrennt und seine Tools werden nicht mehr registriert.

• Sitzungsbezogene Verbindungsauswahl: Der Sitzungsbereich (Titelleiste) erhält einen „MCP“-Auswahlbutton, mit dem ausgewählt werden kann, welche MCP-Server in dieser Sitzung verbunden werden (standardmäßig alle aktivierten, oder explizit „keine verbinden“); nicht ausgewählte Server werden in dieser Sitzung nicht verwendet; der Reiter „Sitzungsverbindungen“ auf der Seite „Einstellungen → MCP“ kann ebenfalls angepasst werden, die Auswahl wird sofort wirksam.

• Tool-Registrierung: Tools verbundener Server werden als mcp__<Server-ID>__<Toolname> als sitzungsbezogene Tools registriert (über agent.ctx.tools.register), nur für die ausgewählte Sitzung sichtbar; Aufrufe werden über das MCP-Protokoll weitergeleitet.

• Verbindungsverwaltung: Automatische Wiederverbindung bei Verbindungsabbruch mit exponentiellem Backoff (maximal 10 Versuche), Unterstützung von notifications/tools/list_changed für die Hot-Synchronisierung der Tool-Liste; die GUI bietet einen Ein-Klick-Verbindungstest; ein Klick auf die „Tool-Anzahl“ eines Servers listet die von diesem Server bereitgestellten Tools auf.

• OAuth-Browser-Autorisierung: Für HTTP/SSE-Server, die eine Bearer-Autorisierung benötigen (401-Herausforderung), öffnet ein Klick auf „Autorisieren“ ein Autorisierungspanel, um die Anmeldung im externen Browser abzuschließen (RFC 9728/8414-Discovery + dynamische Client-Registrierung + PKCE); Token werden in ~/.dsh/dsh-mcp-oauth/<id>.json (0600) persistiert und automatisch mitgeführt, bei Verbindungsabbruch wird automatisch aktualisiert; der Callback-Listener verwendet den festen Port 3085 (bei Belegung Fallback auf zufälligen Port, mit automatischer Bereinigung ungültiger Registrierungen und Neuregistrierung), nach Abschluss der Autorisierung wird automatisch neu verbunden, beim Löschen des Servers werden die Token ebenfalls entfernt.

• MCP-Auswahl in der Sitzungsleiste: Das Dropdown-Panel des „MCP n“-Buttons in der Titelzeile passt die Ausrichtung automatisch an – egal wie kurz der Sitzungsname oder wie schmal das Fenster ist, das Panel ist vollständig sichtbar und wird nicht vom Fensterrand abgeschnitten.

• Agent-Tools: mcp_list listet die konfigurierten Server und ihren Betriebsstatus auf; das Systemprompt kündigt dieses Plugin dem Modell automatisch an.

Architektur

• Host-Seite (Host, src/index.ts): cordis-Plugin name = 'mcp', mountet /api/dsh-mcp/*-Routen (Loopback-Beschränkung), mcp_list-Tool, Systemprompt-Absatz und überwacht agent/created / agent/disposed, um die sitzungsbezogenen Tool-Registrierungen für jede Sitzung zu verwalten.

• Engine (src/engine.ts + src/engine/connection.ts + src/engine/bridge.ts): Eine Verbindung pro Server (@modelcontextprotocol/sdk), gemeinsame Verbindung, Registrierung pro Sitzung.

• Speicher (src/store.ts): Server-CRUD + Sitzungsauswahl, reine Datei-I/O, keine cordis-Abhängigkeit.

• Client (src/client/*): Offizielle Slot-Mounts – „Einstellungen“-Seitenleiste settings.section (id mcp, Server-/Sitzungs-Reiter) + MCP-Auswahl in der Sitzungsleiste conversation.session.header.actions; Farben über --dsw-alias-*-Theme-Variablen (automatische Anpassung an helle/dunkle Themes).

Related MCP server: mcp-server

Installation

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

Nach der Installation dsh neu starten (dsh --profile web), damit es wirksam wird: Der Host lädt die Node-Seite, die Web-GUI lädt die Browser-Seite (/plugins/dsh-mcp/client.js).

Übergabe zur Installation an andere

Den gesamten dsh-mcp-Ordner an die andere Person übergeben (kein node_modules erforderlich, aber die lib/-Build-Artefakte müssen erhalten bleiben – sie enthalten lib/index.js für die Host-Seite und lib/client.js für die Browser-Seite, die tatsächlich von dsh geladen werden). Die Schritte für die andere Person:

# 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-Hinweise:

• Wenn pnpm install mit ERR_PNPM_UNEXPECTED_STORE fehlschlägt (pnpm-Store-Pfadkonflikt), schreiben Sie in die .npmrc des Profils (~/.dsh/profiles/web/.npmrc) store-dir=Ihr pnpm-Store-Pfad (z. B. C:/Users/<Ihr>/AppData/Local/pnpm/store/v11).

• Wenn die Installation mit dsh plugin add fehlschlägt, kann manuell installiert werden: Führen Sie unter ~/.dsh/profiles/web pnpm add --store-dir <gleicher Store-Pfad wie oben> link:C:/path/to/dsh-mcp aus und fügen Sie dsh-mcp zur dsh.profile.bundles-Liste dieses Profils hinzu, dann neu starten.

• Laufzeitumgebung: Node ≥ 22.19 (package.json engines).

Verwendung

1. Öffnen Sie „Einstellungen“, wählen Sie in der Seitenleiste „MCP“, um zur Serververwaltungsseite zu gelangen.

2. Reiter „Server“: Server hinzufügen (Formular oder „Aus JSON hinzufügen“, für stdio Startbefehl/Parameter/Umgebungsvariablen angeben, oder für Streamable HTTP / SSE URL/Request-Header angeben), klicken Sie auf „Test“, um die Konnektivität zu überprüfen; klicken Sie auf „Toolanzahl“, um die Tools aufzulisten; beim Bearbeiten wird das Formular automatisch mit den gespeicherten Parametern/Umgebungsvariablen vorausgefüllt, Sie können auch zu „JSON anzeigen“ wechseln, um die vollständige Konfiguration zu sehen und zu kopieren.

3. Klicken Sie in der Titelzeile der Sitzungsleiste auf den „MCP“-Auswahlbutton, wählen Sie die Server aus, die in dieser Sitzung verbunden werden sollen (oder klicken Sie auf „Alle aktivierten“ / „Keine verbinden“), sofort wirksam – das Modell dieser Sitzung kann dann die entsprechenden mcp__…-Tools aufrufen; der Reiter „Einstellungen → MCP → Sitzungsverbindungen“ kann ebenfalls angepasst werden.

4. Wenn der Server eine Bearer-Autorisierung benötigt: Bearbeiten Sie den Server, aktivieren Sie im HTTP/SSE-Formular „OAuth-Browser-Autorisierung aktivieren“, speichern Sie und klicken Sie dann in der Liste auf „Autorisieren“ – der Browser öffnet die Autorisierungsseite, nach Abschluss wird automatisch verbunden (Token werden in ~/.dsh/dsh-mcp-oauth/<id>.json gespeichert); „Autorisierung löschen“ ermöglicht eine erneute Autorisierung.

5. In der Sitzung können Sie den Agenten direkt fragen „Welche MCP-Server gibt es?“ – er wird mit mcp_list antworten.

Sicherheitsmodell

• Die Konfiguration (stdio-Umgebungsvariablen, HTTP-Header wie Authorization) wird im Klartext in der lokalen privaten Datei ~/.dsh/dsh-mcp.json gespeichert – dasselbe Vertrauensmodell wie die dsh-ssh-Passwortspeicherung. Die Listen-API gibt keine Schlüsselwerte zurück; nur die „Details bearbeiten“-API (auf Loopback beschränkt) gibt die vollständige Konfiguration für die Formularvorausfüllung und „JSON anzeigen“ zurück, um zu vermeiden, dass beim Bearbeiten gespeicherte Parameter und Umgebungsvariablen versehentlich gelöscht werden.

• Die stdio-Übertragung startet die vom Benutzer konfigurierten Befehle mit den Rechten des Host-Prozesses; die MCP-Tool-Ausgaben werden unverändert zurückgegeben und können sensible Informationen enthalten.

• OAuth-Token (Access/Refresh-Token und PKCE-Verifier) werden im Klartext in ~/.dsh/dsh-mcp-oauth/<serverId>.json (0600) gespeichert – dasselbe Vertrauensmodell wie die Konfigurationsdatei; der Autorisierungs-Callback lauscht auf einem Loopback-Port, nur lokal zugänglich. Der Callback-Listener verwendet den festen Port 3085 (bei Belegung Fallback auf zufälligen Port), um sicherzustellen, dass registrierte Clients nach einem dsh-Neustart weiterhin übereinstimmen und kein invalid redirect_uri auftritt; wenn eine Portänderung erkannt wird, werden alte Registrierungen automatisch gelöscht und neu registriert.

• Alle /api/dsh-mcp/*-Routen sind auf Loopback beschränkt (Schutz vor LAN-Exposition).

Entwicklung

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

Der Engine-End-to-End-Test startet tatsächlich einen stdio-MCP-Server-Unterprozess, um Verbindung, Discovery, sitzungsbezogene Registrierung und Aufrufweiterleitung zu verifizieren.

Bekannte Einschränkungen

• MCP-Tools, die taskSupport: required erfordern, werden nicht unterstützt (die Brückenschicht lehnt sie ab und meldet einen Fehler).

• Bildartige Tool-Ergebnisse werden auf Text-Platzhalter reduziert (keine Anbindung an den Anhangsspeicher).

• Eine Umbenennung des Servers hat keinen Einfluss auf die Toolnamen (Toolnamen verwenden die id als Namensraum); das Löschen eines Servers trennt die Verbindung und entfernt ihn aus allen Sitzungsauswahlen.

Versionsverlauf

• 0.2.0: OAuth-Browser-Autorisierung verbessert – Autorisierungspanel (Abschluss im externen Browser, automatische Erkennung), fester Callback-Port 3085, automatische Neuregistrierung bei Portänderung (behebt invalid_redirect_uri), Löschen des Servers löscht Token synchron, Autorisierungsbutton immer sichtbar (erneute Autorisierung möglich), automatische Wiederverbindung nach Abschluss der Autorisierung (Verifier-Snapshot immun gegen veraltete Verbindungsüberschreibungen, Verbindungs-401 löst keine automatische Autorisierungsabläufe mehr aus, die den Benutzerablauf stören), Dropdown-Auswahl in der Sitzungsleiste passt sich automatisch an, um Beschneidung zu vermeiden, mcp_list-Ausgabe und Schema ausgerichtet.

• 0.1.0: Basisversion – Serverliste hinzufügen/löschen/ändern/aktivieren/deaktivieren/testen, sitzungsbezogene Verbindungsauswahl, sitzungsbezogene Tool-Registrierung, Wiederverbindung bei Verbindungsabbruch, Hot-Synchronisierung der Tool-Liste, SSE-Übertragungsunterstützung, Massenhinzufügen aus JSON, Bearbeitungsvorausfüllung/JSON-Anzeige.