Kirby MCP

Kirby MCP

Servidor MCP focado em CLI para projetos Kirby CMS baseados em Composer. Ele permite que um IDE ou agente inspecione seu projeto Kirby (blueprints, templates, plugins, docs) e interaja com um runtime Kirby real. Ele vem com uma base de conhecimento local de conceitos e tarefas do Kirby. Para etapas de instalação específicas de agentes (Claude Code, Codex CLI) e sincronização de Skills, consulte Configuração do cliente.

Ele também pode ser executado como um MCP de referência global sem projeto (kirby-mcp --global) para pesquisa sempre ativa de docs/KB do Kirby. O modo de referência global é intencionalmente separado dos servidores MCP locais do projeto e não pode inspecionar, renderizar, atualizar ou executar comandos em um projeto Kirby.

O servidor usa o despacho de dupla era do MCP SDK v0.8: clientes existentes negociam sessões com estado por meio de initialize, enquanto clientes 2026-07-28 usam solicitações sem estado. Solicitações de registro do MCP não são anunciadas—os diagnósticos são gravados em stderr. Um traceparent W3C v00 válido fornecido por uma solicitação moderna, incluindo o cabeçalho HTTP nativo de clientes de navegador, é incluído para correlação; tracestate e baggage nunca são registrados.

[!WARNING] A injeção de prompt é uma ameaça séria à segurança, especialmente quando usada com documentos recuperados da internet. Você pode não ver isso acontecer ao observar a conversa com o agente!

Início rápido

Na raiz do seu projeto Kirby:

composer require bnomei/kirby-mcp --dev
vendor/bin/kirby-mcp install
vendor/bin/kirby-mcp

Este início rápido é para um servidor MCP stdio local. Se você quiser que o Kirby sirva uma rota HTTP /mcp de produção, instale bnomei/kirby-mcp como uma dependência Composer normal em vez de --dev; consulte Transporte HTTP abaixo.

Em seguida, configure seu cliente MCP (Cursor/Claude Code/Codex CLI) usando os exemplos em Configuração do cliente e copie os Skills incluídos conforme descrito abaixo.

Consulte Configuração do cliente → Claude Code e Configuração do cliente → Codex CLI para etapas de instalação e sincronização de Skills específicas de cada agente.

Modo de Referência Global

Instale uma vez com o Composer e execute o MCP de referência global em qualquer lugar:

composer global require bnomei/kirby-mcp
kirby-mcp --global

Use este modo para pesquisa Kirby sempre disponível: pesquisa KB incluída, glossário, referência de campos/seções do Painel, hooks, extensões, guias de esquema de atualização, pesquisa de docs oficiais e pesquisa de diretório de plugins.

O modo de referência global é sem projeto por design:

• Ele não detecta automaticamente nem aceita --project.
• Ele não expõe ferramentas de projeto/runtime como kirby_roots, kirby_info, kirby_render_page, atualizações de conteúdo, eval/query, instalação de runtime ou geração de helpers de IDE.
• Se você precisar de contexto do projeto ou mutações, adicione um servidor MCP local separado ao projeto com vendor/bin/kirby-mcp.

Exemplos de solicitações copiáveis

Use estes exemplos depois que seu cliente MCP estiver conectado ao servidor.

Planejamento e conteúdo

[!TIP] "Use o Kirby MCP para fazer um plano de..." é uma maneira confiável de fazer seu agente usar as ferramentas e recursos que este servidor MCP fornece. Se você pedir para ele agir, ele tende a editar arquivos diretamente com base em seu treinamento e skills.

Use the Kirby MCP to make a plan to... build a contact form page.

kirby_roots, kirby_blueprint_read, kirby_templates_index, kirby_snippets_index, kirby_controllers_index, kirby_render_page, kirby_dump_log_tail, kirby://config/{option}

Here’s a Kirby MCP–driven plan for a new contact form page in this project:

- Confirm requirements: fields (name/email/message), spam protection (honeypot + csrf()), success UX (inline vs redirect), and whether to store submissions.
- Panel setup: reuse existing blueprint site/blueprints/pages/contact.yml; update site/blueprints/site.yml so the site “pages” section allows creating template contact.
- Create the page: add content/4_contact/contact.txt (or create via Panel once allowed) and fill recipient, subject, success, text.
- Frontend: add site/templates/contact.php + a snippet like site/snippets/contact-form.php (escape all echoed user input; include hidden CSRF field + honeypot).
- Controller: add site/controllers/contact.php to handle POST: check csrf(get('csrf')), validate with invalid(), then send mail via $kirby->email() using replyTo (never use user input as from) and an email template like site/templates/emails/contact.text.php (optional contact.html.php).
- Email config: add site/config/config.php email.transport/email.presets (current kirby://config/email is null).
- Verify with MCP: render the page via kirby_render_page(id='contact', noCache=true); debug with mcp_dump() + kirby_dump_log_tail(traceId=...); inspect blueprint/roots via kirby_blueprint_read(id='pages/contact') and kirby://roots.

Show me the fields available on the home page blueprint and what they do using the MCP.

kirby_blueprint_read, kirby_blueprints_index

Show me the current content of the about page.

kirby_read_page_content

Append " with AI" to the title of the home page with Kirby MCP.

kirby_read_page_content, kirby_update_page_content, kirby://field/text/update-schema

Atalhos de recursos

[!TIP] Sozinhos ou com uma solicitação, os recursos podem ser usados para trazer rapidamente conhecimento e informações de runtime para o contexto atual do seu agente.

kirby://glossary/collection

kirby://glossary/{term}

What is the kirby://config/debug for production?

kirby://config/{option}

Pesquisa e docs

[!TIP] O servidor MCP vem com uma base de conhecimento local sobre o Kirby. Ela consiste em um glossário, tarefas comuns e guias de atualização para campos de conteúdo. Isso reduz a necessidade de depender de recursos externos e é muito rápido.

kirby search for collection filtering

kirby_search

[!TIP] Mas às vezes você ou seu agente precisa se aprofundar. É por isso que o servidor MCP também fornece um fallback para a pesquisa e docs oficiais do Kirby (não incluindo o fórum). Você pode acioná-lo mencionando search online na sua solicitação.

kirby search online for panel permissions

kirby_online

[!TIP] Quando você precisar descobrir plugins de terceiros, também pode pesquisar o diretório oficial de plugins do Kirby e buscar detalhes de cada página de plugin.

kirby search plugins online for e-commerce cart

kirby_online_plugins

[!TIP] Seu agente usará a próxima ferramenta internamente, mas você também pode usá-la para verificar rapidamente o que o servidor MCP sabe sobre um determinado tópico.

What mcp tool should I use to... list plugins?

kirby_tool_suggest

Inventário (runtime + sistema de arquivos)

list blueprints, templates, snippets, collections, controllers, models, plugins, routes, roots

kirby_blueprints_loaded, kirby_blueprints_index, kirby_templates_index, kirby_snippets_index, kirby_collections_index, kirby_controllers_index, kirby_models_index, kirby_plugins_index, kirby_routes_index, kirby_roots

Depuração, tinker/eval e execução de comandos

[!IMPORTANT] A ferramenta kirby_eval está desabilitada por padrão e os comandos CLI são protegidos por uma allowlist/denylist, consulte configuração e segurança abaixo.

kirby MCP tinker $site->index()->count()

kirby_eval

kirby MCP check query site.find('notes').unlisted.count
kirby MCP check query page.siblings.count (model: notes)

kirby_query_dot

run kirby cli command uuid:populate

kirby_run_cli_command

My home page renders incorrectly. Help me debug it with mcp_dump() to return the current $page object.

kirby_render_page, kirby_dump_log_tail, kirby_templates_index, kirby_snippets_index, kirby_controllers_index, kirby_models_index

Capacidades

[!INFO] kirby_init é necessário uma vez por sessão de handshake stdio antes de outras ferramentas. Clientes HTTP podem usar uma nova sessão por chamada de ferramenta, então chamadas HTTP não o exigem; escopos bearer/OAuth permanecem autoritativos. Ele permanece recomendado para auditoria/orientação e opcional para chamadas 2026-07-28 sem estado. Algumas capacidades exigem wrappers de runtime porque consultam o Kirby em tempo de execução.

Na inicialização, o servidor informa ao agente quais ferramentas/recursos usar. A base de conhecimento faz referência cruzada a eles para que o agente possa encontrar o próximo passo.

Inventário atual: 37 ferramentas, 15 recursos, 15 modelos de recursos, 216 artigos de KB.

No modo de referência global (kirby-mcp --global), a superfície exposta é intencionalmente menor: kirby_init, kirby_search, kirby_online, kirby_online_plugins, kirby_tool_suggest e recursos/modelos de referência estáticos (kirby://kb, glossário, campos/seções, hooks, extensões e esquemas de atualização).

Clientes modernos 2026-07-28 recebem dicas de cache público de uma hora para a superfície de descoberta estática de implantação do perfil de referência global e para leituras de índice de KB/referência incluídas em qualquer perfil. Docs buscados externamente e todos os resultados específicos do projeto permanecem privados e imediatamente obsoletos. Resultados de ferramentas que expõem referências concretas de kirby:// em campos estruturados também incluem links de recursos navegáveis para clientes modernos; modelos de URI permanecem apenas como referências estruturadas.

Habilidades

As Habilidades incluídas ficam em vendor/bnomei/kirby-mcp/skills após a instalação. Copie-as para a pasta local de habilidades do seu agente usando as instruções de Configuração do cliente abaixo.

• kirby-project-tour — Inventário e orientação do projeto (raízes, blueprints, plugins) com recomendações de próximos passos.
• kirby-content-migration — Migrações de conteúdo seguras com ferramentas de leitura/atualização em tempo de execução e esquemas de atualização.
• kirby-scaffold-page-type — Estrutura um tipo de página (blueprint + template + controller/modelo opcional) usando as convenções do projeto.
• kirby-routing-and-representations — Rotas personalizadas, redirecionamentos e representações de conteúdo (.json/.xml/.rss).
• kirby-collections-and-navigation — Listagens, paginação, busca, filtragem/ordenação/agrupamento e menus de navegação.
• kirby-panel-and-blueprints — Design de blueprints, UX do Painel, extends e áreas/campos/seções personalizados.
• kirby-plugin-development — Plugins reutilizáveis com hooks/extensões, KirbyTags, blocos e controllers/modelos compartilhados.
• kirby-headless-api — Configuração de API headless com Kirby API, KQL e representações JSON.
• kirby-i18n-workflows — Configuração de idiomas, chaves de tradução, rótulos localizados e fluxos de importação/exportação.
• kirby-security-and-auth — Login/papéis/permissões, restrição de acesso e downloads protegidos.
• kirby-performance-and-media — Ajuste de cache, roteamento de CDN/mídia, imagens responsivas e carregamento preguiçoso.
• kirby-debugging-and-tracing — Reprodução de renderização, rastreamento em tempo de execução com mcp_dump e descoberta de caminhos de código.
• kirby-ide-support — Status do auxiliar de IDE além de melhorias mínimas de PHPDoc/dicas de tipo.
• kirby-upgrade-and-maintenance — Atualizações seguras do Kirby com composer audit, verificações de plugins e validação.
• kirby-forms-and-frontend-actions — Formulários de contato, uploads, emails e criação de páginas no frontend com validação/CSRF.

Configuração do cliente

[!NOTE] A flag --project é opcional quando você executa o servidor a partir da raiz do projeto Kirby. Use-a (ou KIRBY_MCP_PROJECT_ROOT) apenas para servidores MCP locais ao projeto que devem inspecionar um projeto Kirby específico. O stdio baseado em comando é a configuração padrão e recomendada para uso local em IDE/agente. kirby-mcp --global é um servidor de referência separado sem projeto e não deve ser combinado com --project.

Cursor

Adicione em .cursor/mcp.json (projeto) ou ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "kirby-reference": {
      "command": "kirby-mcp",
      "args": ["--global"]
    },
    "kirby-project": {
      "command": "/absolute/path/to/kirby-project/vendor/bin/kirby-mcp"
    }
  }
}

