dsh-mcp — MCP サーバー管理プラグイン（DSH 用 MCP サーバーマネージャー）

DSH Web GUI に MCP（Model Context Protocol）サーバー管理機能を提供します：

• サーバーリスト：「設定 → MCP」ページで MCP サーバーの追加 / 編集 / 削除が可能。stdio（子プロセス）、 Streamable HTTP、SSE（サーバー送信イベント）の 3 つのトランスポートに対応し、JSON からの一括追加も可能。設定は ~/.dsh/dsh-mcp.json（0600、アトミック書き込み）に保存されます。

• 有効 / 無効：各サーバーにグローバルスイッチがあります。無効にすると接続が切断され、そのツールは登録されません。

• セッション単位の接続選択：セッションバー（タイトル行）に「MCP」セレクターが追加され、このセッションで接続する MCP サーバーをチェックできます（デフォルトでは有効なサーバーすべて、明示的に「どれにも接続しない」も選択可能）。チェックされていないサーバーはこのセッションでは使用されません。「設定 → MCP」ページの「セッション接続」タブでも調整でき、チェックは即時反映されます。

• ツール登録：接続済みサーバーのツールは mcp__<サーバーid>__<ツール名> としてセッションスコープの ツール（agent.ctx.tools.register 経由）に登録され、選択されたセッションでのみ表示されます。呼び出しは MCP プロトコルで転送されます。

• 接続管理：切断時は指数バックオフで自動再接続（最大 10 回）、notifications/tools/list_changed による ツールリストのホット同期に対応。GUI からワンクリック接続テストが可能。サーバーの「ツール数」をクリックすると、そのサーバーが提供するツールを一覧表示できます。

• OAuth ブラウザー認証：Bearer 認証が必要な HTTP/SSE サーバー（401 チャレンジ）に対して、「認証」をクリックすると 認証パネルが表示され、外部ブラウザーでログインを完了します（RFC 9728/8414 ディスカバリー + 動的クライアント登録 + PKCE）。トークンは ~/.dsh/dsh-mcp-oauth/<id>.json（0600）に永続化され、自動的に付与されます。切断後の再接続時には自動更新されます。コールバックは固定 ポート 3085 で待ち受け（使用中はランダムにフォールバックし、無効な登録を自動クリアして再登録）、認証完了後は自動再接続、サーバー削除時には トークンも一緒に削除されます。

• セッションバー MCP セレクター：タイトル行の「MCP n」ボタンのドロップダウンパネルは展開方向を自動調整——セッション名が短くても、 ウィンドウが狭くても、パネルは完全に表示され、ウィンドウの端で切り取られることはありません。

• Agent ツール：mcp_list で設定済みサーバーと実行状態を一覧表示。システムプロンプトが自動的にこのプラグインをモデルに通知します。

アーキテクチャ

