Referência de Ferramentas MCP
O Chinaski embarca um servidor MCP (Model Context Protocol) que expõe as ferramentas de conteúdo, blocos, mídia, build, tema e formulários do seu CMS ao Claude Code e a outros clientes MCP.
Conectando
O servidor MCP conversa com a API REST do seu CMS, então o CMS precisa estar em execução. Você precisa de uma chave de API com permissão de escrita (Admin → Settings → API Keys), então definir duas variáveis para o servidor:
CHINASKI_API_URL: URL base do seu CMS (para a instância local 1:http://localhost:3001)CHINASKI_API_KEY: sua chave de API
A versão do servidor é 1.1.0 e fala JSON-RPC 2.0 sobre stdio. Uma unit systemd (chinaski-mcp@1) está incluída em deploy/ para executá-lo com reinícios automáticos e logs estruturados escritos em logs/mcp-server.log.
Logs: o servidor escreve logs estruturados com rotação diária e mantém os 7 logs diários mais recentes.
Retries: chamadas à API REST do CMS têm retry até 3 vezes com backoff exponencial (1s, 2s, 4s) quando o CMS responde com rate limit (429), indisponibilidade (503) ou outros erros 5xx, ou quando a requisição dá timeout. ping retorna status, versão, uptime do servidor e o resultado do health check do CMS.
Ferramentas de conteúdo
Enumeradas abaixo como tabelas de ferramentas. As tabelas listam o nome de cada ferramenta e o que ela faz.
Páginas e posts
| Ferramenta | O que faz |
|---|---|
list_pages / list_posts | Lista o conteúdo. Retorna uma lista enxuta (o campo body é omitido). limit até 1000, padrão 50; filtre por language. |
get_page / get_post | Busca um por ID. Objeto completo ou 404. |
create_page / create_post | Cria conteúdo. Use {{block:name}} no corpo para incorporar blocos. Páginas suportam sobrescrita de template (por exemplo landing.tt), parent_id para a árvore de páginas, e schedule_publish_at / unpublish_at (ISO 8601, hora local do site). Posts aceitam um slug de category, tags separados por vírgula, uma sobrescrita de published_at e agendamento. |
update_page / update_post | Atualiza por ID. Apenas os campos que você fornecer mudam. |
delete_page / delete_post | Exclusão lógica (soft delete). |
Blocos
| Ferramenta | O que faz |
|---|---|
list_blocks / get_block | Navega pelos blocos (o content_json estruturado é omitido nos resultados de lista). |
create_block | Cria um bloco; o name único é o que você referencia em corpos via {{block:name}}. Tipos válidos: accordion, columns, cta, embed, form, gallery, hero, image, newsletter, promo, quote, stat, table, testimonial, text, video. As opções de estilo incluem cores de fundo/texto/botão, largura de borda, padding, margin e cor/opacidade de overlay (0.0 a 1.0). |
bulk_create_blocks | Cria muitos blocos em uma chamada; erros por item são retornados junto aos sucessos. |
update_block / delete_block | Modifica ou faz exclusão lógica. |
Snippets e categorias
| Ferramenta | O que faz |
|---|---|
list_snippets / get_snippet / create_snippet / update_snippet / delete_snippet | Gerencia snippets de código injetados no head ou body do site. Defina is_global para injetar em toda página; defina privacy_sensitive para marcar um snippet como exigindo consentimento antes de carregar. |
list_categories | Lista as categorias de posts. |
get_category / create_category / update_category / delete_category | Gerencia categorias por ID (as exclusões são lógicas). |
Build
| Ferramenta | O que faz |
|---|---|
trigger_build | Dispara um rebuild do site estático. Retorna dispatched, busy ou missing. |
get_build_status | Retorna a hora do último build e se um build está em execução atualmente. |
O build executa de forma assíncrona: após criar ou atualizar conteúdo, chame trigger_build, e então aguarde com get_build_status: build_in_progress: true significa que ainda está executando.
Formulários
| Ferramenta | O que faz |
|---|---|
list_forms / get_form | Lista e busca formulários (endpoints de webhook/notificação são excluídos desses resultados). |
create_form | Cria um formulário com um nome e slug (o slug é usado em embeds e referências de API). |
update_form | Atualiza configurações do formulário, por exemplo notify_email, reply_to_field ou blocked_countries. Nota: URLs de webhook, thank-you URL e o segredo de webhook não são graváveis através dessas ferramentas. |
delete_form | Exclusão lógica. |
list_form_fields / create_form_field / update_form_field / delete_form_field | Gerencia campos de formulário. Tipos de campo: text, email, tel, textarea, select, checkbox, address, radio, checkboxes, file. Nomes de campo são sanitizados para letras minúsculas, dígitos e underscores. As opções de select/radio/checkboxes são separadas por linha nova. A exibição condicional é definida com condition_field + condition_value; a largura de layout é full ou half. |
Navegação
| Ferramenta | O que faz |
|---|---|
list_nav_items / create_nav_item / update_nav_item / delete_nav_item | Gerencia menus de navegação. Filtre por slot (header ou footer); is_external abre em nova aba; parent_id aninha itens. |
Mídia e documentos
| Ferramenta | O que faz |
|---|---|
list_media | Listagem paginada da biblioteca de mídia, 50 por página. |
get_media | Detalhes da mídia: arquivo, tipo MIME, tamanho, texto alt, pasta, URL, dimensões, legenda, crédito e timestamps. |
update_media | Atualiza apenas metadados: texto alt, legenda, crédito, pasta. |
list_documents | PDFs publicados e arquivos para download, incluindo contagens de downloads. |
get_document | Busca um documento por slug. |
Temas
| Ferramenta | O que faz |
|---|---|
get_theme_guide | Retorna a referência completa de criação de temas do Chinaski como Markdown. Leitura recomendada antes de gerar qualquer arquivo de tema. |
list_themes / clone_theme | Lista temas, ou clona um como ponto de partida (fonte padrão: sbs). |
list_theme_files / read_theme_file | Navega e lê os arquivos .tt de template de um tema. |
write_theme_file | Cria ou sobrescreve um arquivo de template. O conteúdo é escaneado por segurança e validado sintaticamente no lado do servidor antes de ser aceito. |
delete_theme | Apaga um tema e todos os seus arquivos; apenas temas não ativos podem ser apagados. |
Design briefs
| Ferramenta | O que faz |
|---|---|
list_design_briefs | Lista os design briefs enviados (HTML/CSS de referência usados para direção visual). |
read_design_brief_file / list_design_brief_files | Lê os arquivos dentro de um brief pelo seu ID. |
Ferramentas de nível mais alto
Estas combinam várias operações do CMS em uma única chamada:
| Ferramenta | O que faz |
|---|---|
create_post_with_blocks / create_page_with_blocks | Cria conteúdo mais seus blocos em uma chamada; o shortcode {{block:name}} de cada bloco é acrescentado ao corpo automaticamente. |
append_block_to_page / append_block_to_post | Acrescenta {{block:name}} a uma página ou post existente por ID ou slug (ID tem precedência). |
bulk_import | Cria (ou, com upsert: true, cria-ou-atualiza) muitas páginas ou posts a partir de um array, correspondidos por slug + idioma e aplicados atomicamente por item. Opcionalmente dispara um build. |
bulk_update | Atualiza muitas páginas ou posts por ID. |
bulk_create_and_append_blocks | Cria blocos e anexa cada um a uma página em uma chamada. |
translate_content | Busca uma página ou post e cria uma cópia traduzida em um idioma alvo; você fornece o título e o corpo traduzidos, enquanto os campos agnósticos de idioma (imagem destacada, autor e similares) são copiados automaticamente. |
audit_content | Reporta a completude de traduções entre páginas, posts, blocos, snippets, itens de navegação e categorias, listando itens com indicadores MISSING ou STALE. O idioma base tem como padrão en. |
auto_create_translations | Cria stubs de tradução para um item de conteúdo: o registro de origem é copiado para cada idioma não presente como rascunho não publicado. |
submit_job / get_job_status | Para operações muito grandes (200+ itens), envia um job assíncrono em lote (upserts em massa de páginas/posts ou criação de blocos) e aguarda seu progresso. |
Descobrindo o conteúdo do seu site
| Ferramenta | O que faz |
|---|---|
get_site_context | Configuração do site: idiomas, temas, tipos de bloco, categorias com contagens de posts e contagens de conteúdo recente. Cacheado brevemente (5 minutos); passe refresh: true para forçar outra leitura. |
search_content | Busca por palavra-chave entre páginas, posts, blocos, snippets e categorias. |
get_popular_content | Páginas e posts atualizados recentemente, mais novos primeiro. |
get_content_gaps | Audita páginas/posts por meta descrições faltando, corpos vazios ou ausência de imagem destacada. |
get_pages_missing_block_type | Encontra páginas que não referenciam nenhum bloco de um tipo dado (por exemplo cta). |
get_orphaned_blocks | Encontra blocos não referenciados por nenhum corpo de página ou post. |
list_scheduled_pages / list_scheduled_posts | Conteúdo na fila para autopublicação futura, com horários de publicação locais. |
list_redirects | Todos os redirecionamentos, filtráveis por idioma. |
Navegando como recursos
Além das ferramentas, o servidor expõe um grafo de conteúdo navegável através de recursos MCP, que permite a um cliente ler conteúdo antes de mudar qualquer coisa:
page://en/about-us: uma página publicada por idioma/slugpost://en/blog/my-post: um post de blog por idioma/slugblock://en/hero-home: um bloco por idioma/nometheme://library/page.tt: um arquivo de template de tema
Use resources/list, resources/read e resources/templates/list. Snippets não podem ser lidos por URI; use as ferramentas de snippet em vez disso.
Prompts prontos
prompts/list oferece prompts de prateleira:
- Escrever um post de blog no estilo do artigo atualizado mais recentemente
- Auditar todas as páginas e posts por meta descrições faltando
- Listar conteúdo sem imagem destacada
- Identificar as páginas atualizadas mais recentemente com traduções faltando
- Encontrar blocos não referenciados por nenhum corpo de página ou post
- Rascunhar uma nova landing page usando o idioma padrão do site
Histórico de sessões
A maior parte das ferramentas de create/update/delete aceita um argumento context opcional (um ID de sessão). Quando fornecido, cada chamada é registrada e pode ser recuperada depois com get_session_history. Os registros de sessão expiram automaticamente após 24 horas. Senhas, segredos e chaves de API são censurados antes de qualquer coisa ser armazenada.
Padrões de trabalho eficientes
- Para muitos itens de uma vez, prefira as ferramentas em massa:
bulk_import(comupsert: true),bulk_update, oucreate_post_with_blocks/create_page_with_blocksem vez de longas cadeias de criações únicas. - Use
submit_jobpara operações de 200+ itens, e então aguarde comget_job_status. - Depois de mudar conteúdo, lembre-se de que o site é estático: o rebuild só acontece quando você chama
trigger_build.