Joomla MCP Server

Joomla MCP Server

Sumário

• Introdução
• Recursos
• Requisitos
• Instalação
• Ferramentas Disponíveis
• Considerações de Segurança

Introdução

O servidor Joomla MCP (Model Context Protocol) permite que assistentes de IA, como o Claude, interajam com sites Joomla por meio da API de Web Services do Joomla. Ele fornece ferramentas para gerenciar artigos usando um assistente de IA.

Recursos

• Recuperar todos os artigos de um site Joomla
• Listar todas as categorias de conteúdo
• Criar novos artigos
• Gerenciar estados de artigos (publicado, não publicado, excluído ou arquivado)
• Excluir artigos
• Atualizar artigos (requer tanto introtext quanto fulltext, com uma quebra "Leia mais")

Requisitos

• Python 3.11+
• Joomla 4.x ou 5.x com o plugin da API de Web Services habilitado
• Token Bearer da API para autenticação

Instalação

Criar um Token de API do Joomla

1. Acessar Perfil do Usuário: Faça login na interface de Administração do Joomla e navegue até o menu Usuários, depois selecione Gerenciar.

2. Editar Super Usuário: Encontre e clique na conta de Super Usuário (ou no usuário desejado) para editar o perfil.

3. Gerar Token: Vá para a aba Token de API do Joomla, clique no botão Gerar e copie o token exibido.

Instalar o Projeto/Servidor localmente

1. Clone o repositório:

git clone https://github.com/nasoma/joomla-mcp-server.git
cd joomla-mcp-server

2. Configure um ambiente virtual e instale as dependências usando uv (um gerenciador de dependências Python, veja a documentação do uv). Se o uv estiver instalado, execute:

uv sync 

Instalando no Claude ou outros assistentes de IA

Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "Joomla Articles MCP": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}",
        "run",
        "main.py"
      ],
      "env": {
        "JOOMLA_BASE_URL": "<your_joomla_website_url>",
        "BEARER_TOKEN": "<your_joomla_api_token>"
      }
    }
  }
}

Substitua {{PATH_TO_UV}} pelo caminho para uv (execute which uv para encontrá-lo) e {{PATH_TO_PROJECT}} pelo caminho do diretório do projeto (execute pwd na raiz do repositório).

Ferramentas Disponíveis

1. get_joomla_articles()

Recupera todos os artigos do site Joomla por meio de sua API.

2. get_joomla_categories()

Recupera todas as categorias do site Joomla e as formata em uma lista legível.

3. create_article()

Cria um novo artigo no site Joomla por meio de sua API.

Parâmetros:

• article_text (obrigatório): O conteúdo do artigo (texto simples ou HTML)
• title (opcional): O título do artigo (inferido do conteúdo se não fornecido)
• category_id (opcional): O ID da categoria para o artigo
• convert_plain_text (opcional, padrão: True): Converte automaticamente texto simples para HTML
• published (opcional, padrão: True): Publica o artigo imediatamente

4. manage_article_state()

Gerencia o estado de um artigo existente no site Joomla por meio de sua API.

Parâmetros:

• article_id (obrigatório): O ID do artigo existente para verificar e atualizar
• target_state (obrigatório): O estado desejado para o artigo (1=publicado, 0=não publicado, 2=arquivado, -2=excluído)

5. delete_article()

Exclui um artigo do site Joomla por meio de sua API.

Parâmetros:

• article_id (obrigatório): O ID do artigo a ser excluído

6. update_article()

Atualiza um artigo existente no site Joomla por meio de sua API. Tanto introtext quanto fulltext são obrigatórios para alinhar com a estrutura de artigos do Joomla (introtext para o teaser, fulltext para o conteúdo após uma quebra "Leia mais").

Parâmetros:

• article_id (obrigatório): O ID do artigo a ser atualizado
• title (opcional): Novo título para o artigo
• introtext (obrigatório): Texto introdutório para o artigo (texto simples ou HTML)
• fulltext (obrigatório): Conteúdo completo para o artigo (texto simples ou HTML)
• metadesc (opcional): Meta descrição para o artigo

Considerações de Segurança

• O Token de API do Joomla tem acesso ao seu site. Trate-o da mesma forma que trata suas senhas.
• O servidor sanitiza o conteúdo HTML para prevenir ataques XSS
• Garanta que seu site Joomla use HTTPS para proteger as comunicações da API.

Licença

Este projeto está licenciado sob a Licença MIT.