Kirby MCP

Kirby MCP

Servidor MCP orientado a CLI para proyectos Kirby CMS basados en Composer. Permite que un IDE o agente inspeccione tu proyecto Kirby (blueprints, plantillas, plugins, documentación) e interactúe con un runtime Kirby real. Incluye una base de conocimiento local sobre conceptos y tareas de Kirby. Para pasos de instalación específicos por agente (Claude Code, Codex CLI) y sincronización de Skills, consulta Configuración del cliente.

También puede ejecutarse como un MCP de referencia global sin proyecto (kirby-mcp --global) para investigación siempre disponible de documentación/base de conocimiento de Kirby. El modo de referencia global está intencionalmente separado de los servidores MCP locales al proyecto y no puede inspeccionar, renderizar, actualizar ni ejecutar comandos en un proyecto Kirby.

El servidor utiliza el despacho de doble era del SDK MCP v0.8: los clientes existentes negocian sesiones con estado a través de initialize, mientras que los clientes 2026-07-28 utilizan solicitudes sin estado. Las solicitudes de registro de MCP no se anuncian; los diagnósticos se escriben en stderr en su lugar. Un traceparent W3C v00 válido proporcionado por una solicitud moderna, incluido el encabezado HTTP nativo de los clientes de navegador, se incluye para correlación; tracestate y baggage nunca se registran.

[!WARNING] La inyección de prompts es una amenaza de seguridad grave, especialmente cuando se utiliza con documentos recuperados de internet. ¡Es posible que no la veas ocurrir al observar la conversación con el agente!

Inicio rápido

Desde la raíz de tu proyecto Kirby:

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

Este inicio rápido es para un servidor MCP stdio local. Si quieres que Kirby sirva una ruta HTTP de producción /mcp, instala bnomei/kirby-mcp como una dependencia normal de Composer en lugar de --dev; consulta Transporte HTTP a continuación.

Luego configura tu cliente MCP (Cursor/Claude Code/Codex CLI) usando los ejemplos en Configuración del cliente y copia los Skills incluidos como se describe a continuación.

Consulta Configuración del cliente → Claude Code y Configuración del cliente → Codex CLI para pasos de instalación por agente y sincronización de Skills.

Modo de Referencia Global

Instala una vez con Composer y ejecuta el MCP de referencia global en cualquier lugar:

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

Usa este modo para investigación de Kirby siempre disponible: búsqueda en la KB incluida, glosario, referencia de campos/secciones del Panel, hooks, extensiones, guías de actualización de esquemas, búsqueda en la documentación oficial y búsqueda en el directorio de plugins.

El modo de referencia global es sin proyecto por diseño:

• No detecta ni acepta automáticamente --project.
• No expone herramientas de proyecto/runtime como kirby_roots, kirby_info, kirby_render_page, actualizaciones de contenido, eval/query, instalación de runtime o generación de helpers de IDE.
• Si necesitas contexto del proyecto o mutaciones, agrega un servidor MCP local al proyecto con vendor/bin/kirby-mcp.

Ejemplos de solicitudes copiables

Usa estos una vez que tu cliente MCP esté conectado al servidor.

Planificación y contenido

[!TIP] "Usa Kirby MCP para hacer un plan para..." es una forma confiable de lograr que tu agente use las herramientas y recursos que este servidor MCP proporciona. Si le pides que actúe, tiende a editar archivos directamente basándose en su entrenamiento y 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

Atajos de recursos

[!TIP] Ya sea por sí solos o con una solicitud, los recursos se pueden usar para llevar rápidamente conocimiento e información del runtime al contexto actual de tu agente.

kirby://glossary/collection

kirby://glossary/{term}

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

kirby://config/{option}

Búsqueda y documentación

[!TIP] El servidor MCP incluye una base de conocimiento local sobre Kirby. Consiste en un glosario, tareas comunes y guías de actualización para campos de contenido. Esto reduce la necesidad de depender de recursos externos y es muy rápido.

kirby search for collection filtering

kirby_search

[!TIP] Pero a veces tú o tu agente necesitan profundizar más. Por eso el servidor MCP también proporciona un respaldo a la búsqueda y documentación oficial de Kirby (sin incluir el foro). Puedes activarlo mencionando search online en tu solicitud.

kirby search online for panel permissions

kirby_online

[!TIP] Cuando necesites descubrir plugins de terceros, también puedes buscar en el directorio oficial de plugins de Kirby y obtener detalles de cada página de plugin.

kirby search plugins online for e-commerce cart

kirby_online_plugins

[!TIP] Tu agente usará la siguiente herramienta internamente, pero tú también puedes usarla para verificar rápidamente qué sabe el servidor MCP sobre un tema determinado.

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

kirby_tool_suggest

Inventario (runtime + sistema de archivos)

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

Depuración, tinker/eval y ejecución de comandos

