Servidor MCP de Baomihua Formatter

Un servidor MCP de Node.js independiente para inspeccionar y operar sobre archivos multimedia en OpenList y CloudDrive2, además de consultar metadatos de películas y series de TMDB. El servidor se comunica a través de stdio de MCP y mantiene las credenciales de almacenamiento/TMDB en la configuración local del entorno, no en descripciones de herramientas ni en documentación versionada.

Requisitos

• Node.js 20 o superior (package.json declara engines.node >=20.0.0).

• Acceso de red al endpoint configurado de OpenList y/o CloudDrive2 cuando se utilicen esos backends.

• Credenciales de TMDB cuando se usen las herramientas de TMDB.

Instalación

Desde el directorio del proyecto del servidor:

Set-Location C:\path\to\baomihua-formatter-mcp-server
Copy-Item .env.example .env
npm install

Edita el .env local con los endpoints y credenciales necesarios para tu entorno. .env está ignorado por Git; nunca lo confirmes, pegues secretos en este README ni incluyas credenciales reales en una configuración de cliente MCP que esté versionada.

Las claves de configuración admitidas están documentadas en .env.example, incluyendo:

• OPENLIST_URL, OPENLIST_USERNAME, OPENLIST_PASSWORD y el opcional OPENLIST_OTP_CODE;

• CLOUDDRIVE2_URL, CLOUDDRIVE2_TOKEN y CLOUDDRIVE2_TLS;

• TMDB_API_KEY o TMDB_TOKEN, más los opcionales TMDB_LANGUAGE y TMDB_PROXY;

• STORAGE_CONCURRENCY, UPLOAD_CONCURRENCY y STORAGE_MAX_CONCURRENCY;

Ejecutar el servidor MCP

El script npm inicia el servidor stdio:

npm run mcp

El proceso está destinado a ser lanzado por un cliente MCP, por lo que el tráfico normal del protocolo se envía por stdin/stdout. Mantén los diagnósticos fuera de stdout al incrustar el servidor.

Entrada genérica para cliente MCP

Usa una ruta absoluta al ejecutable de Node y una ruta absoluta al servidor. Reemplaza solo las rutas de ejemplo y configura los secretos a través del .env local del servidor; esta entrada no contiene credenciales intencionadamente:

{
  "mcpServers": {
    "baomihua-formatter": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\baomihua-formatter-mcp-server\\server.js"
      ]
    }
  }
}

El cliente MCP debe lanzar la entrada desde un contexto donde el proyecto del servidor tenga su archivo .env. Un comando shell equivalente es:

& 'C:\Program Files\nodejs\node.exe' 'C:\path\to\baomihua-formatter-mcp-server\server.js'

Grupos de herramientas y semántica

Navegación de almacenamiento

Ambos backends de almacenamiento exponen un listado directo y un escaneo recursivo:

• openlist_list / clouddrive2_list listan solo los hijos directos.

• openlist_scan / clouddrive2_scan recopilan recursivamente los descendientes y aceptan opciones acotadas de concurrency y continue_on_error.

• openlist_stat / clouddrive2_stat inspeccionan una ruta exacta.

• openlist_search / clouddrive2_search buscan entradas por debajo de una ruta.

Las operaciones de escaneo y carga de directorios usan concurrencia acotada. Mantén la concurrencia dentro del máximo configurado del servidor y deja continue_on_error en falso a menos que se acepte intencionadamente una finalización parcial.

Operaciones de archivos

OpenList y CloudDrive2 proporcionan cada uno herramientas para crear directorios, renombrar, eliminar archivos/directorios, mover, copiar y cargar archivos/directorios. CloudDrive2 también ofrece clouddrive2_get_download_url.

Toda herramienta que modifica requiere confirm: true. El Agente o el cliente MCP deben presentar primero al usuario las rutas, nombres, destinos, política de conflictos y efectos destructivos propuestos. El servidor rechaza mutaciones no confirmadas. continue_on_error no es un mecanismo de confirmación; solo controla si un lote acotado continúa después de que un elemento falle.

TMDB

El servidor expone tmdb_search_movie, tmdb_search_tv, tmdb_get_movie_details, tmdb_get_tv_details y tmdb_get_season_details. Estas herramientas devuelven candidatos o metadatos; no renombran archivos.

La extracción de título, año, temporada, episodio y calidad del nombre de archivo es deliberadamente responsabilidad del Agente. Para flujos de trabajo de formateo multimedia, inspecciona la ruta completa de almacenamiento, extrae esos campos de forma independiente, consulta candidatos en TMDB, valida el resultado seleccionado con los detalles y pide al usuario resolver candidatos ambiguos con el mismo nombre antes de proponer una mutación.

Flujo de trabajo recomendado

1. Usa una llamada *_list del backend para navegación directa o *_scan para recopilación recursiva.

2. Mantén las rutas originales y analiza título, año, temporada, episodio, calidad y marcadores de subtítulos de forma independiente.

3. Busca en TMDB, compara los candidatos con la evidencia analizada y obtén detalles para el ID elegido.

4. Muestra una propuesta completa de renombrado/movido/copiado/eliminado/carga y espera confirmación explícita.

5. Ejecuta la mutación confirmada con confirm: true.

6. Verifica con un listado, stat o escaneo posterior e informa éxitos, omisiones y errores.

Desarrollo

Ejecuta la suite de pruebas desde este directorio:

npm test

El proyecto es privado, usa ESM y no tiene dependencia en tiempo de ejecución del antiguo CLI de formateo. Mantén las credenciales y los registros generados fuera de los commits.