WordPress Author MCP Server

Um servidor MCP baseado em personalidade para WordPress, fornecendo ferramentas adequadas ao papel para gerenciamento de conteúdo.

GitHub
3
Experimente este MCPPatrocinado

Documentação

WordPress Author MCP Server

Um servidor de Model Context Protocol (MCP) baseado em personalidade para WordPress que fornece ferramentas adequadas ao papel para gerenciamento de conteúdo. Este servidor permite que assistentes de IA como Claude criem, editem e gerenciem conteúdo WordPress por meio de interações em linguagem natural.

Propósito e Recursos

  • 🎭 Mapeamento de Ferramentas Baseado em Personalidade: Três modos (Contribuidor/Autor/Administrador) com ferramentas adequadas ao papel
  • 🔧 Operações Semânticas: Ações WordPress de alto nível sem complexidade de API
  • 📁 Fluxo de Trabalho de Sessão de Documento: Edição de arquivos temporários abstraída com identificadores opacos (sem exposição do sistema de arquivos)
  • 🔄 Conversão de Formato Transparente: IA edita Markdown limpo → WordPress recebe HTML formatado
  • ✏️ Edição Flexível Baseada em Linhas: Operações precisas de linha + busca contextual/substituição
  • 🛡️ Permissões Nativas do WordPress: Deixe o WordPress lidar com toda a aplicação de permissões
  • 📝 Gerenciamento de Conteúdo: Criar rascunhos, publicar posts/páginas, agendar conteúdo, gerenciar mídia
  • ⚡ Arquitetura Baseada em Mapa: Configuração JSON para atribuições de ferramentas, sem papéis codificados

Arquitetura Semântica

Este servidor MCP não é apenas um wrapper de API. Ele fornece operações semânticas inteligentes que mapeiam fluxos de trabalho humanos para ações do WordPress, com gerenciamento de estado sofisticado e conversão de formato.

Fluxo de Estado da Sessão de Documento

flowchart TB
    WP[WordPress HTML Post]:::wordpress
    PFE[pull-for-editing]:::operation
    H2M[HTML→Markdown Conversion]:::converter
    DS[Document Session<br/>Handle: abc123]:::session
    LES[Local Edit State<br/>• Clean Markdown<br/>• Line Numbers<br/>• No HTML Entities]:::state
    
    EDL[edit-document-line]:::edit
    IAL[insert-at-line]:::edit
    SR[search-replace]:::edit
    
    MLS[Modified Local State<br/>Multiple Edits Applied]:::state
    STW[sync-to-wordpress]:::operation
    M2H[Markdown→HTML Conversion]:::converter
    WPU[WordPress Update<br/>Single API Call]:::wordpress
    
    WP -->|1| PFE
    PFE --> H2M
    H2M --> DS
    DS --> LES
    LES --> EDL
    LES --> IAL
    LES --> SR
    EDL --> MLS
    IAL --> MLS
    SR --> MLS
    MLS -->|2| STW
    STW --> M2H
    M2H --> WPU
    
    classDef wordpress fill:#1e40af,stroke:#3730a3,color:#ffffff
    classDef operation fill:#059669,stroke:#047857,color:#ffffff
    classDef converter fill:#7c3aed,stroke:#6d28d9,color:#ffffff
    classDef session fill:#ea580c,stroke:#dc2626,color:#ffffff
    classDef state fill:#0891b2,stroke:#0e7490,color:#ffffff
    classDef edit fill:#64748b,stroke:#475569,color:#ffffff

Mapeamento de Operação Semântica