[!IMPORTANT] La herramienta kirby_eval está deshabilitada por defecto y los comandos CLI están protegidos por una lista de permitidos/denegados; consulta configuración y seguridad a continuación.

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 es requerido una vez por sesión de handshake stdio antes de otras herramientas. Los clientes HTTP pueden usar una sesión nueva por llamada a herramienta, por lo que las llamadas HTTP no lo requieren; los alcances de bearer/OAuth siguen siendo autoritativos. Sigue siendo recomendado para auditoría/orientación y opcional para llamadas sin estado 2026-07-28. Algunas capacidades requieren envoltorios de runtime porque consultan Kirby en tiempo de ejecución.

En la inicialización, el servidor le dice al agente qué herramientas/recursos usar. La base de conocimiento los referencia cruzadamente para que el agente pueda encontrar el siguiente paso.

Inventario actual: 37 herramientas, 15 recursos, 15 plantillas de recursos, 216 artículos de KB.

En el modo de referencia global (kirby-mcp --global), la superficie expuesta es intencionalmente más pequeña: kirby_init, kirby_search, kirby_online, kirby_online_plugins, kirby_tool_suggest y recursos/plantillas de referencia estáticos (kirby://kb, glosario, campos/secciones, hooks, extensiones y esquemas de actualización).

Los clientes modernos 2026-07-28 reciben sugerencias de caché pública de una hora para la superficie de descubrimiento estática del perfil de referencia global y para lecturas de índices de KB/referencia incluidos en cualquiera de los perfiles. La documentación obtenida externamente y todos los resultados específicos del proyecto permanecen privados e inmediatamente obsoletos. Los resultados de herramientas que exponen referencias concretas de kirby:// en campos estructurados también incluyen enlaces de recursos navegables para clientes modernos; las plantillas de URI siguen siendo solo referencias estructuradas.

Habilidades

Las habilidades incluidas viven en vendor/bnomei/kirby-mcp/skills después de la instalación. Cópialas en la carpeta local de habilidades de tu agente usando las instrucciones de Configuración del cliente a continuación.

• kirby-project-tour — Inventario y orientación del proyecto (raíces, blueprints, plugins) con recomendaciones de próximos pasos.
• kirby-content-migration — Migraciones de contenido seguras con herramientas de lectura/actualización en runtime y esquemas de actualización.
• kirby-scaffold-page-type — Crear un tipo de página (blueprint + plantilla + controlador/modelo opcional) usando las convenciones del proyecto.
• kirby-routing-and-representations — Rutas personalizadas, redirecciones y representaciones de contenido (.json/.xml/.rss).
• kirby-collections-and-navigation — Listados, paginación, búsqueda, filtrado/ordenación/agrupación y menús de navegación.
• kirby-panel-and-blueprints — Diseño de blueprints, UX del Panel, extends y áreas/campos/secciones personalizados.
• kirby-plugin-development — Plugins reutilizables con hooks/extensiones, KirbyTags, bloques y controladores/plantillas compartidos.
• kirby-headless-api — Configuración de API headless con Kirby API, KQL y representaciones JSON.
• kirby-i18n-workflows — Configuración de idiomas, claves de traducción, etiquetas localizadas y flujos de importación/exportación.
• kirby-security-and-auth — Inicio de sesión/roles/permisos, restricción de acceso y descargas protegidas.
• kirby-performance-and-media — Ajuste de caché, enrutamiento de CDN/medios, imágenes responsivas y carga diferida.
• kirby-debugging-and-tracing — Reproducción de renderizado, trazado en runtime con mcp_dump y descubrimiento de rutas de código.
• kirby-ide-support — Estado del asistente de IDE más mejoras mínimas de PHPDoc/tipos.
• kirby-upgrade-and-maintenance — Actualizaciones seguras de Kirby con auditoría de composer, verificación de plugins y validación.
• kirby-forms-and-frontend-actions — Formularios de contacto, subidas, correos electrónicos y creación de páginas en el frontend con validación/CSRF.

Configuración del cliente

[!NOTE] La bandera --project es opcional cuando ejecutas el servidor desde la raíz del proyecto Kirby. Úsala (o KIRBY_MCP_PROJECT_ROOT) solo para servidores MCP locales del proyecto que deban inspeccionar un proyecto Kirby específico. El stdio basado en comandos es la configuración predeterminada y recomendada para uso local con IDE/agente. kirby-mcp --global es un servidor de referencia separado sin proyecto y no debe combinarse con --project.

Cursor

Añade a .cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

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

Usa kirby-reference para investigación de docs/KB que esté siempre disponible. Usa kirby-project solo cuando ese proyecto Kirby específico deba ser inspeccionable o modificable.

Claude Code

Desde el directorio del proyecto Kirby:

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

Servidor de referencia global:

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

O explícitamente:

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

Copia las habilidades incluidas (ámbito personal):

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

Reinicia Claude Code después de copiarlas (usa .claude/skills/ en su lugar para habilidades con ámbito de repositorio).

Codex CLI

Desde el directorio del proyecto Kirby:

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

Servidor de referencia global:

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

O explícitamente:

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

Copia las habilidades incluidas (ámbito de usuario):

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

Reinicia Codex CLI después de copiarlas.

Manual

Inicia el servidor (apúntalo a un proyecto Kirby basado en composer):

• Desde la raíz del proyecto Kirby: vendor/bin/kirby-mcp
• O explícitamente: vendor/bin/kirby-mcp --project=/absolute/path/to/kirby-project
• O como servidor de referencia global sin proyecto: kirby-mcp --global

Transporte HTTP (opcional)

HTTP está deshabilitado por defecto. vendor/bin/kirby-mcp continúa ejecutando stdio a menos que añadas la ruta de Kirby y establezcas "http.enabled": true en .kirby-mcp/mcp.json o variables de entorno.

Las suscripciones modernas de actualización de recursos usan un bus de sistema de archivos local acotado de 120 segundos bajo .kirby-mcp/http-notifications para que los trabajadores HTTP separados en el mismo host puedan comunicarse. Cada URI suscrita requiere el mismo alcance de portador que la lectura de ese recurso; las suscripciones de contenido del proyecto requieren kirby-mcp:runtime. Esto no es almacenamiento multi-host/NFS y no promete durabilidad ni entrega exactamente una vez. Las llamadas de volcado sin estado deben pasar un traceId de renderizado explícito o una path de solicitud; solo las sesiones de handshake proporcionan la conveniencia del último trazado. La elicitación de confirmación es una interacción de seguridad del usuario, mientras que los alcances de portador HTTP son autorización; el confirm=true explícito sigue siendo compatible.

[!NOTE] HTTP remoto sigue el patrón estándar de MCP: HTTPS /mcp, autenticación Bearer/OAuth y descubrimiento de metadatos MCP. Claude Code y los conectores personalizados de Claude Desktop/Claude.ai son los objetivos principales probados. Otros clientes compatibles con MCP pueden funcionar si soportan MCP HTTP remoto y el modo de autenticación configurado. OpenAI/ChatGPT usa MCP a través de las herramientas de Responses API y ChatGPT Apps/MCP Apps, no el flujo de URL de conector personalizado de Claude documentado aquí.

Usa un modo de autenticación:

Para una ruta de Kirby, instala este paquete como dependencia de producción:

composer require bnomei/kirby-mcp

No lo instales con composer require --dev si tu ruta /mcp debe funcionar en producción; el runtime PHP de producción debe poder autocargar Bnomei\KirbyMcp\Mcp\KirbyMcpRoutes.

Añade estas rutas a tu configuración de Kirby, normalmente site/config/config.php:

<?php

use Bnomei\KirbyMcp\Mcp\KirbyMcpRoutes;

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

Si tu configuración ya define routes, extiende estas entradas dentro del array de rutas existente en lugar de reemplazarlo. No se requiere una ubicación especial de Nginx ni un proxy vendor/bin/kirby-mcp.

El helper de ruta añade /mcp más los metadatos OAuth opcionales, registro, rutas de autorización/token, JWKS y de inicio de sesión. Si cambias http.path, pasa la misma ruta al helper de ruta:

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

Si también cambias la ruta del proveedor OAuth integrado, pásala como argumento nombrado:

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

Las llamadas a herramientas HTTP no requieren un kirby_init previo: los clientes remotos pueden crear una nueva sesión de handshake para cada llamada. kirby_init sigue disponible y recomendado para auditoría y orientación del proyecto. Cada operación HTTP sigue autorizándose de forma independiente a través de sus alcances de portador/OAuth.

Los flujos GET de SSE tienen por defecto una vida útil de paquete de 300 segundos. El transporte pide a PHP que extienda su plazo de ejecución ligeramente más allá de esa vida útil, mientras que el bucle de paquetes sigue siendo el límite autoritativo. Si el host deshabilita set_time_limit(), configura max_execution_time de PHP/FrankenPHP por encima del valor sseMaxSeconds pasado a KirbyMcpRoutes::routes().

Pon los ejemplos JSON a continuación en el archivo de configuración MCP de tu proyecto Kirby:.kirby-mcp/mcp.json.

[!WARNING] Todas las solicitudes /mcp requieren Authorization: Bearer ...; las credenciales en la cadena de consulta se rechazan. Las solicitudes de rutas públicas requieren HTTPS, las solicitudes con un encabezado Origin deben coincidir con http.allowedOrigins, y cada operación se verifica por alcance. Si la ruta está registrada pero http.enabled es falso, devuelve 404.

Token de loopback local

Usa shared-token solo para desarrollo local desde la misma 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"]
    }
  }
}

