Docmost (self-hosted)

Servidor MCP para Docmost autoalojado: lee y escribe espacios, páginas y comentarios desde Claude, Cursor o VS Code; funciona en la edición comunitaria gratuita.

GitHub
13

Documentación

@wisflux/docmost-local-mcp

npm version npm downloads license

Servidor MCP para Docmost diseñado para instancias autoalojadas, especialmente despliegues que no tienen licencia empresarial pero aún así quieren acceso MCP confiable desde IDEs locales y herramientas de IA.

El paquete se lanza con npx, mientras que el servidor real es un binario de Rust descargado desde GitHub Releases durante la instalación. Ese binario maneja el tráfico MCP por stdio, la UX de autenticación local, el almacenamiento de sesiones y el acceso a la API de Docmost.

La razón principal de este proyecto: llevar acceso MCP a instalaciones autoalojadas de Docmost sin que una licencia empresarial sea un requisito previo.

Por Qué Este Proyecto

Muchas integraciones MCP están diseñadas en torno a supuestos de alojamiento o empresariales. Este proyecto está intencionalmente optimizado para Docmost autoalojado:

  • Funciona contra tu propia URL base de Docmost
  • Usa autenticación por correo/contraseña de Docmost
  • Almacena el estado de sesión localmente para reutilización
  • Abre un flujo de autenticación local en lugar de requerir un plano de control alojado separado
  • Se distribuye como un punto de entrada simple de npx para integración fácil con IDEs

Si ejecutas tu propio Docmost y quieres tenerlo disponible dentro de Cursor, Claude Desktop u otro cliente MCP, este paquete es el camino directo.

Destacados

  • Gran ajuste para instancias autoalojadas de Docmost sin licencia empresarial
  • Núcleo de servidor en Rust con un pequeño lanzador Node para instalaciones locales predecibles
  • Ventana de autenticación nativa en plataformas compatibles, con respaldo en navegador
  • Selección explícita de instancia Docmost mediante configuración de inicio
  • Reutilización de sesión con comprobaciones de expiración JWT y re-inicio de sesión automático
  • Almacenamiento de credenciales en el llavero del sistema en plataformas compatibles
  • Superficie de herramientas limpia para espacios, páginas, comentarios, miembros y contexto del usuario actual

Herramientas Disponibles

  • list_spaces: lista los espacios Docmost disponibles
  • get_space: obtiene detalles de un espacio específico
  • search_docs: busca documentación, opcionalmente limitada a un espacio
  • search_pages: alias compatible hacia atrás para search_docs
  • get_page: obtiene una página y devuelve su contenido como Markdown
  • list_pages: lista páginas recientes en un espacio
  • list_child_pages: lista páginas hijas para un ID de página padre
  • get_comments: lista comentarios de una página
  • list_workspace_members: lista miembros del espacio de trabajo
  • get_current_user: obtiene el usuario autenticado y el contexto del espacio de trabajo
  • create_page: crea una nueva página en un espacio desde contenido Markdown
  • update_page: actualiza el título y/o el contenido Markdown de una página existente
  • duplicate_page: duplica una página (y sus subpáginas) dentro de su espacio
  • copy_page_to_space: copia una página (y sus subpáginas) a un espacio diferente
  • move_page: mueve una página bajo un nuevo padre, o a la raíz del espacio
  • move_page_to_space: mueve una página (y sus subpáginas) a un espacio diferente
  • create_space: crea un nuevo espacio con nombre y slug de URL
  • update_space: actualiza el nombre, slug y/o descripción de un espacio
  • create_comment: añade un comentario a nivel de página desde Markdown
  • update_comment: reemplaza el cuerpo de un comentario existente con nuevo Markdown

Hoja de Ruta

Todas las herramientas de lectura y escritura planificadas ya están implementadas. create_comment añade comentarios a nivel de página; los comentarios anclados a una selección de texto específica (comentarios en línea) requieren las posiciones del cursor del editor colaborativo y están fuera del alcance de este servidor basado en REST.

Compatibilidad

