Bookstack MCP

Um servidor MCP para interagir com o Bookstack, construído com o mcp-framework para Node.js.

GitHub
30
Experimente este MCPPatrocinado

Documentação

BookStack MCP Server

Este repositório hospeda um servidor baseado em Python FastMCP que expõe ferramentas consolidadas para gerenciar uma instância do BookStack. As capacidades principais são os fluxos de trabalho de gerenciamento da galeria de imagens que potencializam experiências de autoria em clientes MCP downstream.

Início rápido

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

Inicie o servidor FastMCP após exportar suas credenciais do BookStack (veja abaixo):

cd fastmcp_server
python3 -m fastmcp_server

Ambiente necessário

Copie .env.example para .env e preencha estas variáveis antes de invocar qualquer ferramenta do BookStack:

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

O token da API deve pertencer a um usuário que possa visualizar e gerenciar a galeria de imagens. Os scripts auxiliares locais usam set -a && source .env para que os valores se apliquem também a trechos Python ad-hoc.

Ferramentas do BookStack

O servidor Python FastMCP fornece gerenciamento abrangente do BookStack por meio de ferramentas consolidadas:

Gerenciamento de Conteúdo

  • bookstack_content_crud — operações CRUD unificadas para livros, estantes, capítulos e páginas (compatível com Letta)
  • bookstack_list_content — lista e filtra entidades de conteúdo com paginação
  • bookstack_search — pesquisa de texto completo no conteúdo do BookStack
  • bookstack_batch_operations — operações em lote de criação, atualização e exclusão

Gerenciamento da Galeria de Imagens

  • bookstack_manage_images — interface unificada de criação/leitura/atualização/exclusão/lista para imagens
  • bookstack_search_images — descoberta avançada com filtros de extensão, data, tamanho e uso

Todas as ferramentas são registradas por fastmcp_server/bookstack/tools.py e disponibilizadas automaticamente quando o servidor FastMCP é iniciado.

📘 Compatibilidade com Letta: Se você estiver usando o Letta como seu cliente MCP, leia docs/LETTA_COMPATIBILITY.md para requisitos importantes de compatibilidade e melhores práticas.

Upload de imagens a partir de URLs

bookstack_manage_images aceita três formatos de entrada para os campos image/new_image durante operações de criação e atualização:

  1. Strings base64 simples
  2. Data URLs (data:image/png;base64,...)
  3. URLs HTTP ou HTTPS

Quando uma URL é fornecida, a ferramenta:

  • Transmite a imagem remota com um tempo limite de 30 segundos e um limite de 50 MB
  • Restringe os esquemas a HTTP/HTTPS e bloqueia alvos internos de loopback, privados, link-local, reservados e baseados em redirecionamento
  • Valida o tipo MIME em relação aos formatos aceitos pelo BookStack (jpeg, png, gif, webp, bmp, tiff, svg+xml)
  • Infere um nome de arquivo a partir do caminho da URL quando um não é fornecido

Parâmetros obrigatórios do BookStack

O endpoint POST /api/image-gallery do BookStack exige dois campos adicionais além do payload binário:

  • type — deve ser gallery para imagens de conteúdo padrão (use drawio apenas ao enviar PNGs do diagrams.net)
  • uploaded_to — o ID numérico da página à qual anexar a imagem. O BookStack rejeita uploads sem um contexto de página real.

A ferramenta expõe estes como entradas opcionais chamadas image_type e uploaded_to. Os valores padrão de gallery e 0 preservam a compatibilidade com versões anteriores, permitindo que os chamadores tenham como alvo páginas específicas quando necessário.

Verificação manual em uma instância ativa

Após exportar suas variáveis de ambiente, você pode confirmar um upload de URL de ponta a ponta com o seguinte trecho (substitua PAGE_ID por um 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

Você deve receber um payload JSON descrevendo a imagem enviada, incluindo miniaturas e o identificador uploaded_to. Um erro 422 significa que o BookStack rejeitou a solicitação (causas comuns: uploaded_to ausente, tipo MIME não permitido, imagem excedendo o limite de 50 MB). Uma resposta 404 normalmente indica que o token da API não tem permissões de galeria.

Testes

Execute os testes unitários Python para as ferramentas do BookStack:

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

A suíte cobre o tratamento de URLs, aplicação de tempo limite e tamanho, rejeição de esquemas inválidos e o encaminhamento dos metadados type/uploaded_to.

Referências adicionais