La ruta de Kirby rechaza solicitudes de token compartido a menos que PHP informe REMOTE_ADDR como loopback y el host de la solicitud sea un host de loopback real (localhost, ::1 o un literal IPv4 válido en 127.0.0.0/8).

Token de portador remoto (recomendado)

Usa remote-token para rutas HTTPS públicas cuando el cliente pueda enviar un 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"]
        }
      ]
    }
  }
}

Los clientes CLI locales normalmente no envían un encabezado Origin, así que omite allowedOrigins o déjalo vacío. Añade orígenes exactos solo para clientes de navegador o webview que envíen Origin, por ejemplo http://localhost:5173.

Genera el hash del token:

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

O proporciona el token sin procesar a través del entorno:

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

Usa OAuth en su lugar para conectores personalizados de Claude Desktop/Claude.ai.

Autenticación OAuth (para Claude Desktop/Ai)

Usa oauth para conectores personalizados de Claude Desktop/Claude.ai. No se requiere un paquete de servidor OAuth separado para el flujo integrado de Claude.

Los usuarios y permisos de Kirby son lo primero: OAuth autentica al usuario que se conecta, mientras que cada token remoto nombra a un usuario de Kirby existente. Ambos modos aplican el mapa jerárquico de capacidades de Kirby MCP; las actualizaciones dedicadas de página, archivo, sitio y usuario se ejecutan además como ese usuario de Kirby. Consulta Permisos y límites de Kirby y el mapa completo de capacidades.