• ホスト側（Host、src/index.ts）：cordis プラグイン name = 'mcp'。/api/dsh-mcp/* ルート（loopback フェンス）、 mcp_list ツール、システムプロンプト段落をマウントし、agent/created / agent/disposed を監視して各セッションのスコープツール登録を維持します。

• エンジン（src/engine.ts + src/engine/connection.ts + src/engine/bridge.ts）： サーバーごとに 1 つの接続（@modelcontextprotocol/sdk）、接続を共有し、セッションごとに登録します。

• ストレージ（src/store.ts）：サーバーの CRUD + セッション選択。純粋なファイル I/O で、cordis 依存はありません。

• クライアント（src/client/*）：公式スロットにマウント——「設定」サイドバーの settings.section（id mcp、 サーバー / セッションの 2 タブ）+ セッションバー conversation.session.header.actions の MCP セレクター。 色は --dsw-alias-* テーマ変数を使用（明暗テーマに自動対応）。

Related MCP server: MCP Proxy Server

インストール

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

インストール後、dsh（dsh --profile web）を再起動すると有効になります：ホスト側はノード側を読み込み、Web GUI はブラウザー側 （/plugins/dsh-mcp/client.js）を読み込みます。

他の人にインストールを任せる場合

dsh-mcp フォルダー全体を渡すだけです（node_modules は不要ですが、lib/ のビルド成果物は保持してください—— ホスト側の lib/index.js とブラウザー側の lib/client.js が含まれており、dsh が実際に読み込むものです）。相手側の手順：

# 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 の注意事項：

• pnpm install で ERR_PNPM_UNEXPECTED_STORE（pnpm store パスの競合）が発生する場合、プロファイルの ~/.dsh/profiles/web/.npmrc に store-dir=あなたの pnpm store パス（例： C:/Users/<あなた>/AppData/Local/pnpm/store/v11）を書き込みます。

• dsh plugin add のインストールが失敗する場合は、手動でインストールできます：~/.dsh/profiles/web で pnpm add --store-dir <上記と同じ store パス> link:C:/path/to/dsh-mcp を実行し、dsh-mcp をそのプロファイルの dsh.profile.bundles リストに追加してから再起動します。

• 実行環境要件：Node ≥ 22.19（package.json engines）。

使用方法

1. 「設定」を開き、サイドバーで「MCP」を選択してサーバー管理ページに移動します。

2. 「サーバー」タブ：サーバーを追加（フォームまたは「JSON から追加」、stdio では起動コマンド/引数/環境変数を入力、 または Streamable HTTP / SSE では URL/リクエストヘッダーを入力）、「テスト」をクリックして接続を検証。「ツール数」をクリックしてツールを一覧表示。 編集時はフォームに保存済みのパラメータ/環境変数が自動的にプリフィルされ、「JSON を表示」に切り替えて完全な設定を表示・コピーすることもできます。

3. セッションバーのタイトル行で「MCP」セレクターをクリックし、このセッションで接続するサーバーをチェック（または「すべて有効」/「どれにも接続しない」をクリック）、 即時反映——そのセッションのモデルは対応する mcp__… ツールを呼び出せます。「設定 → MCP → セッション接続」タブでも同様に調整できます。

4. サーバーが Bearer 認証を必要とする場合：サーバーを編集し、HTTP/SSE フォームで「OAuth ブラウザー認証を有効にする」をオンにし、 保存後、リストで「認証」をクリック——ブラウザーで認証ページが開き、完了すると自動的に接続されます（トークンは ~/.dsh/dsh-mcp-oauth/<id>.json に保存）。「認証をクリア」で再認証できます。

5. セッション内でエージェントに「MCP サーバーは何がありますか？」と直接尋ねると、mcp_list で回答します。

セキュリティモデル

• 設定（stdio 環境変数、Authorization などの HTTP ヘッダー）は平文でローカルのプライベートファイル ~/.dsh/dsh-mcp.json に保存されます——dsh-ssh のパスワード保存と同じ信頼モデルです。リスト API はキー値を返しません。 ただし「編集詳細」API（loopback 限定）のみ、フォームのプリフィルと「JSON 表示」のために完全な設定を返します。編集時に保存済みのパラメータと環境変数を誤ってクリアしないようにするためです。

• stdio トランスポートは、ホストプロセスの権限でユーザー設定のコマンドを起動します。MCP ツールの出力はそのまま返され、機密情報が含まれる可能性があります。

• OAuth トークン（アクセス/リフレッシュトークンと PKCE verifier）は平文で ~/.dsh/dsh-mcp-oauth/<serverId>.json（0600）に保存されます——設定ファイルと同じ信頼モデルです。認証コールバックは 127.0.0.1 のループバックポートで待ち受け、ローカルマシンからのみアクセス可能です。コールバックは固定ポート 3085 で待ち受け（使用中はランダム ポートにフォールバック）し、dsh 再起動後も登録済みクライアントが一致し、invalid redirect_uri が発生しません。 ポートの変更を検出すると、古い登録を自動的にクリアして再登録します。

• すべての /api/dsh-mcp/* ルートは loopback のみに制限されています（LAN への露出防止）。

開発

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

エンジンのエンドツーエンドテストでは、実際に stdio MCP サーバーの子プロセスを起動し、接続、ディスカバリー、スコープ登録、呼び出し転送を検証します。

既知の制限

• taskSupport: required を必要とする MCP ツールはサポートされていません（ブリッジ層が拒否してエラーを返します）。

• 画像タイプのツール結果はテキストプレースホルダーにダウングレードされます（添付ファイルストレージには接続されません）。

• サーバー名を変更してもツール名には影響しません（ツール名は id を名前空間として使用）。サーバーを削除すると接続が切断され、すべてのセッション選択からも削除されます。

バージョン履歴

• 0.2.0：OAuth ブラウザー認証の改善——認証パネル（外部ブラウザーで完了、自動検出）、コールバック固定ポート 3085、 ポート変更時の自動再登録（invalid redirect_uri を修正）、サーバー削除時のトークン同期削除、認証ボタンは常に表示（再認証可能）、 認証完了時の自動再接続（verifier スナップショットにより古い接続の上書きを防止、接続 401 で自動的に認証フローを開始してユーザーフローを妨げない）、 セッションバーセレクターのドロップダウン自動調整で切り取り防止、mcp_list の出力とスキーマの整合。

• 0.1.0：基本バージョン——サーバーリストの追加/削除/編集/有効無効/テスト、セッション単位の接続選択、セッションごとのスコープツール登録、 切断時の再接続、ツールリストのホット同期、SSE トランスポート対応、JSON 一括追加、編集時のプリフィル/JSON 表示。