BookStack MCP Server

Un servidor del MCP que proporciona una interfaz completa para la API de BookStack, permitiendo que modelos de IA generen y editen contenido de la wiki.

Características

Este servidor MCP proporciona herramientas para:

📚 Gestión de Contenido

Libros: Crear, leer, actualizar, eliminar y exportar libros
Capítulos: Gestionar capítulos dentro de libros
Páginas: Crear y editar páginas con contenido HTML o Markdown
Estanterías: Organizar libros en colecciones

🔍 Búsqueda y Descubrimiento

Búsqueda Global: Buscar en todo el contenido de BookStack
Navegación: Explorar la estructura del contenido

👥 Gestión de Usuarios y Permisos

Usuarios: Crear, actualizar y gestionar cuentas de usuario
Roles: Configurar roles y permisos
Autenticación: Soporte para autenticación externa

📎 Recursos Multimedia

Adjuntos: Gestionar archivos adjuntos
Imágenes: Administrar la galería de imágenes

📤 Exportación

Múltiples Formatos: Exportar contenido en HTML, PDF, texto plano y Markdown

Instalación

Prerrequisitos

Node.js 18 o superior
Una instancia de BookStack en funcionamiento
Token de API de BookStack

Configuración

Instalar dependencias:

npm install

Configurar variables de entorno:

export BOOKSTACK_BASE_URL="https://tu-bookstack.example.com" export BOOKSTACK_TOKEN_ID="tu_token_id" export BOOKSTACK_TOKEN="tu_token_secreto"

Compilar el proyecto:

npm run build

Obtener Tokens de API de BookStack

Inicia sesión en tu instancia de BookStack
Ve a tu perfil de usuario (esquina superior derecha)
Selecciona "Preferencias" → "API Tokens"
Crea un nuevo token con los permisos necesarios
Guarda el Token ID y el Token Secret

Uso

Ejecutar el Servidor

npm start

O ejecutar directamente:

node build/index.js

Integración con Cliente MCP

El servidor se comunica a través de stdio y está diseñado para ser usado con clientes MCP como Claude Desktop.

Configuración de Claude Desktop

Agrega esta configuración a tu archivo de configuración de Claude Desktop:

{ "mcpServers": { "bookstack": { "type": "stdio", "command": "npx", "args": ["@lautarobarba/bookstack-mcp-server"], "env": { "BOOKSTACK_BASE_URL": "${BOOKSTACK_BASE_URL}", "BOOKSTACK_TOKEN_ID": "${BOOKSTACK_TOKEN_ID}", "BOOKSTACK_TOKEN": "${BOOKSTACK_TOKEN}" } } } }

Configuración de VS Code

Agrega esta configuración a tu archivo .vscode/mcp.json:

{ "servers": { "bookstack": { "type": "stdio", "command": "npx", "args": ["@lautarobarba/bookstack-mcp-server"], "env": { "BOOKSTACK_BASE_URL": "${BOOKSTACK_BASE_URL}", "BOOKSTACK_TOKEN_ID": "${BOOKSTACK_TOKEN_ID}", "BOOKSTACK_TOKEN": "${BOOKSTACK_TOKEN}" } } } }

Herramientas Disponibles

Gestión de Libros

list_books - Listar todos los libros
get_book - Obtener detalles de un libro específico
create_book - Crear un nuevo libro
update_book - Actualizar un libro existente
delete_book - Eliminar un libro
export_book - Exportar libro en varios formatos

Gestión de Capítulos

list_chapters - Listar capítulos
get_chapter - Obtener detalles de un capítulo
create_chapter - Crear un nuevo capítulo
update_chapter - Actualizar un capítulo
delete_chapter - Eliminar un capítulo
export_chapter - Exportar capítulo

Gestión de Páginas

list_pages - Listar páginas
get_page - Obtener contenido de una página
create_page - Crear una nueva página
update_page - Actualizar contenido de página
delete_page - Eliminar una página
export_page - Exportar página

Gestión de Estanterías

list_shelves - Listar estanterías
get_shelf - Obtener detalles de una estantería
create_shelf - Crear una nueva estantería
update_shelf - Actualizar una estantería
delete_shelf - Eliminar una estantería

Búsqueda

search_all - Buscar en todo el contenido

Gestión de Usuarios

list_users - Listar usuarios
get_user - Obtener detalles de usuario
create_user - Crear nuevo usuario
update_user - Actualizar usuario
delete_user - Eliminar usuario

Gestión de Roles

list_roles - Listar roles
get_role - Obtener detalles de rol
create_role - Crear nuevo rol
update_role - Actualizar rol
delete_role - Eliminar rol

Gestión de Recursos

list_attachments - Listar adjuntos
get_attachment - Obtener detalles de adjunto
delete_attachment - Eliminar adjunto
list_images - Listar imágenes
get_image - Obtener detalles de imagen
update_image - Actualizar imagen
delete_image - Eliminar imagen

Ejemplos de Uso

Crear un Nuevo Libro

// A través del cliente MCP await mcpClient.callTool("create_book", { name: "Guía de Desarrollo", description: "Una guía completa para el desarrollo de software", tags: [ { name: "categoria", value: "desarrollo" }, { name: "nivel", value: "intermedio" }, ], });

Crear una Página con Contenido

await mcpClient.callTool("create_page", { book_id: 1, name: "Introducción a TypeScript", markdown: `# Introducción a TypeScript TypeScript es un lenguaje de programación desarrollado por Microsoft... ## Características principales - Tipado estático - Compatibilidad con JavaScript - Herramientas de desarrollo avanzadas `, tags: [ { name: "lenguaje", value: "typescript" }, { name: "tema", value: "introduccion" }, ], });

Buscar Contenido

await mcpClient.callTool("search_all", { query: "typescript desarrollo", count: 10, });

Seguridad

Todas las operaciones requieren un token de API válido de BookStack
Los permisos se manejan a través del sistema de roles de BookStack
Las validaciones de entrada utilizan schemas Zod para mayor seguridad
Manejo robusto de errores para evitar exposición de información sensible

Desarrollo

Estructura del Proyecto

src/ ├── index.ts # Punto de entrada del servidor MCP ├── types/ # Definiciones de tipos TypeScript │ └── index.ts ├── lib/ # Utilidades y cliente API │ ├── bookstack-client.ts │ └── validation.ts └── tools/ # Implementación de herramientas MCP ├── content-tools.ts └── search-user-tools.ts

Scripts Disponibles

npm run build - Compilar TypeScript a JavaScript
npm run dev - Ejecutar en modo desarrollo con watch
npm start - Ejecutar el servidor compilado
npm test - Ejecutar tests (si están configurados)

Contribuir

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
Commit tus cambios (git commit -am 'Agregar nueva funcionalidad')
Push a la rama (git push origin feature/nueva-funcionalidad)
Crea un Pull Request

Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

Soporte

Para problemas y preguntas:

Verifica la documentación de la API de BookStack
Revisa los logs de error del servidor MCP
Crea un issue en el repositorio del proyecto

Changelog

v1.0.0

Implementación inicial del servidor MCP
Soporte completo para la API de BookStack
Herramientas para gestión de contenido, usuarios y búsqueda
Validación robusta con Zod
Exportación en múltiples formatos