1. Ejecuta vendor/bin/kirby-mcp install (o update después de actualizar) para instalar los comandos de runtime y el adaptador de permisos.
2. Registra KirbyMcpRoutes::routes().
3. Habilita la configuración a continuación y configura los permisos de rol del usuario que se conecta.
4. Añade un conector personalizado de Claude con la URL del servidor MCP https://example.com/mcp.
5. Añade el fragmento de consentimiento solo si quieres una pantalla de aprobación 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"
    }
  }
}

Con oauthProvider.enabled=true, la ruta deriva el emisor, la audiencia/recurso y la URL JWKS de la solicitud HTTPS entrante a menos que establezcas http.auth.issuer, http.auth.audience o http.auth.jwksUri. El estado del proveedor se almacena bajo .kirby-mcp/oauth, no en la caché de Kirby.

El ejemplo admite solo administradores. Para conectar editores en su lugar, establece http.oauthProvider.role a su nombre de rol de Kirby existente (por ejemplo editor), o "*" para admitir a cualquier usuario de Kirby autenticado. Esta configuración controla quién puede autorizar una conexión; no asigna ni cambia su rol de Kirby.

[!IMPORTANT] El consentimiento por defecto es snippet. Un usuario de Kirby con sesión iniciada debe aprobar o denegar la solicitud del cliente antes de que Claude obtenga un token. Si el usuario no ha iniciado sesión, Kirby MCP almacena la solicitud de autorización en .kirby-mcp/oauth/sessions, redirige a través de /mcp/oauth/login, y reanuda el flujo OAuth después del inicio de sesión. Usa auto solo para implementaciones privadas de confianza.

Para una pantalla de aprobación personalizada, crea un nuevo snippet. El nombre del snippet por defecto es kirby-mcp/oauth-consent, que se asigna a site/snippets/kirby-mcp/oauth-consent.php en un proyecto de Kirby. El snippet recibe client, scopes, user, approveUrl, denyUrl, y 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>

El snippet debe enviar POST de vuelta a la URL de autorización proporcionada, incluir un campo csrf generado por el helper csrf() de Kirby, y enviar ya sea approve=1 o deny=1.

Emisor OAuth/OIDC personalizado

Si ya tienes, o quieres construir, un servidor de autorización OAuth/OIDC separado, mantén oauthProvider.enabled en falso y configura el emisor, la audiencia/recurso, y la URI JWKS tú mismo:

{
  "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"]
    }
  }
}

El modo OAuth valida los tokens de acceso JWT por emisor, audiencia/recurso, firma JWKS, expiración, y ámbitos de operación. Kirby MCP valida los JWT resultantes para este modo; no ejecuta tu servidor de autorización personalizado por ti. Un paquete como league/oauth2-server puede ser útil si construyes ese emisor tú mismo, pero no es utilizado por el proveedor OAuth integrado de Claude.

Para todas las operaciones remotas, un emisor externo debe establecer el sub del JWT al ID exacto de un usuario de Kirby existente en este proyecto (no su correo electrónico ni un ID de cuenta externa). No hay mapeo automático de cuentas ni aprovisionamiento. Los sujetos faltantes y los usuarios desconocidos/eliminados son rechazados.

Los tokens HTTP se verifican por ámbito en cada operación. Los nombres de ámbito disponibles son:

• kirby-mcp:read para herramientas y recursos de solo lectura.
• kirby-mcp:runtime para inspección de tiempo de ejecución que ejecuta envoltorios de la CLI de Kirby.
• kirby-mcp:write para mutaciones de contenido/archivos/usuarios/sitio, que aún requieren confirmación.
• kirby-mcp:execute para operaciones de tipo consulta/eval, que aún requieren habilitación y confirmación.
• kirby-mcp:admin para acciones administrativas de tiempo de ejecución.

Composer instala las bibliotecas de tiempo de ejecución HTTP/JWT necesarias para Kirby MCP como dependencias directas del paquete; actualizar este paquete es suficiente para los consumidores a menos que tu implementación fije Composer con --no-update.

Ayudas de IDE (opcional, para humanos)

El agente puede tanto verificar como generar ayudas de IDE para tu proyecto: kirby_ide_helpers_status y kirby_generate_ide_helpers. También puedes usar los comandos CLI tú mismo.

• Verificar línea base + frescura: vendor/bin/kirby-mcp ide:status (usa --details y --limit=N para más salida)
• Generar archivos auxiliares regenerables: vendor/bin/kirby-mcp ide:generate (el valor por defecto es --dry-run; agrega --write para crear archivos)
• Salida JSON: --json (marcadores MCP) o --raw-json (JSON plano)

Lo que el servidor MCP hace (y no hace)

• Proporciona herramientas/recursos MCP para inspección de proyectos (blueprints, plantillas/snippets/colecciones, controladores/modelos, plugins, rutas, raíces).
• Obtiene la documentación oficial de referencia de Kirby y envía una base de conocimiento local en Markdown (kb/) para búsquedas rápidas.
• No modifica tu contenido por defecto; las acciones con capacidad de escritura ejecutadas por el MCP están protegidas y requieren aceptación/confirmación explícita. ¡Pero tu agente aún puede hacer lo que le permitas!
• Solo admite proyectos Kirby basados en Composer (la CLI de Kirby se usa para muchas capacidades).

Modelo de seguridad

Permisos y límites de Kirby

Las conexiones OAuth y de token remoto resuelven un usuario de Kirby existente y aplican el mapa de capacidades bnomei.kirby-mcp registrado al descubrimiento y a cada operación. Cada permiso padre y hoja debe ser true; todas las entradas por defecto son false para roles personalizados, mientras que el rol nativo admin de Kirby permanece sin restricciones. Las cuatro herramientas dedicadas de actualización de contenido también se ejecutan como ese usuario, por lo que las verificaciones y hooks de mutación nativos de Kirby se aplican.

Usa la configuración de permisos de Kirby:

• Define permisos de rol en site/blueprints/users/<role>.yml.
• Usa el blueprint de modelo options y los hooks before para reglas específicas del proyecto.
• Usa un rol personalizado para usuarios restringidos; el rol admin de Kirby permanece sin restricciones.

Los ámbitos HTTP siguen siendo puertas de acceso a herramientas de nivel grueso, y las confirmaciones de escritura siguen siendo obligatorias. Ninguno reemplaza los permisos de Kirby. Las conexiones locales stdio y de token compartido loopback siguen siendo acceso de operador de confianza. Consulta Permisos MCP remotos para la configuración de roles y el mapa completo.

Esto es una limitación de capacidades, no un aislamiento por destino. Otorgar una capacidad de lectura permite cada destino soportado por ella. La ejecución habilitada y permitida de eval o CLI genérica es ejecución de confianza y puede omitir otros permisos. La identidad, el rol y la revocación de cuentas se vuelven a verificar en cada solicitud HTTP, pero una respuesta de streaming ya abierta no se reautoriza continuamente. No uses este servidor para aislar usuarios no confiables a un subconjunto privado de un sitio.

Controles adicionales de ejecución y transporte

• kirby_run_cli_command está protegido por una lista de permitidos; extiéndelo vía .kirby-mcp/mcp.json (cli.allow, cli.allowWrite) y bloquea vía cli.deny.
• Las acciones con capacidad de escritura requieren aceptación explícita (por ejemplo, allowWrite=true o confirm=true, dependiendo de la herramienta).
• kirby_eval está deshabilitado por defecto; habilítalo vía KIRBY_MCP_ENABLE_EVAL=1 o .kirby-mcp/mcp.json ({"eval":{"enabled":true}}) y aún requiere confirmación por llamada (confirm=true o elicitación del lado del cliente).
• kirby_query_dot está habilitado por defecto; deshabilítalo vía .kirby-mcp/mcp.json ({"query":{"enabled":false}}) y aún requiere confirmación por llamada (confirm=true o elicitación del lado del cliente).
• El transporte HTTP está deshabilitado por defecto y nunca debe exponerse sin autorización de token Bearer.
• La autenticación HTTP de token compartido está limitada al desarrollo local. Mantén el token fuera del control de versiones; la ruta de Kirby rechaza solicitudes de token compartido cuando REMOTE_ADDR no es loopback o el host de la solicitud no es un host loopback real.
• La autenticación HTTP de token remoto es autenticación pública explícita de token Bearer para clientes con capacidad de encabezados. Cada token requiere un userId de Kirby existente. Almacena hashes en la configuración, mantén los tokens crudos en almacenamiento de entorno/secretos, requiere HTTPS para solicitudes de ruta no loopback, y limita los tokens estrictamente.
• OAuth sigue siendo la ruta de producción preferida para clientes que necesitan un flujo de autenticación interactivo, incluidos Claude Desktop y los conectores personalizados de Claude.ai. El proveedor integrado opcional está deshabilitado por defecto y solo escribe en .kirby-mcp/oauth.
• HTTP valida Origin antes del manejo del protocolo MCP y rechaza tokens faltantes, malformados, expirados, inválidos o con ámbito insuficiente antes de los efectos secundarios de herramientas/recursos.
• HTTP expone solo la ruta MCP configurada, /mcp por defecto, para el tráfico MCP.