flowchart LR
    subgraph "Human Intent"
        H1[I want to write about MCP servers]:::human
        H2[Fix that typo in my article]:::human
        H3[What do people think of my post?]:::human
    end
    
    subgraph "AI Intent"
        AI1[Create article]:::intent
        AI2[Edit my post]:::intent
        AI3[Review feedback]:::intent
    end
    
    subgraph "Semantic Operations"
        SO1[draft-article]:::semantic
        SO2[pull-for-editing<br/>+ edit-document<br/>+ sync-to-wordpress]:::semantic
        SO3[view-editorial-feedback]:::semantic
    end
    
    subgraph "WordPress API"
        API1[POST /wp/v2/posts<br/>+ Category lookups<br/>+ Tag creation<br/>+ Status setting]:::api
        API2[GET /wp/v2/posts/:id<br/>+ GET categories<br/>+ GET tags<br/>+ PUT /wp/v2/posts/:id]:::api
        API3[GET /wp/v2/comments<br/>+ Filter by post_author<br/>+ Parse editorial notes]:::api
    end
    
    H1 --> AI1
    H2 --> AI2
    H3 --> AI3
    
    AI1 --> SO1
    AI2 --> SO2
    AI3 --> SO3
    
    SO1 --> API1
    SO2 --> API2
    SO3 --> API3
    
    classDef human fill:#ec4899,stroke:#db2777,color:#ffffff
    classDef intent fill:#10b981,stroke:#059669,color:#ffffff
    classDef semantic fill:#f59e0b,stroke:#d97706,color:#000000
    classDef api fill:#6366f1,stroke:#4f46e5,color:#ffffff

Principais Componentes Arquiteturais

  1. Gerenciador de Sessão de Documento

    • Mantém sessões de edição com identificadores opacos
    • Nenhum caminho de sistema de arquivos exposto à IA
    • Limpeza automática na sincronização

  2. Camada de Conversão de Formato

    • Turndown: HTML → Markdown (com fallbacks)
    • Marked: Markdown → HTML (com fallbacks)
    • Lida com entidades HTML do WordPress de forma transparente

  3. Mecanismo de Operação Semântica

    • Mapeia intenções de alto nível para fluxos de trabalho do WordPress
    • Agrupa chamadas de API relacionadas
    • Fornece operações semelhantes a transações

  4. Sistema de Edição Baseado em Linhas

    • Operações precisas de número de linha
    • Busca sensível ao contexto dentro de intervalos de linha
    • Evita correspondência de strings frágil

Fluxo de Permissão

flowchart TD
    subgraph "MCP Configuration"
        P1[Contributor Personality]:::personality
        P2[Author Personality]:::personality
        P3[Admin Personality]:::personality
    end
    
    subgraph "Available Tools"
        T1[Limited Tools<br/>draft, edit, submit]:::tools
        T2[Extended Tools<br/>+ publish, media]:::tools
        T3[All Tools<br/>+ bulk ops, categories]:::tools
    end
    
    subgraph "WordPress User"
        U1[Contributor Account]:::user
        U2[Author Account]:::user
        U3[Admin Account]:::user
    end
    
    subgraph "Actual Capabilities"
        C1[Can only draft]:::capability
        C2[Can publish own]:::capability
        C3[Full control]:::capability
    end
    
    P1 --> T1
    P2 --> T2
    P3 --> T3
    
    T1 --> |Filtered by| U1
    T1 --> |Filtered by| U2
    T1 --> |Filtered by| U3
    
    T2 --> |Filtered by| U1
    T2 --> |Filtered by| U2
    T2 --> |Filtered by| U3
    
    T3 --> |Filtered by| U1
    T3 --> |Filtered by| U2
    T3 --> |Filtered by| U3
    
    U1 --> C1
    U2 --> C2
    U3 --> C3
    
    WP[WordPress Always Has<br/>Final Authority]:::wordpress
    C1 --> WP
    C2 --> WP
    C3 --> WP
    
    classDef personality fill:#8b5cf6,stroke:#7c3aed,color:#ffffff
    classDef tools fill:#0ea5e9,stroke:#0284c7,color:#ffffff
    classDef user fill:#f97316,stroke:#ea580c,color:#ffffff
    classDef capability fill:#22c55e,stroke:#16a34a,color:#000000
    classDef wordpress fill:#dc2626,stroke:#b91c1c,color:#ffffff

Pré-requisitos

Antes de usar este servidor MCP, você precisa:

  1. Senha de Aplicativo do WordPress

    • Vá para o admin do seu WordPress: Users > Your Profile > Application Passwords
    • Crie uma nova senha de aplicativo
    • Salve esta senha - você precisará dela para a configuração

  2. Plugin WordPress Feature API

    • Instale o plugin WordPress Feature API
    • Ative o plugin no admin do seu WordPress
    • Isso habilita operações semânticas além da API REST básica

  3. Permissões de Usuário Apropriadas do WordPress

    • O servidor MCP respeita as permissões reais do seu usuário WordPress
    • Personalidade Contribuidor + conta Admin = capacidades de Admin
    • Personalidade Administrador + conta Contribuidor = apenas capacidades de Contribuidor
    • O WordPress sempre tem autoridade final sobre permissões

