Bookstack MCP

Un servidor MCP para interactuar con Bookstack, construido con el mcp-framework para Node.js.

GitHub
30
Prueba este MCPPatrocinado

Documentación

Servidor MCP de BookStack

Este repositorio aloja un servidor basado en Python FastMCP que expone herramientas consolidadas para gestionar una instancia de BookStack. Las capacidades principales son los flujos de trabajo de gestión de la galería de imágenes que impulsan las experiencias de creación en clientes MCP posteriores.

Inicio rápido

# Install Python dependencies for the FastMCP server
pip install -r fastmcp_server/requirements.txt

Inicie el servidor FastMCP después de exportar sus credenciales de BookStack (ver más abajo):

cd fastmcp_server
python3 -m fastmcp_server

Entorno requerido

Copie .env.example a .env y complete estas variables antes de invocar cualquier herramienta de BookStack:

BS_URL=https://your-bookstack.example.com
BS_TOKEN_ID=...
BS_TOKEN_SECRET=...

El token de API debe pertenecer a un usuario que pueda ver y gestionar la galería de imágenes. Los scripts auxiliares locales usan set -a && source .env para que los valores también se apliquen a fragmentos de Python ad-hoc.

Herramientas de BookStack

El servidor Python FastMCP proporciona una gestión integral de BookStack a través de herramientas consolidadas:

Gestión de contenido

  • bookstack_content_crud — operaciones CRUD unificadas para libros, estanterías, capítulos y páginas (compatible con Letta)
  • bookstack_list_content — listar y filtrar entidades de contenido con paginación
  • bookstack_search — búsqueda de texto completo en el contenido de BookStack
  • bookstack_batch_operations — operaciones masivas de creación, actualización y eliminación

Gestión de la galería de imágenes

  • bookstack_manage_images — interfaz unificada de creación/lectura/actualización/eliminación/listado de imágenes
  • bookstack_search_images — descubrimiento avanzado con filtros de extensión, fecha, tamaño y uso

Todas las herramientas son registradas por fastmcp_server/bookstack/tools.py y se exponen automáticamente cuando el servidor FastMCP se inicia.

📘 Compatibilidad con Letta: Si está usando Letta como su cliente MCP, lea docs/LETTA_COMPATIBILITY.md para conocer los requisitos de compatibilidad importantes y las mejores prácticas.

Carga de imágenes desde URLs

bookstack_manage_images acepta tres formatos de entrada para los campos image/new_image durante las operaciones de creación y actualización:

  1. Cadenas base64 simples
  2. URLs de datos (data:image/png;base64,...)
  3. URLs HTTP o HTTPS

Cuando se proporciona una URL, la herramienta:

  • Transmite la imagen remota con un tiempo de espera de 30 segundos y un límite de 50 MB
  • Restringe los esquemas a HTTP/HTTPS y bloquea destinos internos de bucle local, privados, de enlace local, reservados y basados en redirecciones
  • Valida el tipo MIME contra los formatos aceptados por BookStack (jpeg, png, gif, webp, bmp, tiff, svg+xml)
  • Infiere un nombre de archivo de la ruta de la URL cuando no se proporciona uno

Parámetros requeridos de BookStack

El endpoint POST /api/image-gallery de BookStack exige dos campos adicionales además de la carga binaria:

  • type — debe ser gallery para imágenes de contenido estándar (use drawio solo al cargar PNG de diagrams.net)
  • uploaded_to — el ID numérico de la página a la que adjuntar la imagen. BookStack rechaza cargas sin un contexto de página real.

La herramienta los presenta como entradas opcionales llamadas image_type y uploaded_to. Los valores predeterminados de gallery y 0 preservan la compatibilidad hacia atrás mientras permiten a los llamadores apuntar a páginas específicas cuando sea necesario.

Verificación manual contra una instancia en vivo

Después de exportar sus variables de entorno, puede confirmar una carga de URL de extremo a extremo con el siguiente fragmento (reemplace PAGE_ID con un ID de página existente):

cd /opt/stacks/bookstack-mcp/Bookstack-MCP
set -a && source .env && set +a
python3 - <<'PY'
import asyncio, json, time
from fastmcp import FastMCP
from fastmcp_server.bookstack.tools import register_bookstack_tools

TEST_IMAGE_URL = "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"
PAGE_ID = 39  # replace with a page id from your BookStack instance

async def main():
    mcp = FastMCP("manual-test")
    register_bookstack_tools(mcp)
    tool = await mcp.get_tool("bookstack_manage_images")
    result = await tool.run({
        "operation": "create",
        "name": f"URL Upload Test {int(time.time())}",
        "image": TEST_IMAGE_URL,
        "uploaded_to": PAGE_ID,
    })
    print(json.dumps(json.loads(result.content[0].text), indent=2))

asyncio.run(main())
PY

Debería recibir una carga JSON que describa la imagen cargada, incluyendo miniaturas y el identificador uploaded_to. Un error 422 significa que BookStack rechazó la solicitud (causas comunes: falta uploaded_to, tipo MIME no permitido, imagen que excede el límite de 50 MB). Una respuesta 404 generalmente indica que el token de API carece de permisos de galería.

Pruebas

Ejecute las pruebas unitarias de Python para las herramientas de BookStack:

cd fastmcp_server
python3 -m pytest tests/test_manage_images.py -v

La suite cubre el manejo de URLs, el cumplimiento de tiempo de espera y tamaño, el rechazo de esquemas no válidos y el reenvío de metadatos type/uploaded_to.

Referencias adicionales