Qué cambian install / update en tu proyecto

vendor/bin/kirby-mcp install:

• Crea .kirby-mcp/mcp.json si ni .kirby-mcp/mcp.json ni .kirby-mcp/config.json existen.
• Copia los envoltorios de comandos de tiempo de ejecución en la raíz de comandos de Kirby del proyecto (generalmente site/commands/mcp/).
• Copia el adaptador de plugin diminuto index.php, los assets estáticos del Panel (index.js, index.css), y genera su composer.json solo de metadatos en la raíz de plugins resuelta (generalmente site/plugins/kirby-mcp/). El servidor y sus dependencias permanecen como una biblioteca en vendor/. El adaptador registra permisos y una API de actividad del Panel autenticada, no la ruta pública de transporte MCP.
• Usa --force para sobrescribir archivos de envoltorio existentes.

vendor/bin/kirby-mcp update:

• Sobrescribe los envoltorios de tiempo de ejecución y actualiza los metadatos del adaptador de plugin copiado (úsalo después de actualizar este paquete).
• Crea .kirby-mcp/mcp.json solo si falta; no sobrescribirá una configuración existente.

Para eliminar todo:

• Elimina la carpeta de envoltorios de tiempo de ejecución (site/commands/mcp/ en la mayoría de los proyectos).
• Elimina la carpeta del adaptador (site/plugins/kirby-mcp/ en la mayoría de los proyectos).
• Opcionalmente elimina .kirby-mcp/ (configuración + cachés + archivos auxiliares opcionales).

Indicador de actividad opcional del Panel

Habilítalo en el .kirby-mcp/mcp.json de tu proyecto (o en el config.json existente):

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

Ejecuta vendor/bin/kirby-mcp update después de actualizar para copiar los assets del Panel, luego recarga el Panel. No se necesita compilación de frontend, hoja de estilo personalizada del Panel, URL de estado pública ni secreto adicional.

Los administradores del Panel ven un pequeño indicador de robot en la parte superior central después de una llamada exitosa de herramienta MCP o lectura de recurso:

Pasa el cursor, enfoca o toca el indicador para ver el tiempo transcurrido. Sondea cada 15 segundos mientras la pestaña del Panel está visible y se oculta en fallos de autenticación/red. Esto indica actividad exitosa reciente, no una conexión abierta, una operación en ejecución ni un conteo de agentes. La inicialización, el descubrimiento, el ping, las solicitudes fallidas y el sondeo del Panel no lo actualizan; la herramienta kirby_init en sí cuenta.

La función está deshabilitada por defecto. Cuando está habilitada, las llamadas stdio locales del proyecto y HTTP comparten una marca de tiempo en .kirby-mcp/activity; el modo de referencia global nunca registra actividad del proyecto. El proceso MCP y el proceso web PHP deben compartir este directorio de proyecto y tener los permisos de archivo necesarios. Esta es una señal de mejor esfuerzo de un solo sistema de archivos, no un registro de auditoría ni un servicio de presencia multi-servidor. Mantén .kirby-mcp/ fuera de la raíz pública de documentos o deniega el acceso web a ella, como con los otros archivos de estado MCP.

GET /api/kirby-mcp/activity usa la autenticación normal de API de Kirby y requiere un administrador de Kirby. Devuelve solo state y ageSeconds, nunca identidades, nombres de herramientas, argumentos o contenido. No hay endpoint público ni token incrustado en CSS. La integración del Panel usa el hook created de Kirby y un elemento DOM aislado; no reemplaza los componentes centrales del Panel.

Volcados de depuración (mcp_dump)

Este paquete proporciona un helper ligero mcp_dump() que agrega JSONL a .kirby-mcp/dumps.jsonl en la raíz del proyecto.

Redacción de secretos: Por defecto, la salida del volcado se escanea en busca de datos sensibles (claves API, tokens, contraseñas, IPs) y se redacta antes de escribir. Esto protege contra fugas accidentales de secretos. Configura vía dumps.secretPatterns en .kirby-mcp/mcp.json:

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