Início Rápido

Uma vez que os pré-requisitos sejam atendidos:

# Clone and install
git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

# Run interactive setup
npm run setup

O assistente de configuração irá:

  1. Perguntar pela URL do seu site WordPress e credenciais
  2. Ajudar você a escolher uma personalidade padrão (Contribuidor/Autor/Administrador)
  3. Criar seu arquivo de configuração .env
  4. Gerar configurações prontas para colar para Claude Desktop e Claude Code

Importante: A personalidade que você escolher determina quais ferramentas estão disponíveis, mas suas permissões reais de usuário WordPress sempre têm precedência.

Documentação

Como Funciona

  1. Recursos são definidos como módulos independentes em src/features/
  2. Personalidades mapeiam para conjuntos específicos de recursos em config/personalities.json
  3. Na inicialização, especifique uma personalidade para expor apenas suas ferramentas mapeadas
  4. WordPress lida com toda a aplicação real de permissões

Instalação

git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

Configuração

1. Configuração do WordPress

O servidor procura por credenciais nesta ordem:

  1. Variáveis de ambiente (WORDPRESS_URL, WORDPRESS_USERNAME, WORDPRESS_APP_PASSWORD)
  2. Arquivo .env em ~/.wordpress-mcp/ (recomendado para uso global)
  3. Arquivo .env no diretório do servidor (para desenvolvimento)

Opção A: Usar o Assistente de Configuração (Recomendado)

Execute a configuração interativa:

npm run setup

Isso irá:

  • Perguntar onde salvar suas credenciais (global ou local)
  • Coletar os detalhes do seu site WordPress
  • Criar o arquivo .env automaticamente
  • Mostrar configurações prontas para colar

Opção B: Configuração Manual

Crie um arquivo .env em ~/.wordpress-mcp/:

mkdir -p ~/.wordpress-mcp
cat > ~/.wordpress-mcp/.env << EOF
WORDPRESS_URL=https://your-site.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password
EOF

Nota: Use Senhas de Aplicativo para melhor segurança. Gere uma em: Users > Your Profile > Application Passwords no admin do seu WordPress.

2. Configuração do Claude Desktop

Primeiro, garanta que suas credenciais estejam configuradas (execute npm run setup se necessário).

Adicione ao arquivo de configuração do seu Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wordpress-author": {
      "command": "node",
      "args": [
        "/path/to/wordpress-mcp/src/server.js",
        "--personality=author"
      ]
    }
  }
}

O servidor lerá as credenciais do seu arquivo .env.

3. Configuração do Claude Code

Opção A: Usando a CLI (Recomendado)

Primeiro, garanta que seu arquivo .env esteja configurado (execute npm run setup se necessário).

Então, no diretório do seu projeto, execute:

claude mcp add wordpress-author \
  node /path/to/wordpress-mcp/src/server.js -- \
  --personality=author

O servidor lerá as credenciais do arquivo .env no diretório wordpress-mcp.

Opção B: Configuração Manual

Alternativamente, adicione ao .claude/settings.json do seu projeto:

{
  "mcpServers": {
    "wordpress-author": {
      "command": "node",
      "args": [
        "/path/to/wordpress-mcp/src/server.js",
        "--personality=author"
      ]
    }
  }
}

Nota: O servidor lê as credenciais do seu arquivo .env, não da configuração do Claude.

Nota: Ajuste o parâmetro de personalidade (--personality=) para um de:

  • contributor - Ferramentas limitadas para criação de conteúdo
  • author - Capacidades completas de autoria (recomendado)
  • administrator - Gerenciamento completo do site

Uso