Apunta a Docmost aproximadamente desde el último año de lanzamientos (v0.22+); servidores más antiguos funcionan con el mejor esfuerzo. El servidor detecta la versión de Docmost (vía POST /api/version) una vez por sesión y se adapta donde el comportamiento difiere:

  • Ediciones del cuerpo de página: update_page solo puede cambiar el cuerpo de una página existente en Docmost v0.70.0+. En servidores más antiguos, el cuerpo vive en el editor colaborativo y una actualización REST del cuerpo se ignora — update_page lo dice explícitamente y sugiere create_page (que persiste cuerpos en todas las versiones vía el endpoint de importación). Las actualizaciones de título funcionan en todas partes.

Soporte de Contenido

Los cuerpos de páginas y comentarios se escriben en Markdown (encabezados, negrita/cursiva/tachado, código en línea, enlaces, listas, listas de tareas, citas en bloque, bloques de código; las páginas también soportan tablas e imágenes con URL externa). Los comentarios soportan un conjunto más pequeño — sin tablas, listas de tareas ni imágenes.

Menciones (@etiquetado): en cualquier cuerpo Markdown, un enlace con una URL user: o page: se convierte en una mención — [Display Name](user:USER_UUID) etiqueta a un usuario (encuentra el UUID con list_workspace_members) y [Page Title](page:PAGE_UUID) enlaza una página. Los usuarios etiquetados son notificados por Docmost.

Adjuntar archivos/imágenes subidos (a diferencia de referenciar una URL de imagen) no está soportado.

Requisitos

  • Node.js 18 o más reciente para npx
  • Una instancia Docmost alcanzable
  • Autenticación por correo/contraseña habilitada en esa instancia Docmost

Inicio Rápido

Ejecuta el servidor directamente con npx:

npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com

También puedes proporcionar la URL base con una variable de entorno:

DOCMOST_BASE_URL=https://docs.example.com npx -y @wisflux/docmost-local-mcp

Configuración del Cliente MCP

La mayoría de los clientes MCP lanzan el servidor directamente con npx. Añade esto a la configuración MCP de tu cliente, reemplazando la URL base con tu propia instancia Docmost:

{
  "mcpServers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
    }
  }
}

Dónde vive esa configuración, por cliente:

  • Claude Desktop — claude_desktop_config.json (Configuración → Desarrollador → Editar Configuración)

  • Cursor — ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto)

  • Claude Code — un comando, sin edición de archivos:

    claude mcp add docmost -- npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com

  • VS Code (GitHub Copilot) — .vscode/mcp.json, usando una clave de nivel superior servers en lugar de mcpServers:

    {
  "servers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
    }
  }
}

Esta configuración funciona bien cuando quieres una instancia Docmost fija por configuración de cliente. Si --base-url o DOCMOST_BASE_URL está establecido, la página de inicio de sesión muestra esa URL prellenada y bloquea el campo. Si no se configura ninguna URL base, el flujo de inicio de sesión la solicita durante el inicio de sesión interactivo.

Ejemplos de Prompts

Una vez conectado, pregunta a tu cliente de IA cosas como:

  • "Busca en el espacio de Ingeniería en Docmost nuestro runbook de guardia y resúmelo."
  • "Crea una nueva página en el espacio de Producto titulada 'Planificación Q3' a partir de estas notas: …"
  • "Convierte esta transcripción de reunión en una página estructurada de Docmost bajo el espacio de Equipo."
  • "Encuentra cada página en Docmost que mencione el antiguo endpoint de API y listalas."
  • "Lee la página 'Onboarding' y redacta una lista de verificación más corta como nueva subpágina."
  • "Añade un comentario en la página de notas de versión señalando el paso de migración faltante."

Flujo de Autenticación

  1. Tu cliente MCP lanza el servidor sobre stdio.
  2. En la primera llamada de herramienta autenticada, el servidor inicia una página de inicio de sesión HTTP local en 127.0.0.1.
  3. El servidor abre una ventana de autenticación nativa cuando está disponible, o recurre al navegador del sistema.
  4. Ingresas tu correo y contraseña allí. Si --base-url o DOCMOST_BASE_URL está establecido, la URL de Docmost está prellenada y bloqueada.
  5. El servidor inicia sesión a través de /api/auth/login, extrae la cookie authToken, almacena la sesión y opcionalmente guarda las credenciales para re-inicio de sesión automático.
  6. Las solicitudes futuras reutilizan el token guardado hasta que esté cerca de expirar o sea rechazado por Docmost.