• Omite secretPatterns → usa patrones integrados (claves OpenAI/Anthropic/GitHub/Stripe/AWS, JWTs, tokens Bearer, IPs, etc.)
• Establece a [] → deshabilita la redacción por completo
• Establece a ["/pattern1/", "/pattern2/"] → usa solo tus patrones regex personalizados

Flujo de trabajo típico para tu agente de codificación:

• Agrega mcp_dump($anything) (opcionalmente encadena ->green(), ->label('...'), ->caller(), ->trace(), ->pass($value)) en cualquier lugar de plantillas/snippets/controladores.
• Llama a kirby_render_page (devuelve un traceId).
• Llama a kirby_dump_log_tail(traceId=...) para recuperar los eventos de volcado capturados para esa renderización.

Configuración

La configuración del proyecto vive en .kirby-mcp/mcp.json (o .kirby-mcp/config.json) en la raíz del proyecto Kirby. Se crea mediante vendor/bin/kirby-mcp install si falta.

Selección de host de Kirby:

• Por defecto, la CLI de Kirby se ejecuta sin anulación de KIRBY_HOST.
• Para usar la configuración de Kirby específica del host, establece KIRBY_MCP_HOST (o KIRBY_HOST) al iniciar el servidor MCP, o establece kirby.host en .kirby-mcp/mcp.json:
  • {"kirby":{"host":"localhost"}} | Opción | Tipo | Predeterminado | Descripción | | ----------------------------------- | ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | cache.ttlSeconds | int | 60 | TTL de caché en memoria (segundos) para recursos de solo lectura como kirby://commands y kirby://cli/command/{command} además de algunos cachés internos (inspección de raíces, completados); establezca en 0 para deshabilitar el caché. | | docs.ttlSeconds | int | 86400 | TTL de caché en memoria (segundos) para documentos markdown de getkirby.com obtenidos (p. ej. kirby://field/{type} y kirby://section/{type}); establezca en 0 para deshabilitar el caché. | | cli.allow | string[] | [] | Patrones adicionales de lista de permitidos para kirby_run_cli_command (admite comodín *, p. ej. plugin:*). | | cli.allowWrite | string[] | [] | Patrones adicionales de lista de permitidos para comandos con capacidad de escritura; requiere allowWrite=true al llamar a kirby_run_cli_command (admite *). | | cli.deny | string[] | [] | Patrones de denegación que siempre bloquean comandos, incluso si están en la lista de permitidos (admite *). | | dumps.enabled | bool | true | Habilitar/deshabilitar escrituras de mcp_dump() en .kirby-mcp/dumps.jsonl. | | dumps.maxBytes | int | 2097152 | Tamaño máximo para .kirby-mcp/dumps.jsonl escrito por mcp_dump(). Cuando la siguiente escritura lo exceda, el registro se compacta conservando la mitad más nueva de las líneas, y luego se agrega la nueva entrada. | | dumps.secretPatterns | string[] | (predeterminados) | Patrones de expresión regular para redacción de secretos en registros de volcado. Omita para usar los predeterminados (claves de API, tokens, IPs, etc.), establezca en [] para deshabilitar el enmascaramiento, o proporcione patrones personalizados. | | ide.typeHintScanBytes | int | 16384 | Máximo de bytes a leer de archivos de controlador/modelo al detectar sugerencias de tipo de línea base de Kirby IDE (ver kirby_ide_helpers_status). | | kirby.host | string | null | Host Kirby predeterminado para pasar como KIRBY_HOST a la CLI de Kirby (afecta la configuración específica del host como config.{host}.php). | | eval.enabled | bool | false | Habilitar kirby_eval / kirby mcp:eval (aún requiere confirmación explícita por llamada). | | query.enabled | bool | true | Habilitar kirby_query_dot / kirby mcp:query:dot (aún requiere confirmación explícita por llamada). | | http.enabled | bool | false | Habilitar el transporte MCP HTTP Streamable opcional. Stdio sigue siendo el predeterminado cuando esto es falso o no está establecido. | | http.host | string | 127.0.0.1 | Host de enlace para el listener HTTP de bajo nivel/verificación de configuración. El modo de token compartido requiere un host de loopback real; el adaptador de ruta de Kirby rechaza por separado la autenticación de token compartido a menos que tanto REMOTE_ADDR como el host de la solicitud sean loopback. | | http.port | int | 8765 | Puerto de enlace para el listener HTTP de bajo nivel/verificación de configuración. El adaptador de ruta de Kirby no usa este campo. | | http.path | string | /mcp | Ruta de endpoint MCP única para solicitudes HTTP Streamable. Haga coincidir esto con el patrón de ruta de Kirby copiado. | | http.allowedOrigins | string[] | [] | Orígenes de navegador permitidos para modo HTTP. Configure los orígenes de cliente exactos que espera. | | http.auth.mode | string | null | Requerido cuando HTTP está habilitado: oauth para validación JWT, remote-token para clientes públicos de token portador que pueden enviar encabezados, o shared-token para desarrollo local de loopback. | | http.auth.token | string | null | Secreto de token compartido para desarrollo local. Prefiera KIRBY_MCP_HTTP_TOKEN para que los secretos permanezcan fuera del control de versiones. | | http.auth.tokens | array | [] | Registros de token remoto. Cada uno necesita id, hash (sha256:<64-hex>), userId (un ID de usuario Kirby existente), y scopes opcional por token. | | http.auth.issuer | string | null | Emisor OAuth esperado en tokens de acceso JWT. | | http.auth.audience | string | null | Audiencia/recurso OAuth esperado en tokens de acceso JWT, usualmente la URL del recurso MCP. | | http.auth.jwksUri | string | null | URI JWKS de OAuth usada para verificar firmas de tokens de acceso. | | http.auth.scopes | string[] | [] | Ámbitos de operación aceptados como kirby-mcp:read, kirby-mcp:runtime, kirby-mcp:write, kirby-mcp:execute, y kirby-mcp:admin. | | http.oauthProvider.enabled | bool | false | Habilitar el servidor de autorización OAuth integrado para conectores personalizados de Claude Desktop/Claude.ai. | | http.oauthProvider.path | string | /mcp/oauth | Prefijo de ruta del proveedor OAuth integrado. Haga coincidir esto con el cuarto argumento de KirbyMcpRoutes::routes() si lo personaliza. | | http.oauthProvider.consent | string | snippet | Modo de consentimiento: snippet, always, remember, o auto. auto omite el consentimiento explícito para usuarios de Kirby con sesión iniciada y solo debe usarse para implementaciones privadas de confianza. | | http.oauthProvider.consentSnippet | string | kirby-mcp/oauth-consent | Fragmento de Kirby usado cuando consent es snippet. | | http.oauthProvider.role | string | admin | Rol de Panel requerido para autorizar clientes MCP OAuth. Un usuario con sesión iniciada sin este rol es denegado (access_denied), por lo que las cuentas de bajo privilegio no pueden emitir tokens. Use * para permitir cualquier usuario autenticado de Panel (solo loopback/dev). |

