dsh-mcp — плагин управления MCP-серверами (MCP Server Manager for DSH)

Предоставляет DSH Web GUI возможность управлять MCP-серверами (Model Context Protocol):

• Список серверов: на странице «Настройки → MCP» можно добавлять / изменять / удалять MCP-серверы; поддерживаются три транспорта: stdio (подпроцесс), Streamable HTTP и SSE (серверные события); также можно массово добавлять из JSON; конфигурация хранится в ~/.dsh/dsh-mcp.json (0600, атомарная запись).

• Включение / отключение: у каждого сервера есть глобальный переключатель; после отключения соединение разрывается, и его инструменты больше не регистрируются.

• Выбор подключений на уровне сеанса: в панели сеанса (строка заголовка) добавлен селектор «MCP», в котором можно отметить, какие MCP-серверы подключать для данного сеанса (по умолчанию — все включённые, также можно явно выбрать «не подключать ни один»); серверы без отметки в этом сеансе не используются; вкладка «Подключения сеанса» на странице «Настройки → MCP» тоже позволяет менять выбор, изменения применяются сразу.

• Регистрация инструментов: инструменты подключённых серверов регистрируются как mcp__<服务器id>__<工具名> в качестве инструментов области сеанса (через agent.ctx.tools.register) и видны только выбранному сеансу; вызовы пересылаются по протоколу MCP.

• Управление подключениями: при разрыве соединения автоматическое переподключение с экспоненциальной задержкой (до 10 раз); поддерживается горячая синхронизация списка инструментов через notifications/tools/list_changed; в GUI есть проверка подключения в один клик; нажатие на «Число инструментов» в карточке сервера показывает список его инструментов.

• OAuth-браузерная авторизация: для HTTP/SSE-серверов, требующих Bearer-авторизации (вызов приходит с 401), нажмите «Авторизовать», чтобы открыть панель авторизации и выполнить вход во внешнем браузере (обнаружение RFC 9728/8414 + динамическая регистрация клиента + PKCE); токены сохраняются в ~/.dsh/dsh-mcp-oauth/<id>.json (0600), затем автоматически передаются и автоматически обновляются при переподключении; callback-прослушивание ведётся на фиксированном порту 3085 (при занятости — случайный порт, при этом недействительные регистрации автоматически очищаются и выполняется повторная регистрация); после завершения авторизации происходит автоматическое переподключение, при удалении сервера токены также удаляются.

• Селектор MCP в панели сеанса: выпадающая панель кнопки «MCP n» в строке заголовка выбирает направление раскрытия адаптивно — каким бы коротким ни было имя сеанса и узким ни было окно, панель остаётся полностью видимой и не обрезается краем окна.

• Инструмент агента: 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): для каждого сервера отдельное подключение (через @modelcontextprotocol/sdk), общие подключения, регистрация по сеансам.

• Хранилище (src/store.ts): CRUD серверов + выбор сеансов, чистый файловый ввод/вывод, без зависимостей от cordis.

