MCP Server for BookStack API - Allows AI models to interact with BookStack wiki
npm install @lautarobarba/bookstack-mcp-serverUn 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.
Este servidor MCP proporciona herramientas para:
- 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 Global: Buscar en todo el contenido de BookStack
- Navegación: Explorar la estructura del contenido
- Usuarios: Crear, actualizar y gestionar cuentas de usuario
- Roles: Configurar roles y permisos
- Autenticación: Soporte para autenticación externa
- Adjuntos: Gestionar archivos adjuntos
- Imágenes: Administrar la galería de imágenes
- Múltiples Formatos: Exportar contenido en HTML, PDF, texto plano y Markdown
- Node.js 18 o superior
- Una instancia de BookStack en funcionamiento
- Token de API de BookStack
1. Instalar dependencias:
``bash`
npm install
2. Configurar variables de entorno:
`bash`
export BOOKSTACK_BASE_URL="https://tu-bookstack.example.com"
export BOOKSTACK_TOKEN_ID="tu_token_id"
export BOOKSTACK_TOKEN="tu_token_secreto"
3. Compilar el proyecto:
`bash`
npm run build
1. Inicia sesión en tu instancia de BookStack
2. Ve a tu perfil de usuario (esquina superior derecha)
3. Selecciona "Preferencias" → "API Tokens"
4. Crea un nuevo token con los permisos necesarios
5. Guarda el Token ID y el Token Secret
`bash`
npm start
O ejecutar directamente:
`bash`
node build/index.js
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:
`json`
{
"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:
`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}"
}
}
}
}
- list_books - Listar todos los librosget_book
- - Obtener detalles de un libro específicocreate_book
- - Crear un nuevo libroupdate_book
- - Actualizar un libro existentedelete_book
- - Eliminar un libroexport_book
- - Exportar libro en varios formatos
- list_chapters - Listar capítulosget_chapter
- - Obtener detalles de un capítulocreate_chapter
- - Crear un nuevo capítuloupdate_chapter
- - Actualizar un capítulodelete_chapter
- - Eliminar un capítuloexport_chapter
- - Exportar capítulo
- list_pages - Listar páginasget_page
- - Obtener contenido de una páginacreate_page
- - Crear una nueva páginaupdate_page
- - Actualizar contenido de páginadelete_page
- - Eliminar una páginaexport_page
- - Exportar página
- list_shelves - Listar estanteríasget_shelf
- - Obtener detalles de una estanteríacreate_shelf
- - Crear una nueva estanteríaupdate_shelf
- - Actualizar una estanteríadelete_shelf
- - Eliminar una estantería
- search_all - Buscar en todo el contenido
- list_users - Listar usuariosget_user
- - Obtener detalles de usuariocreate_user
- - Crear nuevo usuarioupdate_user
- - Actualizar usuariodelete_user
- - Eliminar usuario
- list_roles - Listar rolesget_role
- - Obtener detalles de rolcreate_role
- - Crear nuevo rolupdate_role
- - Actualizar roldelete_role
- - Eliminar rol
- list_attachments - Listar adjuntosget_attachment
- - Obtener detalles de adjuntodelete_attachment
- - Eliminar adjuntolist_images
- - Listar imágenesget_image
- - Obtener detalles de imagenupdate_image
- - Actualizar imagendelete_image
- - Eliminar imagen
`javascript`
// 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" },
],
});
`javascript# Introducción a TypeScript
await mcpClient.callTool("create_page", {
book_id: 1,
name: "Introducción a TypeScript",
markdown:
TypeScript es un lenguaje de programación desarrollado por Microsoft...
- Tipado estático
- Compatibilidad con JavaScript
- Herramientas de desarrollo avanzadas,`
tags: [
{ name: "lenguaje", value: "typescript" },
{ name: "tema", value: "introduccion" },
],
});
`javascript`
await mcpClient.callTool("search_all", {
query: "typescript desarrollo",
count: 10,
});
- 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
``
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
- npm run build - Compilar TypeScript a JavaScriptnpm run dev
- - Ejecutar en modo desarrollo con watchnpm start
- - Ejecutar el servidor compiladonpm test
- - Ejecutar tests (si están configurados)
1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)git commit -am 'Agregar nueva funcionalidad'
3. Commit tus cambios ()git push origin feature/nueva-funcionalidad
4. Push a la rama ()
5. Crea un Pull Request
Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE` para más detalles.
Para problemas y preguntas:
1. Verifica la documentación de la API de BookStack
2. Revisa los logs de error del servidor MCP
3. Crea un issue en el repositorio del proyecto
- 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