Variables de entorno:

Solución de problemas

• "No se puede determinar la raíz del proyecto Kirby": ejecuta desde la raíz del proyecto Kirby o pasa --project=/absolute/path (o establece KIRBY_MCP_PROJECT_ROOT).
• Las herramientas solo de ejecución fallan: ejecuta vendor/bin/kirby-mcp install y verifica kirby_runtime_status.
• Comando CLI bloqueado: agrega patrones a .kirby-mcp/mcp.json (cli.allow / cli.allowWrite) o bloquea con cli.deny.
• Los comandos CLI de ejecución no pueden resolver PHP detrás de PHP-FPM/FrankenPHP: instala un PHP_BINDIR/php ejecutable o establece KIRBY_MCP_PHP_BINARY a la ruta del binario CLI de PHP, p. ej. /opt/php-x.x/bin/php.
• HTTP SSE se cierra antes de sseMaxSeconds: asegúrate de que set_time_limit() esté habilitado o establece el max_execution_time del PHP/FrankenPHP del host por encima de la vida útil configurada del stream.
• Configuración específica del host no aplicada: establece KIRBY_MCP_HOST/KIRBY_HOST o configura {"kirby":{"host":"..."}}.
• Los recursos de documentación son lentos/fallan: confirma el acceso a la red o ajusta docs.ttlSeconds (establécelo a 0 para deshabilitar el caché).
• Sin salida de dump: asegúrate de dumps.enabled=true, que exista un .kirby-mcp/dumps.jsonl y usa el traceId correcto con kirby_dump_log_tail.
• El cliente HTTP obtiene 401/403: confirma la autenticación Bearer, la audiencia/recurso del token, los ámbitos y que Origin coincida con la configuración HTTP.
• El conector personalizado de Claude no puede conectarse: confirma que la URL pública sea el endpoint MCP (https://example.com/mcp), que el helper de ruta esté registrado, http.enabled=true, http.auth.mode=oauth, http.oauthProvider.enabled=true y que las solicitudes no-loopback lleguen a Kirby por HTTPS.

Desarrollo

• Instalar dependencias: composer install
• Ejecutar pruebas: composer test
• Ejecutar análisis estático: composer analyse

Aviso legal

Este servidor MCP se proporciona "tal cual" sin garantía. Úsalo bajo tu propio riesgo y pruébalo siempre tú mismo antes de usarlo en un entorno de producción. Si encuentras algún problema, por favor crea un nuevo issue.

Licencia

MIT

Se desaconseja usar este servidor MCP en cualquier proyecto que promueva racismo, sexismo, homofobia, abuso animal, violencia o cualquier otra forma de discurso de odio.