• Клиент (src/client/*): официальные слоты — раздел settings.section в боковой панели «Настройки» (id mcp, вкладки «Серверы» и «Подключения сеанса») плюс MCP-селектор в conversation.session.header.actions панели сеанса; цвета используют переменные темы --dsw-alias-* (автоматически адаптируются к светлой и тёмной теме).

Related MCP server: MCP Proxy Server

Установка

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

После установки перезапустите dsh (dsh --profile web), чтобы изменения вступили в силу: хостовая часть загружает Node.js-компонент, а 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), впишите в файл ~/.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 (engines в package.json).

Использование

1. Откройте «Настройки», в боковой панели выберите «MCP», чтобы перейти на страницу управления серверами.

2. Вкладка «Серверы»: добавьте сервер (через фигуру или «из JSON»; для stdio заполните команду запуска, аргументы и переменные окружения, для Streamable HTTP / SSE — URL/заголовки), нажмите «Проверить», чтобы проверить соединение; нажмите «Число инструментов», чтобы перечислить инструменты; при редактировании форма автоматически предзаполняется сохранёнными параметрами и переданными окружения, также можно переключиться в «Просмотр JSON», чтобы увидеть полную конфигурацию и скопировать её.

3. В строке заголовка панели сеанса нажмите селектор «MCP» и отметьте серверы, которые нужно подключить в этом сеансе (или выберите «все включённые» / «не подключать ни одного») — это применяется сразу; модель этого сеанса сможет вызывать соответствующие инструменты mcp__…; вкладка «Подключения сеанса» на странице «Настройки → MCP» делает то же самое.

4. Если серверу нужна Bearer-авторизация: отредактируйте сервер, включите «OAuth-браузерную авторизацию» в форме HTTP/SSE, после сохранения нажмите «Авторизовать» в списке — браузер откроет страницу авторизации, после её завершения подключение установится автоматически (токены хранятся в ~/.dsh/dsh-mcp-oauth/<id>.json); «Очистить авторизацию» позволяет авторизоваться заново.

5. В сеансе можно просто спросить агента «какие MCP-серверы есть» — он ответит с помощью mcp_list.

Модель безопасности

• Конфигурация (переменные окружения stdio, HTTP-заголовки такие, как Authorization) хранится в открытом виде в локальном приватном файле ~/.dsh/dsh-mcp.json — та же модель доверия, что и хранение паролей dsh-ssh. Список-интерфейс не возвращает значения ключей; только интерфейс «просмотра деталей» (ограничен loopback) возвращает полную конфигурацию для предзаполнения формы и «Просмотра JSON», чтобы при редактировании случайно не очистить сохранённые параметры и переменные окружения.

• Транспляция stdio за неё запускает сконфигурированную команду с привилегиями хост-процесса; вывод MCP-инструментов возвращается как есть и может содержать конфиденциальные данные.

• OAuth-токены (access/refresh token и PKCE-verifier) хранятся в открытом виде в ~/.dsh/dsh-mcp-oauth/<serverId>.json (0600) — та же модель доверия, что и для конфигурационного файла; callback авторизации слушает пеле-порт 127.0.0.1, доступен только на этом компьютере. Callback используется на фиксированном порту 3085 (если занято — на случайном порту), чтобы после перезапуска dsh зарегистрированный клиент продолжал совпадать и не возникал invalid redirect_uri; при обнаружении смены порта старые регистрации автоматически удаляются и выполняется повторная регистрация.

• Все маршруты /api/dsh-mcp/* доступны только через loopback (защита от локальной сети).

Разработка

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-сервера и проверяет подключение, обнаружение, регистрацию областей сеанса и перенаправление вызовов.

Известные ограничения

• Не поддерживаются MCP-инструменты с требованием taskSupport: required (мостовой слой отвергает их с ошибкой).

• Результаты инструментов с изображениями сводятся к текстовым заглушкам (не привязываются к хранилищу вложений).

• Переименование сервера не влияет на имена инструментов (имя инструмента использует пространство имён по id); удаление сервера разрывает соединение и убирает его из всех выборов сеансов.

История версий

• 0.2.0: отработана OAuth-браузерная авторизация — панель авторизации (вход во внешнем браузере, автоматическое обнаружение), фиксированный порт callback 3085, автоматическая повторная регистрация при смене порта (исправляет invalid redirect_uri), очистка токенов при удалении сервера, кнопка «Авторизовать» всегда видна (можно повторно авторизоваться), автоподключение после авторизации (снимок verifier защищает от перезаписи устаревшим подключением, сConnection при 401 больше не запускает авторизацию в фоне, не мешая рабочим процессом), адаптивное расширение выпадающей панели селектора в панели сеанса, вывод mcp_list согласован со схемой.

• 0.1.0: базовая версия — создание/изменение/удаление серверов, включение/отключение/проверка, выбор подключений на уровне сеанса, регистрация инструментов области сеанса, переподключение при разрыве, горячая синхронизация списка инструментов, поддержка SSE-транспорта, массовое добавление через JSON, предзаполнение формы при редактировании/просмотр JSON.