Lançado o plone-client

O plone-client é uma biblioteca Python, uma linha de comando e um servidor MCP para sites Plone, construído sobre a plone.restapi. A segunda versão alfa já está no PyPI.

Foi lançado o plone-client, um pacote Python para trabalhar com sites Plone por meio da plone.restapi. Ele pode ser usado de três formas: como biblioteca, em scripts e integrações; como linha de comando, no terminal; e como servidor MCP, em assistentes de inteligência artificial.

O pacote foi criado por Érico Andrei durante o Axolote Sprint, em Oaxaca, no México. A versão 1.0.0a2, segunda alfa, já está disponível no PyPI. Ele funciona com o Plone 6.0, 6.1 e 6.2 e exige Python 3.11 ou mais recente.

Como biblioteca

Muitos projetos precisam levar conteúdo de outra fonte para um site Plone: importar a programação de um evento a partir de uma API externa, publicar um item novo sempre que algo é produzido, migrar conteúdo entre sites. Em cada caso, o mesmo código costuma ser reescrito: autenticar no site, criar o conteúdo, enviar os arquivos, publicar.

O plone-client oferece um cliente por site, com um gerenciador para cada serviço da plone.restapi: client.content, client.workflow, client.search, client.users e assim por diante. Cada método envia o que a plone.restapi documenta e devolve o que o site responde, sem um modelo de objetos por cima do JSON. A correspondência com a API é de um para um, e a documentação traz um mapa para o @plone/client, o cliente JavaScript usado pelo Volto.

from plone_client import PloneClient
from plone_client import blocks

with PloneClient("https://example.org", username="editor", password="secret") as client:
    page = client.content.create(
        "/news",
        "Document",
        title="Hello, Plone",
        **blocks.build(blocks.title(), blocks.description(), blocks.text("It works.")),
    )
    client.workflow.transition(page["@id"], "publish")

Acima dos gerenciadores ficam as operações, tarefas que exigem várias requisições na ordem certa: criar uma página a partir de Markdown, criar uma notícia com suas imagens e definir a imagem de destaque, enviar uma pasta local mantendo sua estrutura. Todas aceitam uma simulação (dry run) e relatam cada requisição enviada, de modo que, se algo falhar no meio do caminho, fica claro o que já foi criado.

Como linha de comando

Na linha de comando, cada site é um perfil com nome, URL e usuário. A senha fica no chaveiro do sistema operacional, ou vem de um gerenciador de senhas ou de uma variável de ambiente. O arquivo de configuração não guarda segredos.

plone-client profile add prod --url https://example.org --username editor --read-only
plone-client -p prod search -t "News Item" --state published --limit 10

Um perfil marcado com --read-only recusa qualquer alteração antes de enviar a requisição, o que torna seguro explorar um site em produção.

A saída é em JSON, e cada tipo de erro tem seu próprio código de saída. Isso torna a linha de comando útil tanto para pessoas quanto para scripts e agentes de programação, como o Claude Code. Para estes, o pacote traz uma skill, instalada com plone-client skill install, que ensina os comandos, o modelo de conteúdo do Volto e as regras de segurança: nada de senhas, simulação antes de alterar e nenhuma exclusão sem confirmação.

Como servidor MCP

O comando plone-client mcp coloca os mesmos perfis à disposição de assistentes que falam o protocolo MCP, como o Claude Desktop e o Claude Code. Ele pode servir um perfil, um grupo de perfis ou todos, e as senhas continuam no chaveiro.

Em vez de uma ferramenta para cada um dos mais de cem serviços da plone.restapi, o servidor oferece uma lista curta: as leituras do dia a dia, as operações descritas acima (como create_page, que transforma Markdown em blocos do Volto), a edição de blocos um a um, o workflow, traduções, cópias de trabalho e uma ferramenta genérica para qualquer outro serviço. A opção --tool restringe a lista às ferramentas indicadas, e plone-client mcp --http atende assistentes que se conectam por URL, com um token guardado no chaveiro.

Para dar ao Claude Code acesso a um site:

uv tool install "plone-client[mcp,markdown]"
plone-client profile add blog --url https://example.org --username editor
claude mcp add plone-blog -- plone-client mcp --profile blog

O próprio anúncio do lançamento, em inglês, foi publicado dessa forma: um assistente conectado ao plone-client mcp criou o post a partir de um arquivo Markdown, com a imagem de destaque e os blocos de código.

Vale lembrar que a comunidade já conta com outro servidor MCP para o Plone, o plone-mcp, publicado no npm como @plone/mcp e em desenvolvimento ativo. Os dois projetos vêm de direções diferentes: o plone-mcp exige apenas o Node.js, e o plone-client parte de uma biblioteca Python, compartilhando perfis e travas de segurança entre scripts, terminal e assistentes.

Instalação

uv add plone-client                            # a biblioteca
uv tool install "plone-client[cli]"            # a linha de comando
uv tool install "plone-client[mcp,markdown]"   # o servidor MCP, com páginas em Markdown

O extra markdown exige Python 3.12 ou mais recente.

Documentação

A documentação do plone-client (em inglês) está organizada em:

• Tutoriais: o primeiro script e a primeira sessão na linha de comando;
• Guias práticos: sincronizar conteúdo, gerenciar perfis, enviar arquivos, conectar um assistente pelo MCP e usar com agentes de programação;
• Referência: compatibilidade, cliente, gerenciadores, comandos, configuração e erros;
• Explicações: o desenho do pacote, o tratamento de segredos e quando usar a biblioteca, a linha de comando ou o servidor MCP.

Por ser uma versão alfa, a API ainda pode mudar. Problemas e sugestões podem ser registrados no rastreador de issues do projeto.