Use kirby-reference para pesquisa de docs/KB que está sempre disponível. Use kirby-project apenas quando esse projeto Kirby específico precisar ser inspecionável ou mutável.

Claude Code

A partir do diretório do projeto Kirby:

claude mcp add kirby -- vendor/bin/kirby-mcp

Servidor de referência global:

claude mcp add kirby-reference -- kirby-mcp --global

Ou explicitamente:

claude mcp add kirby -- vendor/bin/kirby-mcp --project=/absolute/path/to/kirby-project

Copie as Habilidades incluídas (escopo pessoal):

mkdir -p ~/.claude/skills
rsync -a vendor/bnomei/kirby-mcp/skills/ ~/.claude/skills/

Reinicie o Claude Code após copiar (use .claude/skills/ para habilidades com escopo de repositório).

Codex CLI

A partir do diretório do projeto Kirby:

codex mcp add kirby -- vendor/bin/kirby-mcp

Servidor de referência global:

codex mcp add kirby-reference -- kirby-mcp --global

Ou explicitamente:

codex mcp add kirby -- vendor/bin/kirby-mcp --project=/absolute/path/to/kirby-project

Copie as Habilidades incluídas (escopo do usuário):

mkdir -p ~/.codex/skills
rsync -a vendor/bnomei/kirby-mcp/skills/ ~/.codex/skills/

Reinicie o Codex CLI após copiar.

Manual

Inicie o servidor (aponte-o para um projeto Kirby baseado em composer):

• A partir da raiz do projeto Kirby: vendor/bin/kirby-mcp
• Ou explicitamente: vendor/bin/kirby-mcp --project=/absolute/path/to/kirby-project
• Ou como servidor de referência global sem projeto: kirby-mcp --global

Transporte HTTP (opcional)

HTTP está desabilitado por padrão. vendor/bin/kirby-mcp continua executando stdio a menos que você adicione a rota do Kirby e defina "http.enabled": true em .kirby-mcp/mcp.json ou variáveis de ambiente.

Assinaturas modernas de atualização de recursos usam um barramento de sistema de arquivos local limitado de 120 segundos em .kirby-mcp/http-notifications para que workers HTTP separados no mesmo host possam se comunicar. Cada URI assinado requer o mesmo escopo de portador que a leitura desse recurso; assinaturas de conteúdo do projeto exigem kirby-mcp:runtime. Isso não é armazenamento multi-host/NFS e não promete durabilidade ou entrega exatamente uma vez. Chamadas de despejo sem estado devem passar um traceId de renderização explícito ou path de solicitação; apenas sessões de handshake fornecem conveniência de último rastreamento. A elicitação de confirmação é uma interação de segurança do usuário, enquanto os escopos de portador HTTP são autorização; confirm=true explícito permanece suportado.

[!NOTE] HTTP remoto segue o padrão MCP: HTTPS /mcp, autenticação Bearer/OAuth e descoberta de metadados MCP. Os conectores personalizados do Claude Code e Claude Desktop/Claude.ai são os principais alvos testados. Outros clientes compatíveis com MCP podem funcionar se suportarem HTTP MCP remoto e o modo de autenticação configurado. OpenAI/ChatGPT usa MCP por meio de ferramentas da API Responses e ChatGPT Apps/MCP Apps, não o fluxo de URL de conector personalizado do Claude documentado aqui.

Use um modo de autenticação:

Para uma rota do Kirby, instale este pacote como dependência de produção:

composer require bnomei/kirby-mcp

Não o instale com composer require --dev se sua rota /mcp deve funcionar em produção; o runtime PHP de produção deve ser capaz de autoload Bnomei\KirbyMcp\Mcp\KirbyMcpRoutes.

Adicione estas rotas à sua configuração do Kirby, geralmente site/config/config.php:

<?php

use Bnomei\KirbyMcp\Mcp\KirbyMcpRoutes;

return [
    'routes' => [
        ...KirbyMcpRoutes::routes(),
    ],
];

Se sua configuração já define routes, espalhe essas entradas no array de rotas existente em vez de substituí-lo. Nenhuma localização especial de Nginx ou proxy vendor/bin/kirby-mcp é necessária.

O auxiliar de rota adiciona /mcp além dos metadados OAuth opcionais, registro, rotas de autorização/token, JWKS e login. Se você alterar http.path, passe o mesmo caminho para o auxiliar de rota:

'routes' => [
    ...KirbyMcpRoutes::routes('/custom-mcp'),
],

Se você também alterar o caminho do provedor OAuth integrado, passe-o como argumento nomeado:

'routes' => [
    ...KirbyMcpRoutes::routes('/custom-mcp', oauthPath: '/custom-mcp/oauth'),
],

