MCP - Model Context Protocol for Joomla!

MCP - Model Context Protocol para Joomla!

O MCP é um plugin de sistema leve e poderoso para Joomla que fornece um Model Context Protocol — uma API simples baseada em tarefas para gerenciamento de conteúdo. Ele atua como uma ponte simplificada entre seu site Joomla e o mundo moderno de IA, automação de fluxos de trabalho e ferramentas internas. Saiba mais em Model Context Protocol.

O Problema

A API REST integrada do Joomla é abrangente, mas sua complexidade pode ser um obstáculo para integração rápida. Agentes de IA modernos e plataformas de automação de fluxos de trabalho prosperam com "ferramentas" ou endpoints simples e previsíveis para executar ações específicas. Eles precisam de um protocolo claro para interagir com fontes de dados externas sem exigir configurações complexas e específicas de cada serviço.

A Solução: MCP (Model Context Protocol)

O MCP estabelece um protocolo simples para modelos e serviços de IA interagirem com seu conteúdo Joomla. Ele fornece uma API plana de endpoint único, onde uma ação é especificada por um parâmetro task. Esse design torna incrivelmente fácil para qualquer aplicativo criar, atualizar ou recuperar artigos e categorias — fornecendo e recebendo contexto por meio de um protocolo padronizado.

Ele autentica usando o sistema nativo de Token de API do Joomla, garantindo que todas as operações sejam seguras e respeitem os níveis de permissão do usuário associado ao token.

Principais Recursos

• Protocolo Simples: Sem rotas RESTful complexas para aprender. Apenas uma URL e um parâmetro task.
• Seguro: Utiliza o sistema Web Services - Authentication - Token nativo do Joomla.
• Leve: Um único plugin sem dependências externas.
• Pronto para IA: Projetado para servir como a "ferramenta" perfeita para agentes de IA e fluxos de automação lerem e gravarem no seu banco de dados Joomla.
• Endpoints Essenciais: Cobre as tarefas mais comuns de gerenciamento de conteúdo.

O Superpoder de IA e Automação de Fluxos de Trabalho

É aqui que o MCP realmente se destaca. Ele transforma seu CMS Joomla de uma plataforma isolada em um componente dinâmico e integrado dos seus fluxos de trabalho automatizados e pipelines de conteúdo orientados por IA.

Para Automação de Fluxos de Trabalho (Make.com, n8n, Zapier, etc.)

Plataformas como Make.com e n8n são construídas em torno da conexão de serviços por meio de chamadas de API. O MCP fornece os endpoints perfeitos para seus módulos genéricos de "Requisição HTTP".

Exemplo de Uso: Um feed RSS aciona um fluxo de trabalho no n8n. Um nó de IA reescreve o conteúdo e, em seguida, um nó de Requisição HTTP usa o Model Context Protocol (task=mcp.create_article) para publicar instantaneamente o novo artigo no seu site Joomla.

Para Frameworks de Agentes de IA (crewAI, AutoGen, etc.)

Agentes de IA precisam de "ferramentas" para interagir com o mundo real. Os endpoints do MCP são os blocos de construção perfeitos para essas ferramentas, permitindo que os agentes gerenciem conteúdo de forma autônoma.

Exemplo de Uso: Você atribui a um agente crewAI a tarefa "Escreva uma postagem de blog sobre as últimas tendências de IA e publique em nosso site".

1. O ResearcherAgent navega na web.
2. O WriterAgent compõe o artigo.
3. O PublisherAgent recebe uma ferramenta publish_to_joomla, que usa o Model Context Protocol para chamar o endpoint mcp.create_article. A equipe de IA conclui toda a tarefa sem intervenção humana.

Para Ferramentas Internas e Scripts (Windmill, Superblocks, etc.)

Plataformas como Windmill permitem que você crie rapidamente painéis administrativos internos e execute scripts. O MCP fornece uma camada de abstração limpa para interagir com o Joomla.

Exemplo de Uso: Sua equipe de marketing quer um painel simples no Windmill para publicar rapidamente comunicados à imprensa. Um desenvolvedor cria uma interface simples. O botão "Publicar" aciona um script que usa o Model Context Protocol para enviar o conteúdo ao vivo instantaneamente.

Instalação e Configuração

