dsh-mcp — Complemento de gestión de servidores MCP (MCP Server Manager for DSH)

Aporta capacidades de gestión de servidores MCP (Model Context Protocol) para la interfaz web de DSH:

• Lista de servidores: en la página «Configuración → MCP», permite añadir / editar / eliminar servidores MCP, con soporte para tres transportes: stdio (proceso hijo), Streamable HTTP y SSE (eventos enviados por el servidor); también se pueden añadir en lote desde JSON; la configuración se guarda en ~/.dsh/dsh-mcp.json (0600, escritura atómica).

• Habilitar / deshabilitar: cada servidor tiene un interruptor global; al deshabilitarlo se desconecta y sus herramientas dejan de registrarse.

• Selección de conexión por sesión: la barra de sesión (fila de título) incorpora un selector «MCP» que permite marcar qué servidores MCP se conectan en esta sesión (por defecto todos los habilitados; también se puede elegir explícitamente «no conectar ninguno»); los servidores no marcados no se usan en esta sesión; la pestaña «Conexión de sesión» de la página «Configuración → MCP» también permite ajustarlo, y los cambios surten efecto de inmediato.

• Registro de herramientas: las herramientas de los servidores conectados se registran como herramientas de ámbito de sesión con el nombre mcp__<id del servidor>__<nombre de la herramienta> (a través de agent.ctx.tools.register) y solo son visibles para la sesión seleccionada; las llamadas se reenvían mediante el protocolo MCP.

• Gestión de conexiones: ante una desconexión, se reconecta automáticamente con retroceso exponencial (máximo 10 intentos); admite sincronización en caliente de la lista de herramientas mediante notifications/tools/list_changed; la GUI ofrece una prueba de conexión con un clic; al hacer clic en el «número de herramientas» de un servidor se pueden enumerar las herramientas que ofrece.

• Autorización OAuth en el navegador: para servidores HTTP/SSE que requieren autorización Bearer (desafío 401), al hacer clic en «Autorizar» se abre un panel de autorización para completar el inicio de sesión en un navegador externo (descubrimiento RFC 9728/8414 + registro dinámico de cliente + PKCE); el token se persiste en ~/.dsh/dsh-mcp-oauth/<id>.json (0600) y se adjunta automáticamente; la reconexión tras una desconexión lo renueva automáticamente; el puerto de escucha del callback es fijo, el 3085 (si está ocupado, se recurre a un puerto aleatorio y se eliminan automáticamente los registros no válidos para volver a registrarse); tras completar la autorización se reconecta automáticamente, y al eliminar el servidor también se elimina el token.

• Selector MCP en la barra de sesión: el panel desplegable del botón «MCP n» de la fila de título adapta automáticamente la dirección de apertura —por muy corto que sea el nombre de la sesión o por muy estrecha que sea la ventana, el panel queda completamente visible y no se recorta por los bordes de la ventana.

• Herramienta de agente: mcp_list enumera los servidores configurados y su estado de ejecución; el mensaje de sistema informa automáticamente al modelo de la existencia de este complemento.

Arquitectura