Chamadas de ferramentas HTTP não exigem um kirby_init anterior: clientes remotos podem criar uma nova sessão de handshake para cada chamada. kirby_init permanece disponível e recomendado para auditoria e orientação do projeto. Cada operação HTTP ainda é autorizada independentemente por meio de seus escopos de portador/OAuth.

Fluxos GET SSE têm como padrão uma vida útil de pacote de 300 segundos. O transporte pede ao PHP para estender seu prazo de execução para pouco além dessa vida útil, enquanto o loop do pacote permanece como o limite autoritativo. Se o host desabilitar set_time_limit(), configure PHP/FrankenPHP max_execution_time acima do valor sseMaxSeconds passado para KirbyMcpRoutes::routes().

Coloque os exemplos JSON abaixo no arquivo de configuração MCP do seu projeto Kirby:.kirby-mcp/mcp.json.

[!WARNING] Todas as solicitações /mcp exigem Authorization: Bearer ...; credenciais na string de consulta são rejeitadas. Solicitações de rotas públicas exigem HTTPS, solicitações com cabeçalho Origin devem corresponder a http.allowedOrigins, e cada operação é verificada por escopo. Se a rota estiver registrada, mas http.enabled for falso, ela retorna 404.

Token de loopback local

Use shared-token apenas para desenvolvimento local na mesma máquina:

{
  "http": {
    "enabled": true,
    "path": "/mcp",
    "allowedOrigins": ["http://127.0.0.1:3000"],
    "auth": {
      "mode": "shared-token",
      "token": "replace-with-a-long-random-secret",
      "scopes": ["kirby-mcp:read", "kirby-mcp:runtime", "kirby-mcp:write", "kirby-mcp:execute", "kirby-mcp:admin"]
    }
  }
}

A rota do Kirby rejeita solicitações de token compartilhado a menos que o PHP relate REMOTE_ADDR como loopback e o host da solicitação seja um host de loopback real (localhost, ::1 ou um literal IPv4 válido em 127.0.0.0/8).

Token de portador remoto (recomendado)

Use remote-token para rotas HTTPS públicas quando o cliente puder enviar um token Bearer estático:

{
  "http": {
    "enabled": true,
    "path": "/mcp",
    "allowedOrigins": [],
    "auth": {
      "mode": "remote-token",
      "tokens": [
        {
          "id": "claude-code",
          "hash": "sha256:replace-with-sha256-token-hash",
          "userId": "editor-user",
          "scopes": ["kirby-mcp:read", "kirby-mcp:runtime", "kirby-mcp:write", "kirby-mcp:execute", "kirby-mcp:admin"]
        }
      ]
    }
  }
}

Clientes CLI locais geralmente não enviam cabeçalho Origin, então omita allowedOrigins ou deixe-o vazio. Adicione origens exatas apenas para clientes de navegador ou webview que enviam Origin, por exemplo http://localhost:5173.

Gere o hash do token:

php -r 'echo "sha256:" . hash("sha256", $argv[1]) . PHP_EOL;' 'replace-with-a-long-random-secret'

Ou forneça o token bruto por meio do ambiente:

KIRBY_MCP_HTTP_AUTH_MODE=remote-token
KIRBY_MCP_HTTP_REMOTE_TOKEN=replace-with-a-long-random-secret
KIRBY_MCP_HTTP_REMOTE_TOKEN_ID=claude-code
KIRBY_MCP_HTTP_REMOTE_TOKEN_USER_ID=editor-user
KIRBY_MCP_HTTP_REMOTE_TOKEN_SCOPES=kirby-mcp:read,kirby-mcp:runtime

Use OAuth para conectores personalizados do Claude Desktop/Claude.ai.

Autenticação OAuth (para Claude Desktop/Ai)

Use oauth para conectores personalizados do Claude Desktop/Claude.ai. Nenhum pacote de servidor OAuth separado é necessário para o fluxo integrado do Claude.

Usuários e permissões do Kirby vêm primeiro: OAuth autentica o usuário conectado, enquanto cada token remoto nomeia um usuário Kirby existente. Ambos os modos aplicam o mapa hierárquico de capacidades do Kirby MCP; atualizações dedicadas de página, arquivo, site e usuário também são executadas como esse usuário Kirby. Consulte Permissões e limites do Kirby e o mapa completo de capacidades.

1. Execute vendor/bin/kirby-mcp install (ou update após atualizar) para instalar os comandos de tempo de execução e o adaptador de permissões.
2. Registre KirbyMcpRoutes::routes().
3. Habilite a configuração abaixo e configure as permissões de papel do usuário conectado.
4. Adicione um conector personalizado do Claude com URL do servidor MCP https://example.com/mcp.
5. Adicione o trecho de consentimento apenas se quiser uma tela de aprovação personalizada.

{
  "http": {
    "enabled": true,
    "path": "/mcp",
    "allowedOrigins": ["https://claude.ai"],
    "auth": {
      "mode": "oauth",
      "scopes": ["kirby-mcp:read", "kirby-mcp:runtime", "kirby-mcp:write", "kirby-mcp:execute", "kirby-mcp:admin"]
    },
    "oauthProvider": {
      "enabled": true,
      "path": "/mcp/oauth",
      "consent": "snippet",
      "role": "admin"
    }
  }
}

Com oauthProvider.enabled=true, a rota deriva emissor, público/recursos e URL JWKS da solicitação HTTPS recebida, a menos que você defina http.auth.issuer, http.auth.audience ou http.auth.jwksUri. O estado do provedor é armazenado em .kirby-mcp/oauth, não no cache do Kirby.