Uma vez configurado, as ferramentas WordPress estarão disponíveis no Claude. Você pode:

  • Criar e editar posts e páginas em rascunho
  • Publicar artigos e páginas com opções de agendamento
  • Criar estruturas de página hierárquicas com relações pai-filho
  • Buscar posts usando linguagem natural
  • Puxar posts/páginas para edição com sessões de documento
  • Editar conteúdo usando operações baseadas em linhas
  • Sincronizar alterações de volta em uma única chamada de API
  • Gerenciar arquivos de mídia
  • Realizar operações em massa (somente admin)

Fluxos de Trabalho de Descoberta e Edição de Conteúdo

Exemplos de Busca Semântica:

  • "Encontre meu artigo sobre batatas publicado ontem"
  • "Busque por rascunhos mencionando servidores MCP"
  • "Mostre-me posts sobre IA que precisam de edição"
  • "Encontre artigos publicados com comentários para revisar"

Fluxos de Trabalho em Linguagem Natural:

  • "Encontre meu artigo sobre batatas e atualize a seção de culinária" → IA usa find-posts → sugere pull-for-editing → guia você pelas edições
  • "Revise o feedback no meu tutorial WordPress" → IA busca posts publicados → usa view-editorial-feedback
  • "Edite meu último rascunho sobre APIs semânticas" → IA encontra rascunhos recentes → puxa para edição → ajuda com as alterações

Fluxos de Trabalho Específicos de Página:

  • "Crie uma página Sobre Nós" → IA usa draft-page ou create-page com contexto semântico claro
  • "Faça uma página de Serviços sob a seção principal de Serviços" → IA cria página hierárquica com relação pai
  • "Edite a página de Contato para adicionar novos horários de atendimento" → IA usa pull-for-editing com type: "page"

Operações Diretas Baseadas em ID (quando você sabe o ID):

  • "Puxe o post 42 para edição"
  • "Puxe a página 15 para edição"
  • "Publique o rascunho com ID 30"
  • "Agende o post 55 para a próxima segunda-feira às 9h"

Busca Inteligente com Intenção

A operação find-posts entende o que você quer fazer:

Filtragem baseada em intenção:

  • intent: "edit" → Prioriza rascunhos que você pode modificar
  • intent: "review" → Mostra posts pendentes aguardando aprovação
  • intent: "publish" → Encontra rascunhos prontos para publicar
  • intent: "comment" → Mostra posts publicados com feedback

Orientação de fluxo de trabalho: Cada resultado de busca inclui:

  • Próximas ações sugeridas com base no status do post
  • Instruções claras para o próximo passo
  • Recomendações de ferramentas adequadas ao papel

Exemplo:

"Find posts about baking I can edit"
→ Returns drafts with suggested actions: ["pull-for-editing", "submit-for-review"]
→ Guidance: "📝 Use 'pull-for-editing' with a post ID to start editing..."

Recursos de Edição de Documento

🔄 Conversão de Formato Transparente:

  • HTML do WordPress → Markdown limpo para edição pela IA
  • IA edita em Markdown → WordPress recebe HTML formatado
  • Preserva negrito, itálico, cabeçalhos, listas e mais
  • Sem entidades HTML ou problemas de codificação

✏️ Ferramentas de Edição Flexíveis:

  • read-document - Visualizar conteúdo com números de linha
  • edit-document-line - Substituir linhas específicas por número
  • insert-at-line - Inserir conteúdo em posições precisas
  • replace-lines - Substituir blocos de múltiplas linhas
  • search-replace - Busca sensível ao contexto com proximidade de linha
  • edit-document - Substituição tradicional de strings (fallback)

Exemplo de Fluxo de Trabalho de Sessão de Documento

1. Pull for editing: pull-for-editing postId=42
   → Returns documentHandle="wp-session-abc123" (no filesystem paths!)

2. Read and edit using various methods:
   → read-document documentHandle="wp-session-abc123"
   → edit-document-line lineNumber=5 newLine="Better content"
   → insert-at-line lineNumber=10 content="New paragraph"
   → search-replace searchTerm="old" replacement="new" nearLine=15

3. Sync back:
   → sync-to-wordpress documentHandle="wp-session-abc123"
   → Single WordPress update with all formatting preserved

Principais Benefícios:

  • A IA nunca vê caminhos de sistema de arquivos (segurança + abstração)
  • Edite em Markdown limpo sem problemas de codificação HTML
  • WordPress recebe HTML formatado corretamente automaticamente
  • Edição baseada em linhas evita falhas de correspondência de strings
  • Um puxar → múltiplas edições → um empurrar (eficiência de API)

