bookstack_mcp_server

lautarobarba/bookstack_mcp_server

3.1

If you are the rightful owner of bookstack_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The BookStack MCP Server provides a comprehensive interface for the BookStack API, enabling AI models to generate and edit wiki content.

Tools
3
Resources
0
Prompts
0

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

  1. Instalar dependencias:
npm install
  1. 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"
  1. Compilar el proyecto:
npm run build

Obtener Tokens de API de BookStack

  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

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

  1. Fork el proyecto
  2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
  3. Commit tus cambios (git commit -am 'Agregar nueva funcionalidad')
  4. Push a la rama (git push origin feature/nueva-funcionalidad)
  5. 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:

  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

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