O exemplo admite apenas administradores. Para conectar editores, defina http.oauthProvider.role para o nome do papel Kirby existente deles (por exemplo editor), ou "*" para admitir qualquer usuário Kirby autenticado. Esta configuração controla quem pode autorizar uma conexão; ela não atribui ou altera o papel Kirby deles.

[!IMPORTANT] O consentimento padrão é snippet. Um usuário Kirby logado deve aprovar ou negar o cliente antes que o Claude receba um token. Se o usuário não estiver logado, o Kirby MCP armazena a solicitação de autorização em .kirby-mcp/oauth/sessions, redireciona por meio de /mcp/oauth/login e retoma o fluxo OAuth após o login. Use auto apenas para implantações privadas confiáveis.

Para uma tela de aprovação personalizada, crie um novo snippet. O nome padrão do snippet é kirby-mcp/oauth-consent, que mapeia para site/snippets/kirby-mcp/oauth-consent.php em um projeto Kirby. O snippet recebe client, scopes, user, approveUrl, denyUrl e error:

<?php
$clientName = (string) ($client['client_name'] ?? $client['client_id'] ?? 'OAuth client');
$userEmail = (string) ($user?->email() ?? 'Kirby user');
?>

<?php if ($error !== null): ?>
<p><?= esc((string) $error) ?></p>
<?php endif ?>

<form method="post" action="<?= esc((string) $approveUrl, 'attr') ?>">
  <h1>Authorize <?= esc($clientName) ?></h1>
  <p><?= esc($userEmail) ?></p>
  <ul>
    <?php foreach ($scopes as $scope): ?>
    <li><?= esc((string) $scope) ?></li>
    <?php endforeach ?>
  </ul>
  <input type="hidden" name="csrf" value="<?= esc((string) csrf(), 'attr') ?>">
  <button type="submit" name="approve" value="1">Approve</button>
  <button type="submit" name="deny" value="1" formaction="<?= esc((string) $denyUrl, 'attr') ?>">Deny</button>
</form>

O snippet deve enviar POST de volta para a URL de autorização fornecida, incluir um campo csrf gerado pelo helper csrf() do Kirby e enviar approve=1 ou deny=1.

Emissor OAuth/OIDC personalizado

Se você já possui, ou deseja construir, um servidor de autorização OAuth/OIDC separado, mantenha oauthProvider.enabled como falso e configure o emissor, o público/recurso e o URI JWKS você mesmo:

{
  "http": {
    "enabled": true,
    "path": "/mcp",
    "allowedOrigins": ["https://client.example"],
    "auth": {
      "mode": "oauth",
      "issuer": "https://auth.example.test",
      "audience": "https://example.test/mcp",
      "jwksUri": "https://auth.example.test/.well-known/jwks.json",
      "scopes": ["kirby-mcp:read", "kirby-mcp:runtime", "kirby-mcp:write", "kirby-mcp:execute", "kirby-mcp:admin"]
    }
  }
}

O modo OAuth valida tokens de acesso JWT por emissor, público/recurso, assinatura JWKS, expiração e escopos de operação. O Kirby MCP valida os JWTs resultantes para este modo; ele não executa seu servidor de autorização personalizado por você. Um pacote como league/oauth2-server pode ser útil se você construir esse emissor você mesmo, mas ele não é usado pelo provedor OAuth integrado do Claude.

Para todas as operações remotas, um emissor externo deve definir sub do JWT como o ID exato de um usuário Kirby existente neste projeto (não o e-mail ou um ID de conta externa). Não há mapeamento automático de contas ou provisionamento. Assuntos ausentes e usuários desconhecidos/excluídos são rejeitados.

Tokens HTTP são verificados por escopo em cada operação. Os nomes de escopo disponíveis são:

• kirby-mcp:read para ferramentas e recursos somente leitura.
• kirby-mcp:runtime para inspeção de runtime que executa wrappers da CLI do Kirby.
• kirby-mcp:write para mutações de conteúdo/arquivos/usuários/site, ainda exigindo confirmação.
• kirby-mcp:execute para operações de consulta/avaliação, ainda exigindo habilitação e confirmação.
• kirby-mcp:admin para ações administrativas de runtime.

O Composer instala as bibliotecas de runtime HTTP/JWT necessárias pelo próprio Kirby MCP como dependências diretas do pacote; atualizar este pacote é suficiente para consumidores, a menos que sua implantação fixe o Composer com --no-update.

Helpers de IDE (opcional, para humanos)

O agente pode verificar e gerar helpers de IDE para o seu projeto: kirby_ide_helpers_status e kirby_generate_ide_helpers. Você também pode usar os comandos CLI você mesmo.

• Verificar linha de base + atualização: vendor/bin/kirby-mcp ide:status (use --details e --limit=N para mais saída)
• Gerar arquivos de helper regeneráveis: vendor/bin/kirby-mcp ide:generate (o padrão é --dry-run; adicione --write para criar arquivos)
• Saída JSON: --json (marcadores MCP) ou --raw-json (JSON simples)

O que o servidor MCP faz (e não faz)

• Fornece ferramentas/recursos MCP para inspeção de projetos (blueprints, templates/snippets/coleções, controllers/modelos, plugins, rotas, raízes).
• Busca documentação oficial de referência do Kirby e inclui uma base de conhecimento Markdown local (kb/) para consultas rápidas.
• Não modifica seu conteúdo por padrão; ações com capacidade de escrita executadas pelo MCP são protegidas e exigem aceitação/confirmação explícita. Mas seu agente ainda pode fazer o que você permitir!
• Suporta apenas projetos Kirby baseados em Composer (a CLI do Kirby é usada para muitos recursos).

Modelo de segurança

Permissões e limites do Kirby