1. Baixar: Baixe o arquivo plg_system_mcp_vX.X.X.zip mais recente da página de Releases.
2. Instalar: No painel do Administrador do Joomla, vá para System -> Install -> Extensions e envie o arquivo zip.
3. Habilitar Plugin: Vá para System -> Manage -> Plugins e pesquise por "MCP". Habilite o plugin.
4. Gerar um Token de API de Usuário:
   • Vá para Users -> Manage e selecione o usuário ao qual deseja conceder acesso à API. As permissões desse usuário serão respeitadas.
     • Clique na aba "Joomla API Token".
     • Clique em "Criar um Novo Token" para gerar uma chave de API. Copie esta chave com segurança.

Uso da API

Nota: Esta é a Versão 2.0 com tarefas de API consolidadas e arquitetura aprimorada.

• Endpoint: https://www.yoursite.com/index.php
• Método: POST
• Cabeçalho de Autenticação: X-Joomla-Token: YOUR_JOOMLA_API_TOKEN
• Parâmetro de Consulta: task=mcp.your_task

Tarefas Disponíveis

Tarefa	Descrição	Exemplo de Corpo JSON
mcp.info	Retorna informações do plugin e status de autenticação.	null
mcp.get_article	Recupera um único artigo por ID.	{"article_id": 124}
mcp.get_articles	Recupera uma lista de todos os artigos.	null ou {"catid": 8, "state": 1, "limit": 10}
mcp.get_categories	Recupera uma lista de todas as categorias de conteúdo.	null
mcp.get_tags	Recupera uma lista de todas as tags.	null
mcp.create_article	Cria um novo artigo.	{"title": "My Title", "articletext": "<p>Content</p>", "catid": 2, "published": true}
mcp.update_article	Atualiza o conteúdo e/ou estado do artigo (consolidado).	{"article_id": 124, "title": "Updated Title", "state": 0} ou {"article_id": 126, "state": -2}

Exemplo: Requisição curl Completa

Veja como criar um novo artigo publicado na categoria de ID 8.

curl -X POST \
  -H "X-Joomla-Token: YOUR_JOOMLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Article via MCP", "articletext": "<p>This content was published by an automated workflow!</p>", "catid": 8, "published": true}' \
  "[https://www.yoursite.com/index.php?task=mcp.create_article](https://www.yoursite.com/index.php?task=mcp.create_article)"

Usando MCP com Ferramentas de Automação de Fluxos de Trabalho

Integração com n8n

1. Crie um Nó HTTP:
   • Adicione um nó de Requisição HTTP ao seu fluxo de trabalho.
     • Defina o Método como POST.
     • Defina a URL como https://<your_joomla_website_url>/index.php.
     • Adicione um parâmetro de consulta: task=mcp.<your_task> (ex.: task=mcp.create_article).
2. Adicione Cabeçalhos:
   • Adicione um cabeçalho: X-Joomla-Token com o valor <your_joomla_api_token>.
3. Adicione o Corpo JSON:
   • Adicione o payload JSON para a tarefa que deseja executar (ex.: criar ou atualizar um artigo).

Integração com Make.com

1. Crie um Cenário:
   • Adicione um módulo HTTP ao seu cenário.
     • Defina o Método como POST.
     • Defina a URL como https://<your_joomla_website_url>/index.php.
2. Adicione Parâmetros de Consulta:
   • Adicione um parâmetro de consulta: task=mcp.<your_task> (ex.: task=mcp.get_article).
3. Adicione Cabeçalhos:
   • Adicione um cabeçalho: X-Joomla-Token com o valor <your_joomla_api_token>.
4. Adicione o Corpo JSON:
   • Adicione o payload JSON para a tarefa que deseja executar.

Mudanças na Versão 2.0

Melhorias Implementadas

1. Consolidação de Tarefas:
   • As tarefas manage_article_state e move_article_to_trash foram consolidadas na tarefa update_article. Agora você pode atualizar conteúdo e estado em uma única chamada.
     • Use {"article_id": 123, "state": -2} para mover para a lixeira, {"article_id": 123, "state": 0} para despublicar, etc.
2. Novos Recursos:
   • Adicionada a tarefa mcp.get_tags para recuperar todas as tags
     • Adicionada a tarefa mcp.info para informações do plugin e status de autenticação
     • Suporte aprimorado de filtragem e paginação para get_articles
3. Arquitetura de Código:
   • Totalmente refatorado com classes de manipulador organizadas
     • Sistema de autenticação aprimorado
     • Melhor tratamento de erros e validação
     • Respostas JSON simplificadas com carimbos de data/hora