Mapeamentos de Personalidade

Os mapeamentos de ferramentas são definidos em config/personalities.json:

Contribuidor

Criação de Conteúdo:

  • draft-article - Criar posts em rascunho
  • draft-page - Criar páginas em rascunho para conteúdo estático
  • edit-draft - Editar rascunhos existentes
  • submit-for-review - Enviar rascunhos para revisão editorial
  • view-editorial-feedback - Ver comentários do editor

Fluxo de Trabalho de Sessão de Documento:

  • pull-for-editing - Buscar posts/páginas em sessões de edição
  • read-document - Ler documentos com números de linha
  • edit-document-line - Substituir linhas específicas por número
  • insert-at-line - Inserir conteúdo em posições de linha
  • replace-lines - Substituir intervalos de linhas
  • search-replace - Busca e substituição sensível ao contexto
  • edit-document - Substituição de strings (fallback)
  • sync-to-wordpress - Empurrar todas as alterações de volta
  • list-editing-sessions - Visualizar sessões ativas
  • close-editing-session - Limpeza manual de sessão

Autor

  • Todas as ferramentas do contribuidor, mais:

Publicação:

  • create-article - Criar e publicar posts imediatamente
  • create-page - Criar e publicar páginas com hierarquia
  • publish-workflow - Publicar ou agendar posts
  • manage-media - Enviar e gerenciar arquivos de mídia

Gerenciamento de Conteúdo:

  • trash-own-content - Mover seus próprios posts ou páginas para a lixeira

Administrador

  • Todas as ferramentas do autor, mais:

Gerenciamento do Site:

  • bulk-content-operations - Ações em massa em posts/páginas (lixeira, restaurar, excluir, alterar status)
  • manage-all-content - Visualizar e gerenciar todos os posts
  • review-content - Revisar posts e comentários pendentes
  • moderate-comments - Aprovar, rejeitar ou gerenciar comentários
  • manage-categories - Criar, atualizar e organizar categorias

Editor

  • Todas as ferramentas do autor, mais:

Gerenciamento Editorial:

  • bulk-content-operations - Ações em massa em posts/páginas (lixeira, restaurar, excluir, alterar status)
  • review-content - Revisar posts e comentários pendentes
  • moderate-comments - Aprovar, rejeitar ou gerenciar comentários
  • manage-categories - Criar, atualizar e organizar categorias

Adicionando Personalidades Personalizadas

Edite config/personalities.json para criar mapeamentos de papéis personalizados:

{
  "custom-editor": {
    "name": "Custom Editor",
    "description": "Custom editorial team member",
    "features": ["manage-all-content", "edit-draft", "publish-workflow", "bulk-content-operations"],
    "context": {
      "can_publish": true,
      "can_edit_others": true
    }
  }
}

Então inicie com:

npx wordpress-author-mcp --personality=editor

Personalização

Veja CUSTOMIZATION.md para instruções detalhadas sobre:

  • Criando personalidades personalizadas
  • Adicionando novos recursos
  • Configurando mapeamentos de ferramentas baseados em papéis
  • Exemplos do mundo real (Editor, Revisor, Gerente de Mídias Sociais)

Benefícios da Arquitetura

  1. Sem papéis fixos - Toda a lógica de personalidade vive na configuração
  2. Fácil personalização - Modifique o JSON para alterar a disponibilidade das ferramentas
  3. Autoridade do WordPress - A API impõe as permissões reais
  4. Separação limpa - Os recursos não conhecem as personalidades
  5. Extensível - Adicione recursos e mapeie-os sem tocar no código principal

Tratamento de Permissões do WordPress

O servidor MCP apresenta ferramentas com base na personalidade, mas o WordPress sempre tem a autoridade final:

  • Se um colaborador tentar publicar (via manipulação da API), o WordPress retorna 403
  • Se um autor tentar editar postagens de outros, o WordPress nega
  • O servidor MCP lida com esses erros de forma elegante, com mensagens úteis

Desenvolvimento

# Run in development mode with auto-reload
npm run dev

Licença

MIT