Conexões OAuth e de token remoto resolvem um usuário Kirby existente e aplicam o mapa de capacidades bnomei.kirby-mcp registrado à descoberta e a cada operação. Cada permissão pai e filha deve ser true; todas as entradas padrão são false para funções personalizadas, enquanto a função nativa admin do Kirby permanece sem restrições. As quatro ferramentas dedicadas de atualização de conteúdo também executam como esse usuário, então as verificações e hooks nativos de mutação do Kirby se aplicam.

Use a configuração de permissões do Kirby:

• Defina permissões de função em site/blueprints/users/<role>.yml.
• Use os hooks de blueprint de modelo options e before para regras específicas do projeto.
• Use uma função personalizada para usuários restritos; a função admin do Kirby permanece sem restrições.

Escopos HTTP permanecem como portões grosseiros de acesso a ferramentas, e confirmações de escrita permanecem obrigatórias. Nenhum deles substitui as permissões do Kirby. Conexões locais stdio e de token compartilhado em loopback permanecem como acesso de operador confiável. Consulte Permissões MCP remotas para configuração de funções e o mapa completo.

Isso é um controle de capacidade, não um isolamento por destino. Conceder uma capacidade de leitura permite todos os destinos suportados por ela. Execução habilitada e permitida de eval ou CLI genérica é execução confiável e pode contornar outras permissões. Identidade, função e revogação de conta são reverificadas a cada solicitação HTTP, mas uma resposta de streaming já aberta não é reautorizada continuamente. Não use este servidor para isolar usuários não confiáveis em um subconjunto privado de um site.

Controles adicionais de execução e transporte

• kirby_run_cli_command é protegido por uma lista de permissões; estenda via .kirby-mcp/mcp.json (cli.allow, cli.allowWrite) e bloqueie via cli.deny.
• Ações com capacidade de escrita exigem aceitação explícita (por exemplo, allowWrite=true ou confirm=true, dependendo da ferramenta).
• kirby_eval está desabilitado por padrão; habilite via KIRBY_MCP_ENABLE_EVAL=1 ou .kirby-mcp/mcp.json ({"eval":{"enabled":true}}) e ainda exige confirmação por chamada (confirm=true ou elicitação no lado do cliente).
• kirby_query_dot está habilitado por padrão; desabilite via .kirby-mcp/mcp.json ({"query":{"enabled":false}}) e ainda exige confirmação por chamada (confirm=true ou elicitação no lado do cliente).
• O transporte HTTP está desabilitado por padrão e nunca deve ser exposto sem autorização de token Bearer.
• A autenticação HTTP de token compartilhado é limitada ao desenvolvimento local. Mantenha o token fora do controle de versão; a rota do Kirby rejeita solicitações de token compartilhado quando REMOTE_ADDR não é loopback ou o host da solicitação não é um host loopback real.
• A autenticação HTTP de token remoto é autenticação pública explícita de token Bearer para clientes com suporte a cabeçalhos. Cada token exige um userId Kirby existente. Armazene hashes na configuração, mantenha tokens brutos em armazenamento de ambiente/segredos, exija HTTPS para solicitações de rota não loopback e escopos de token restritos.
• OAuth continua sendo o caminho de produção preferido para clientes que precisam de um fluxo de autenticação interativo, incluindo conectores personalizados do Claude Desktop e Claude.ai. O provedor integrado opcional está desabilitado por padrão e grava apenas em .kirby-mcp/oauth.
• HTTP valida Origin antes do tratamento do protocolo MCP e rejeita tokens ausentes, malformados, expirados, inválidos ou com escopo insuficiente antes de efeitos colaterais de ferramentas/recursos.
• HTTP expõe apenas o caminho de rota MCP configurado, /mcp por padrão, para tráfego MCP.

O que install / update mudam no seu projeto

vendor/bin/kirby-mcp install:

• Cria .kirby-mcp/mcp.json se nem .kirby-mcp/mcp.json nem .kirby-mcp/config.json existirem.
• Copia wrappers de comando de runtime para a raiz de comandos do Kirby do projeto (geralmente site/commands/mcp/).
• Copia o adaptador de plugin minúsculo index.php, ativos estáticos do Painel (index.js, index.css) e gera seu composer.json somente de metadados na raiz de plugins resolvida (geralmente site/plugins/kirby-mcp/). O servidor e suas dependências permanecem como uma biblioteca em vendor/. O adaptador registra permissões e uma API de atividade do Painel autenticada, não a rota pública de transporte MCP.
• Use --force para sobrescrever arquivos de wrapper existentes.

vendor/bin/kirby-mcp update:

• Sobrescreve os wrappers de runtime e atualiza os metadados do adaptador de plugin copiado (use após atualizar este pacote).
• Cria .kirby-mcp/mcp.json apenas se estiver ausente; não sobrescreverá uma configuração existente.

Para remover tudo:

• Exclua a pasta de wrappers de runtime (site/commands/mcp/ na maioria dos projetos).
• Exclua a pasta do adaptador (site/plugins/kirby-mcp/ na maioria dos projetos).
• Opcionalmente, exclua .kirby-mcp/ (config + caches + arquivos de helper opcionais).

Indicador de atividade opcional do Painel

Habilite isso no .kirby-mcp/mcp.json do seu projeto (ou no config.json existente):

{
  "activity": { "enabled": true }
}

Execute vendor/bin/kirby-mcp update após atualizar para copiar os ativos do Painel e recarregue o Painel. Nenhuma compilação de frontend, folha de estilo personalizada do Painel, URL de status público ou segredo adicional é necessária.

Administradores do Painel veem um pequeno indicador de robô no topo central após uma chamada de ferramenta MCP bem-sucedida ou leitura de recurso:

Passe o mouse, foque ou toque no indicador para ver o tempo decorrido. Ele consulta a cada 15 segundos enquanto a aba do Painel está visível e se oculta em falha de autenticação/rede. Isso indica atividade recente bem-sucedida, não uma conexão aberta, uma operação em execução ou uma contagem de agentes. Inicialização, descoberta, ping, solicitações com falha e consultas do Painel não o atualizam; a própria ferramenta kirby_init conta.

O recurso está desabilitado por padrão. Quando habilitado, chamadas locais stdio e HTTP do projeto compartilham um timestamp em .kirby-mcp/activity; o modo de referência global nunca registra atividade do projeto. O processo MCP e o processo web PHP devem compartilhar este diretório de projeto e ter as permissões de arquivo necessárias. Este é um sinal de melhor esforço, de sistema de arquivos único, não um log de auditoria ou serviço de presença multi-servidor. Mantenha .kirby-mcp/ fora da raiz pública de documentos ou negue acesso web a ele, como para os outros arquivos de estado MCP.

GET /api/kirby-mcp/activity usa a autenticação normal da API do Kirby e exige um administrador Kirby. Ele retorna apenas state e ageSeconds, nunca identidades, nomes de ferramentas, argumentos ou conteúdo. Não há endpoint público ou token embutido em CSS. A integração do Painel usa o hook created do Kirby e um elemento DOM isolado; ela não substitui componentes principais do Painel.

Dumps de depuração (mcp_dump)

Este pacote fornece um helper leve mcp_dump() que anexa JSONL a .kirby-mcp/dumps.jsonl na raiz do projeto.

Redação de segredos: Por padrão, a saída do dump é verificada quanto a dados sensíveis (chaves de API, tokens, senhas, IPs) e redigida antes da gravação. Isso protege contra vazamento acidental de segredos. Configure via dumps.secretPatterns em .kirby-mcp/mcp.json:

{
  "dumps": {
    "secretPatterns": []
  }
}

• Omita secretPatterns → use padrões integrados (chaves OpenAI/Anthropic/GitHub/Stripe/AWS, JWTs, tokens Bearer, IPs, etc.)
• Defina como [] → desabilite a redação completamente
• Defina como ["/pattern1/", "/pattern2/"] → use apenas seus padrões regex personalizados

Fluxo de trabalho típico para seu agente de codificação:

• Adicione mcp_dump($anything) (opcionalmente encadeie ->green(), ->label('...'), ->caller(), ->trace(), ->pass($value)) em qualquer lugar em templates/snippets/controllers.
• Chame kirby_render_page (ele retorna um traceId).
• Chame kirby_dump_log_tail(traceId=...) para recuperar os eventos de dump capturados para essa renderização.

Configuração

A configuração do projeto fica em .kirby-mcp/mcp.json (ou .kirby-mcp/config.json) na raiz do projeto Kirby. Ela é criada por vendor/bin/kirby-mcp install se estiver ausente.

Seleção de host do Kirby:

• Por padrão, a CLI do Kirby executa sem substituição de KIRBY_HOST.
• Para usar configuração Kirby específica do host, defina KIRBY_MCP_HOST (ou KIRBY_HOST) ao iniciar o servidor MCP, ou defina kirby.host em .kirby-mcp/mcp.json:
  • {"kirby":{"host":"localhost"}} | Opção | Tipo | Padrão | Descrição | | ----------------------------------- | ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | cache.ttlSeconds | int | 60 | TTL do cache em memória (segundos) para recursos somente leitura como kirby://commands e kirby://cli/command/{command} além de alguns caches internos (inspeção de raízes, conclusões); defina como 0 para desabilitar o cache. | | docs.ttlSeconds | int | 86400 | TTL do cache em memória (segundos) para documentos markdown buscados de getkirby.com (ex.: kirby://field/{type} e kirby://section/{type}); defina como 0 para desabilitar o cache. | | cli.allow | string[] | [] | Padrões adicionais de lista de permissões para kirby_run_cli_command (suporta curinga *, ex.: plugin:*). | | cli.allowWrite | string[] | [] | Padrões adicionais de lista de permissões para comandos com capacidade de escrita; requer allowWrite=true ao chamar kirby_run_cli_command (suporta *). | | cli.deny | string[] | [] | Padrões de negação que sempre bloqueiam comandos, mesmo se estiverem na lista de permissões (suporta *). | | dumps.enabled | bool | true | Habilita/desabilita gravações de mcp_dump() em .kirby-mcp/dumps.jsonl. | | dumps.maxBytes | int | 2097152 | Tamanho máximo para .kirby-mcp/dumps.jsonl gravado por mcp_dump(). Quando a próxima gravação exceder esse valor, o log é compactado mantendo a metade mais recente das linhas e, em seguida, a nova entrada é anexada. | | dumps.secretPatterns | string[] | (padrões) | Padrões regex para redação de segredos em logs de despejo. Omita para usar os padrões (chaves de API, tokens, IPs, etc.), defina como [] para desabilitar a mascaramento, ou forneça padrões personalizados. | | ide.typeHintScanBytes | int | 16384 | Máximo de bytes a ler de arquivos de controlador/modelo ao detectar dicas de tipo de baseline do Kirby IDE (veja kirby_ide_helpers_status). | | kirby.host | string | null | Host Kirby padrão a passar como KIRBY_HOST para a CLI do Kirby (afeta configuração específica do host como config.{host}.php). | | eval.enabled | bool | false | Habilita kirby_eval / kirby mcp:eval (ainda requer confirmação explícita por chamada). | | query.enabled | bool | true | Habilita kirby_query_dot / kirby mcp:query:dot (ainda requer confirmação explícita por chamada). | | http.enabled | bool | false | Habilita o transporte MCP HTTP Streamable opcional. Stdio permanece o padrão quando isso é falso ou não definido. | | http.host | string | 127.0.0.1 | Host de vinculação para o listener HTTP de baixo nível/verificação de configuração. O modo de token compartilhado requer um host de loopback real; o adaptador de rota Kirby rejeita separadamente autenticação de token compartilhado a menos que tanto REMOTE_ADDR quanto o host da solicitação sejam loopback. | | http.port | int | 8765 | Porta de vinculação para o listener HTTP de baixo nível/verificação de configuração. O adaptador de rota Kirby não usa este campo. | | http.path | string | /mcp | Caminho de endpoint MCP único para solicitações HTTP Streamable. Corresponda isso ao padrão de rota Kirby copiado. | | http.allowedOrigins | string[] | [] | Origens de navegador permitidas para modo HTTP. Configure as origens exatas do cliente que você espera. | | http.auth.mode | string | null | Obrigatório quando HTTP está habilitado: oauth para validação JWT, remote-token para clientes públicos de token portador que podem enviar cabeçalhos, ou shared-token para desenvolvimento local de loopback. | | http.auth.token | string | null | Segredo de token compartilhado para desenvolvimento local. Prefira KIRBY_MCP_HTTP_TOKEN para que segredos fiquem fora do controle de versão. | | http.auth.tokens | array | [] | Registros de token remoto. Cada um precisa de id, hash (sha256:<64-hex>), userId (um ID de usuário Kirby existente) e scopes opcional por token. | | http.auth.issuer | string | null | Emissor OAuth esperado em tokens de acesso JWT. | | http.auth.audience | string | null | Audiência/recursos OAuth esperados em tokens de acesso JWT, geralmente a URL de recurso MCP. | | http.auth.jwksUri | string | null | URI JWKS OAuth usado para verificar assinaturas de tokens de acesso. | | http.auth.scopes | string[] | [] | Escopos de operação aceitos como kirby-mcp:read, kirby-mcp:runtime, kirby-mcp:write, kirby-mcp:execute e kirby-mcp:admin. | | http.oauthProvider.enabled | bool | false | Habilita o servidor de autorização OAuth integrado para conectores personalizados do Claude Desktop/Claude.ai. | | http.oauthProvider.path | string | /mcp/oauth | Prefixo de rota do provedor OAuth integrado. Corresponda isso ao quarto argumento de KirbyMcpRoutes::routes() se você personalizá-lo. | | http.oauthProvider.consent | string | snippet | Modo de consentimento: snippet, always, remember ou auto. auto pula consentimento explícito para usuários Kirby conectados e deve ser usado apenas para implantações privadas confiáveis. | | http.oauthProvider.consentSnippet | string | kirby-mcp/oauth-consent | Snippet Kirby usado quando consent é snippet. | | http.oauthProvider.role | string | admin | Papel do painel necessário para autorizar clientes MCP OAuth. Um usuário conectado sem esse papel é negado (access_denied), então contas de baixo privilégio não podem emitir tokens. Use * para permitir qualquer usuário autenticado do painel (somente loopback/dev). |

Variáveis de ambiente:

Solução de problemas

• “Não foi possível determinar a raiz do projeto Kirby”: execute a partir da raiz do projeto Kirby ou passe --project=/absolute/path (ou defina KIRBY_MCP_PROJECT_ROOT).
• Ferramentas somente em tempo de execução falham: execute vendor/bin/kirby-mcp install e verifique kirby_runtime_status.
• Comando CLI bloqueado: adicione padrões a .kirby-mcp/mcp.json (cli.allow / cli.allowWrite) ou bloqueie com cli.deny.
• Comandos CLI em tempo de execução não conseguem resolver PHP atrás de PHP-FPM/FrankenPHP: instale um PHP_BINDIR/php executável ou defina KIRBY_MCP_PHP_BINARY para o caminho do binário PHP CLI, ex.: /opt/php-x.x/bin/php.
• HTTP SSE fecha antes de sseMaxSeconds: garanta que set_time_limit() esteja habilitado ou defina o max_execution_time do PHP/FrankenPHP do host acima do tempo de vida do stream configurado.
• Configuração específica do host não aplicada: defina KIRBY_MCP_HOST/KIRBY_HOST ou configure {"kirby":{"host":"..."}}.
• Recursos de documentação lentos/falhando: confirme o acesso à rede ou ajuste docs.ttlSeconds (defina como 0 para desabilitar o cache).
• Sem saída de dump: garanta dumps.enabled=true, que um .kirby-mcp/dumps.jsonl exista e use o traceId correto com kirby_dump_log_tail.
• Cliente HTTP recebe 401/403: confirme a autenticação Bearer, audiência/recurso do token, escopos e Origin correspondentes às configurações HTTP definidas.
• Conector personalizado do Claude não consegue conectar: confirme que a URL pública é o endpoint MCP (https://example.com/mcp), que o auxiliar de rota está registrado, http.enabled=true, http.auth.mode=oauth, http.oauthProvider.enabled=true e que requisições não-loopback alcançam o Kirby via HTTPS.

Desenvolvimento

• Instalar dependências: composer install
• Executar testes: composer test
• Executar análise estática: composer analyse

Aviso legal

Este servidor MCP é fornecido "como está", sem garantia. Use-o por sua conta e risco e sempre teste você mesmo antes de usá-lo em um ambiente de produção. Se encontrar algum problema, por favor crie uma nova issue.

Licença

MIT

É desencorajado usar este servidor MCP em qualquer projeto que promova racismo, sexismo, homofobia, abuso animal, violência ou qualquer outra forma de discurso de ódio.