• Lado del host (Host, src/index.ts): complemento de cordis name = 'mcp', monta las rutas /api/dsh-mcp/* (con valla de loopback), la herramienta mcp_list, el párrafo de mensaje de sistema, y escucha agent/created / agent/disposed para mantener el registro de herramientas de ámbito de sesión de cada sesión.

• Motor (src/engine.ts + src/engine/connection.ts + src/engine/bridge.ts): una conexión por servidor (@modelcontextprotocol/sdk), conexión compartida, registro por sesión.

• Almacenamiento (src/store.ts): CRUD de servidores + selección de sesión, E/S de archivos pura, sin dependencias de cordis.

• Cliente (src/client/*): montaje en los slots oficiales — settings.section de la barra lateral de «Configuración» (id mcp, con dos pestañas: servidores / sesión) + selector MCP de conversation.session.header.actions de la barra de sesión; los colores usan las variables de tema --dsw-alias-* (adaptación automática a temas claro y oscuro).

Related MCP server: MCP Proxy Server

Instalación

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

Tras la instalación, reinicie dsh (dsh --profile web) para que surta efecto: el host carga el lado de nodo y la interfaz web carga el lado de navegador (/plugins/dsh-mcp/client.js).

Entrega a otra persona para su instalación

Basta con entregar a la otra persona la carpeta completa dsh-mcp (no se necesita node_modules, pero hay que conservar los artefactos de compilación de lib/ — contienen lib/index.js del lado del host y lib/client.js del lado del navegador, que es lo que dsh carga realmente). Pasos para la otra persona:

# 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

Notas para Windows:

• Si pnpm install informa de ERR_PNPM_UNEXPECTED_STORE (conflicto de ruta del store de pnpm), escriba store-dir=ruta de su store de pnpm (p. ej. C:/Users/<usted>/AppData/Local/pnpm/store/v11) en el ~/.dsh/profiles/web/.npmrc del perfil.

• Si falla la instalación con dsh plugin add, se puede instalar manualmente: en ~/.dsh/profiles/web ejecute pnpm add --store-dir <la misma ruta de store de antes> link:C:/path/to/dsh-mcp, añada dsh-mcp a la lista dsh.profile.bundles de ese perfil y reinicie.

• Requisitos del entorno de ejecución: Node ≥ 22.19 (engines de package.json).

Uso

1. Abra «Configuración» y seleccione «MCP» en la barra lateral para entrar en la página de gestión de servidores.

2. Pestaña «Servidores»: añada servidores (mediante formulario o «Añadir desde JSON»; para stdio rellene el comando de inicio/parámetros/variables de entorno, o para Streamable HTTP / SSE rellene la URL/cabeceras de solicitud), haga clic en «Probar» para verificar la conectividad; haga clic en «número de herramientas» para enumerar las herramientas; al editar, el formulario se rellena automáticamente con los parámetros/variables de entorno guardados, y también puede cambiar a «Ver JSON» para ver la configuración completa y copiarla.

3. Haga clic en el selector «MCP» de la fila de título de la barra de sesión y marque los servidores que desea conectar en esta sesión (o haga clic en «Todos los habilitados» / «No conectar ninguno»); surte efecto de inmediato —el modelo de esa sesión ya puede invocar las herramientas mcp__… correspondientes; la pestaña «Configuración → MCP → Conexión de sesión» también permite ajustarlo.

4. Cuando el servidor requiera autorización Bearer: edite el servidor, active «Habilitar autorización OAuth en el navegador» en el formulario HTTP/SSE, guarde y haga clic en «Autorizar» en la lista —el navegador abrirá la página de autorización y, al completarse, se conectará automáticamente (el token se guarda en ~/.dsh/dsh-mcp-oauth/<id>.json); «Borrar autorización» permite volver a autorizar.

5. En la sesión puede preguntar directamente al agente «¿qué servidores MCP hay?» —responderá usando mcp_list.

Modelo de seguridad

• La configuración (variables de entorno de stdio, cabeceras HTTP como Authorization) se almacena en texto plano en el archivo privado local ~/.dsh/dsh-mcp.json —el mismo modelo de confianza que el almacenamiento de contraseñas de dsh-ssh. La interfaz de lista no devuelve los valores de las claves; solo la interfaz de «detalles de edición» (restringida a loopback) devuelve la configuración completa para el relleno previo del formulario y «Ver JSON», evitando que al editar se borren por error los parámetros y variables de entorno guardados.

• El transporte stdio inicia el comando configurado por el usuario con los permisos del proceso del host; la salida de las herramientas MCP se devuelve tal cual y puede contener información sensible.

• Los tokens OAuth (access/refresh token y verifier PKCE) se almacenan en texto plano en ~/.dsh/dsh-mcp-oauth/<serverId>.json (0600) —el mismo modelo de confianza que el archivo de configuración; el callback de autorización escucha en un puerto de loopback 127.0.0.1, accesible solo desde la máquina local. El puerto de escucha del callback es fijo, el 3085 (si está ocupado, se recurre a un puerto aleatorio), lo que garantiza que tras reiniciar dsh los clientes registrados sigan coincidiendo y no aparezca invalid redirect_uri; si se detecta un cambio de puerto, se eliminan automáticamente los registros antiguos y se vuelve a registrar.

• Todas las rutas /api/dsh-mcp/* están restringidas a loopback (para evitar la exposición en la LAN).

Desarrollo

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

Las pruebas de extremo a extremo del motor inician realmente un proceso hijo de servidor MCP stdio para verificar la conexión, el descubrimiento, el registro de ámbito y el reenvío de llamadas.

Limitaciones conocidas

• No se admiten herramientas MCP que requieran taskSupport: required (la capa de puente lo rechaza e informa del error).

• Los resultados de herramientas de tipo imagen se degradan a un marcador de posición de texto (no se integran con el almacenamiento de adjuntos).

• Renombrar un servidor no afecta al nombre de las herramientas (el nombre de la herramienta usa el id como espacio de nombres); eliminar un servidor desconecta la conexión y lo elimina de todas las selecciones de sesión.

Historial de versiones

• 0.2.0: mejora de la autorización OAuth en el navegador —panel de autorización (completado en navegador externo, detección automática), puerto de callback fijo 3085, re-registro automático al cambiar el puerto (corrige invalid redirect_uri), borrado del token al eliminar el servidor, botón de autorización siempre visible (permite volver a autorizar), reconexión automática al completar la autorización (la instantánea del verifier es inmune a la sobrescritura de conexiones obsoletas; la conexión 401 ya no inicia automáticamente el flujo de autorización para no interferir con el flujo del usuario), el desplegable del selector de la barra de sesión se adapta automáticamente para evitar recortes, salida de mcp_list alineada con el esquema.

• 0.1.0: versión base —alta/baja/modificación de la lista de servidores, habilitar/deshabilitar, prueba, selección de conexión por sesión, registro de herramientas de ámbito de sesión, reconexión tras desconexión, sincronización en caliente de la lista de herramientas, soporte de transporte SSE, añadido en lote desde JSON, relleno previo al editar/ver JSON.