Feito com Chinaski

Servidor MCP

O Chinaski embarca um servidor Model Context Protocol (MCP) que conecta assistentes de IA como o Claude Code diretamente ao seu CMS: ele expõe a superfície completa de conteúdo do CMS como ferramentas que o assistente pode chamar. O servidor fala JSON-RPC sobre stdio, de modo que seu assistente o lança como um processo local: ele não escuta em nenhuma rede por si mesmo. Esta página explica como configurá-lo, o que ele pode fazer e como ele se comporta.

O que ele pode fazer

CRUD de conteúdo: list/fetch/create/update/delete para páginas, posts, blocos, snippets, categorias, documentos, formulários (e seus campos), mídia, itens de navegação e temas. O escalão coberto na tabela do README é um subconjunto central; o servidor também inclui ferramentas para itens de navegação, mídia, formulários, manipulação de documentos, clonagem de temas, limpeza de blocos órfãos e mais; confira a lista de ferramentas que seu cliente mostra após conectar.

Ferramentas de nível mais alto: criar uma página ou post junto com seus blocos embutidos em uma única chamada (create_page_with_blocks, create_post_with_blocks), traduzir uma página/post para outro idioma, auditar traduções ausentes, importar em massa muitas páginas/posts (com upsert para atualizar por slug+idioma), atualização em massa, criar-e-anexar blocos, e enviar/aguardar jobs assíncronos para operações muito grandes.

Descoberta e análise: get_site_context (idiomas, temas, tipos de bloco, categorias, contagens recentes), busca por palavra-chave nos tipos de conteúdo, relatórios de conteúdo popular e lacunas de conteúdo (meta descrições faltando, corpos vazios, imagens destacadas faltando), além de audit_meta_descriptions e criação automática de traduções.

Recursos: o conteúdo é navegável como recursos como page://en/about-us, post://en/blog/my-post, block://en/hero-home, theme://library/page.tt, antes de mutar qualquer coisa.

Prompts: um conjunto de prompts prontos, por exemplo “Write a blog post in the style of my most popular article”, “Audit all pages for missing meta descriptions”, “Find blocks not referenced by any page or post body”.

Pré-requisitos

  • Uma instância do CMS em execução (serviço chinaski@<N>).
  • Uma chave de API com permissão de escrita, criada em Admin → Settings → API Keys. Chaves de leitura não criam conteúdo.

Setup

Aponte o servidor para o seu CMS com duas variáveis de ambiente obrigatórias:

  • CHINASKI_API_URL: URL base do CMS (por exemplo http://127.0.0.1:3001). O servidor se recusa a iniciar sem ela.
  • CHINASKI_API_KEY: a chave de API acima. Também obrigatória.

Ajustes opcionais:

Variável Padrão Propósito
CHINASKI_MCP_LOG_DIR logs Para onde os logs do servidor vão
CHINASKI_MCP_LOG_FILE <log dir>/mcp-server.log Nome exato do arquivo de log
CHINASKI_MCP_SESSION_DB chinaski-mcp/sessions.db Banco de histórico de sessões
CHINASKI_MCP_SESSION_TTL 86400 (24h) Por quanto tempo os registros de sessão vivem
CHINASKI_MCP_CONTEXT_TTL 300 Tempo de vida do cache de contexto de site (segundos)
CHINASKI_MCP_MAX_RETRIES 3 Tentativas por chamada REST

Uma checagem rápida de sanidade de que o servidor responde a um handshake initialize: ecoe uma requisição initialize JSON-RPC no processo com ambas as variáveis de env obrigatórias definidas e verifique que você recebe um resultado de volta.

Registrando no Claude Code

Uma configuração de exemplo vive no .claude/settings.json do repo: adicione sua URL de API e chave, e recarregue o Claude Code para que o servidor se registre. O registro parece uma entrada mcpServers apontando o servidor chinaski para perl …/chinaski-mcp/chinaski-mcp.pl com as duas variáveis de env acima.

Executando como serviço

deploy/chinaski-mcp@.service executa o servidor sob o systemd por instância e o reinicia automaticamente em caso de falha. A unit aponta os logs para /var/www/chinaski<N>/logs e o banco de sessões para /var/www/chinaski<N>/chinaski-mcp/sessions.db e fornece a URL/chave de /etc/chinaski<N>/mcp-env.

Os logs rotacionam-se diariamente por si mesmos (mcp-server.log.YYYY-MM-DD), com os 7 mais recentes mantidos. Sob o systemd, tudo também vai para o journald.

Sessões, retries e estabilidade

  • Chamadas de ferramentas podem ser marcadas com um argumento context opcional (um ID de sessão). Chamadas marcadas são armazenadas no banco de sessões (senhas, segredos e chaves de API censurados) e podem ser revisadas depois com get_session_history; os registros expiram após o TTL de sessão.
  • Chamadas ao CMS têm retry automático: até as 3 tentativas configuradas com backoff exponencial (1 s, 2 s, 4 s), apenas em respostas 429, 503 e outros 5xx.
  • Os resultados de get_site_context são cacheados por 5 minutos.
  • O handshake ping reporta status, versão e uptime do servidor junto com o resultado de /api/health do CMS.
  • Nomes de ferramenta ou prompt desconhecidos retornam um erro imediatamente, e sites que não existem retornam uma resposta “not found” em vez de crashar.

Trabalhando com conteúdo

Notas do README do projeto que se aplicam hora a hora:

  • Incorpore blocos em corpos de página e post com shortcodes {{block:name}}; o builder estático os resolve em tempo de build.
  • Criar conteúdo não toca no site ao vivo até você disparar um build: chame trigger_build, e então aguarde (poll) get_build_status.
  • Prefira ferramentas em massa (bulk_import com upsert, create_*_with_blocks) a muitas chamadas de item único, e use submit_job para lotes muito grandes (na ordem de centenas de itens).
Leia este site em