Estado Local y Almacenamiento de Credenciales

El servidor almacena el estado local en:

~/.docmost-local-mcp/

Archivos utilizados allí:

  • config.json: última URL base y correo
  • session.json: token de autenticación guardado y expiración

Las credenciales se almacenan en el llavero del sistema cuando está disponible, que es la ruta preferida en plataformas compatibles.

Si el almacenamiento seguro de credenciales del sistema operativo no está disponible, el servidor recurre al almacenamiento de credenciales local cifrado para poder seguir soportando la reutilización de inicio de sesión sin escribir credenciales en texto plano. Ese respaldo es intencionalmente secundario al almacenamiento respaldado por llavero.

Notas de Plataforma

La ventana de autenticación nativa usa la vista web del sistema en cada plataforma:

  • macOS: WKWebView
  • Windows: WebView2
  • Linux: WebKitGTK

Advertencias importantes:

  • Windows necesita el runtime WebView2 disponible
  • Los entornos de escritorio Linux necesitan paquetes WebKitGTK instalados
  • Cuando el binario se compila sin la característica native-webview, siempre se usa el respaldo del navegador

Referencia de Herramientas

list_spaces

Devuelve nombres, slugs e IDs de espacios Docmost.

search_docs

Entradas:

  • query: texto de búsqueda requerido
  • space_id: ID de espacio Docmost opcional

search_pages

Entradas:

  • query: texto de búsqueda requerido
  • space_id: ID de espacio Docmost opcional

Este es un alias compatible hacia atrás para la búsqueda de páginas. search_docs sigue disponible.

get_space

Entradas:

  • space_id: ID de espacio Docmost requerido

get_page

Entradas:

  • slug_id: el ID de slug de página devuelto por search_docs

list_pages

Entradas:

  • space_id: ID de espacio Docmost requerido
  • limit: límite de recuento de páginas opcional
  • cursor: cursor de paginación opcional

list_child_pages

Entradas:

  • page_id: ID de página padre requerido
  • limit: límite de recuento de páginas opcional
  • cursor: cursor de paginación opcional

get_comments

Entradas:

  • page_id: ID de página requerido
  • limit: límite de recuento de comentarios opcional
  • cursor: cursor de paginación opcional

list_workspace_members

Entradas:

  • limit: límite de recuento de miembros opcional
  • cursor: cursor de paginación opcional
  • query: texto de búsqueda de miembros opcional
  • admin_view: indicador de visibilidad de administrador opcional

get_current_user

Entradas:

  • ninguna

create_page

Entradas:

  • space_id: ID de espacio Docmost requerido (UUID) para crear la página
  • title: título de página requerido
  • markdown: cuerpo de página opcional como Markdown
  • parent_page_id: ID de página padre opcional para anidar (solo páginas solo-título)

Cuando se proporciona markdown, el cuerpo de la página se envía a través del endpoint de importación de Docmost (POST /api/pages/import), que es el único mecanismo que persiste de manera confiable el contenido del cuerpo de la página en todas las versiones de Docmost (incluidos servidores autoalojados más antiguos). Las páginas creadas con un cuerpo aterrizan en la raíz del espacio — parent_page_id se respeta solo para páginas solo-título.

update_page

Entradas:

  • page_id: ID de página Docmost o ID de slug requerido
  • title: nuevo título opcional (omitir para dejar sin cambios)
  • markdown: nuevo cuerpo opcional como Markdown; reemplaza el contenido existente (omitir para dejar sin cambios)

Actualizar el título de una página funciona en todas las versiones de Docmost. Actualizar el cuerpo de una página existente vía REST funciona solo en Docmost más reciente; en servidores autoalojados más antiguos (por ejemplo, v0.25.x) el cuerpo se edita únicamente a través del editor colaborativo y una actualización REST del cuerpo no se aplica. Para establecer el contenido del cuerpo de manera confiable allí, crea una nueva página con create_page en su lugar.

Para el diseño completo, detalles de conversión Markdown→ProseMirror, campos verificados de la API de Docmost y advertencias de versión, consulta docs/write-tools.md.

Desarrollo

Para detalles del flujo de trabajo de mantenedores y contribuyentes, consulta CONTRIBUTING.md.

Licencia

MIT