Cómo usar cipi/agent en Laravel — proyecto MCP para depuración y seeders
Por Andrea Pollastri · Última actualización: · lectura gratuita, sin muro de pago
SSH en producción para un migrate:status, un vistazo a un trabajo fallido o una seeder de preparación es lento, no se puede compartir y es inútil para un asistente de IA. El paquete oficial Laravel cipi/agent coloca webhooks, controles de estado y, lo que es más útil, un proyecto MCP dentro de la aplicación, para que Cursor pueda leer registros, ejecutar Artisan y consultar la base de datos sobre HTTPS.
- Por qué un agente dentro de la aplicación
- Instalar cipi/agent
- Qué hace realmente el paquete
- Enciende el proyecto MCP
- Conecte el cursor, el código VS o Claude
- Depurar sin SSH
- Seeders, migrar y almacenar en caché a través de artisan
- Un bucle diario que puedes copiar
- Proyecto MCP vs panel API MCP
- Tokens, bloques y privilegios mínimos
- Preguntas frecuentes
Por qué un agente dentro de la aplicación
Cipi ya posee el servidor: Nginx, PHP, bases de datos, SSL, implementaciones sin tiempo de inactividad. Eso es infraestructura. Una aplicación Laravel todavía tiene su propio mundo: modelos Eloquent, seeders, colas Horizon, rotación diaria de registros, el conjunto de migración actual. Una IA que solo ve las conjeturas del repositorio. Una IA que puede llamar a herramientas en elcorriendo La aplicación deja de adivinar.
Para eso está el proyecto MCP. vive en POST /cipi/mcp en el dominio de la aplicación, habla MCP 2024-11-05 durante HTTPS y expone seis herramientas con alcance para eso aplicación. Sin raíz SSH. No hay clave de implementación compartida en el IDE. El asistente pide salud, cruz. laravel.log, corre db:seed --class=RoleSeeder en la puesta en escena y verifica el recuento de filas con db_query.
La verificación de estado y MCP funcionan en cualquier host Laravel 12+. Webhook se implementa y el conjunto de registros completo (nginx, php, worker, deploy) esperar un Cipi-gestionado ambiente. La referencia vive en el Cipi Documentos del agente.
Instalar cipi/agent
Requisitos: PHP 8.3+ y Laravel 12 o 13. El proveedor de servicios descubre automáticamente: abandone config/app.php solo.
$ composer require cipi/agent
$ php artisan cipi:status # config + live DB connectivityEn un Cipi VPS, cipi app create ya inyecta CIPI_APP_USER, CIPI_WEBHOOK_TOKEN y las rutas de implementación. Sólo habilitas los servicios opcionales que desees. Desactivado Cipi, publique la configuración si necesita valores predeterminados diferentes:
$ php artisan vendor:publish --tag=cipi-configComprométete y empuja. La siguiente implementación recoge el paquete. Nada más que cablear en el lado del panel.
Qué hace realmente el paquete
| Característica | Punto final | cuando lo usas |
|---|---|---|
| Webhook implementar | POST /cipi/webhook | GitHub / GitLab escrituras push .deploy-trigger; El implementador se ejecuta como usuario de la aplicación en un minuto |
| control de salud | GET /cipi/health | UptimeRobot / Grafana: aplicación, base de datos, caché, acumulación de cola, última confirmación |
| Proyecto MCP | POST /cipi/mcp | Cursor / VS Code / Claude: salud, registros, SQL, Artisan, implementación: esta guía |
| Anonimizador de base de datos | POST /cipi/db | Volcados seguros para GDPR para control de calidad/local, transformaciones Faker, descarga firmada de 15 minutos |
Cada función tiene su propio token de portador y se puede desactivar de forma independiente. Vuelve un punto final deshabilitado 404 — no existe, en lo que se refiere a un escáner.
Enciende el proyecto MCP
El servidor MCP está desactivado por defecto. Habilítelo, acuñe un token dedicado y luego imprima los fragmentos del cliente:
$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp
$ php artisan cipi:mcpcipi:mcp imprime las seis herramientas y JSON listo para pegar para Cursor (nativo HTTP), VS Code / Copilot y Claude Desktop (a través de mcp-remote). La ficha aterriza en .env como CIPI_MCP_TOKEN. No reutilice el secreto webhook.
Conecte el cursor, el código VS o Claude
Para Cursor, ponga esto en ~/.cursor/mcp.json (o Configuración → MCP). Reemplace el dominio y el token de su .env:
{
"mcpServers": {
"cipi-myapp": {
"type": "http",
"url": "https://yourdomain.com/cipi/mcp",
"headers": {
"Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
}
}
}
}VS Code 1.102+ utiliza el mismo transporte HTTP en .vscode/mcp.json bajo un servers clave. Claude Desktop necesita el mcp-remote puente stdio — php artisan cipi:mcp imprime ese bloque también.
Nombra el servidor después del usuario de la aplicación (cipi-myapp, cipi-staging). Una aplicación Laravel, una MCP. Si ejecuta puesta en escena y producción, registre dos servidores y diga a cuál se refiere.
Depurar sin SSH
Esta es la parte que cambia el ritmo diario. Te quedas en el IDE. El asistente habla con la aplicación en vivo.
salud: ¿está igualada?
Misma carga útil que GET /cipi/health: versión Laravel, APP_DEBUG, nombre de la base de datos, caché, controlador de cola, trabajos pendientes, última confirmación de implementación. Preguntar: “¿La producción es saludable? ¿Alguna cola atrasada? si checks.app.debug es true en un servidor público, acabas de encontrar un problema sin abrir .env.
logs: últimos errores, no todo el archivo
el logs La herramienta lee las últimas N líneas (50 predeterminadas, máximo 500) y mantiene intactos los seguimientos de la pila. Filtros:
type—laravel,nginx,php,worker,deploylevel—error,warning, … (solo Laravel)search— palabra clave que no distingue entre mayúsculas y minúsculas, p.PaymentFailedo una clase de trabajo
Rotación diaria (laravel-YYYY-MM-DD.log) se detecta automáticamente. Un primer mensaje útil después de un 500: "Muestre los últimos 100 errores Laravel y luego las nginx líneas coincidentes".
db_query - mira, no arruines
Leer: SELECT, SHOW, DESCRIBE, EXPLAIN. Escribe: INSERT, UPDATE, DELETE. Bloqueado: DROP, TRUNCATE, GRANT, REVOKE, E/S de archivos. Los resultados regresan como una tabla ASCII, con un límite de 100 filas: suficiente para confirmar una seeder, no suficiente para volcar la tabla de usuarios.
# after a RoleSeeder on staging
SELECT id, name, created_at FROM roles ORDER BY id;
# did today’s signups land?
SELECT COUNT(*) FROM users WHERE created_at >= CURRENT_DATE;Seeders, migrar y almacenar en caché a través de artisan
el artisan La herramienta es la razón por la que este paquete gana un espacio en un repositorio Laravel. Ejecuta cualquier comando Artisan excepto los de larga duración/interactivos (serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start). Todo lo demás, incluidas las seeders, es presa fácil.
Mensajes que realmente guardan un salto a SSH:
- “Corre
migrate:statusen la puesta en escena”. - “Sólo roles semilla:
db:seed --class=RoleSeeder.” - “Cargar pedidos de demostración con
DemoDataSeeder, entoncesSELECT COUNT(*) FROM orders.” - “
queue:failed¿Algún trabajo estancado desde el último despliegue? - “
cache:clearyoptimize:cleardespués del cambio de configuración”.
no apunte esto a producción y diga "ejecute DatabaseSeeder". migrate:fresh --seed es no en la lista de bloqueados: el paquete lo ejecutará. Utilice seeders con nombre en la preparación y confirme con db_query. Los datos de producción no son un patio de recreo solo porque el transporte es MCP en lugar de SSH.
Un patrón de puesta en escena seguro: una clase de seeder por dispositivo, idempotente cuando sea posible, llamada por su nombre. El asistente dirige la clase, lee la tabla y solo entonces promocionas el mismo seeder a través de CI. Eso es lo opuesto a “desechar la producción y rezar”.
Combínalo con el anonimizador cuando lo local necesita volumen sin PII: anonimice un volcado en forma de producción, cárguelo localmente, mantenga MCP seeders para las pequeñas tablas de referencia (roles, planes, indicadores de características) que cambian en cada sprint.
Un bucle diario que puedes copiar
Tú: Staging healthy? Any pending jobs?
Agente: health → healthy, queue 0, debug false, commit a1b2c3d
Tú: Last Laravel errors, search "InvoiceJob"
Agente: logs type=laravel level=error search=InvoiceJob
→ 1 error, missing column invoices.paid_at
Tú: migrate:status. Is 2026_08_22_add_paid_at pending?
Agente: artisan migrate:status → yes, pending
Tú: After I deploy, seed InvoiceStatusSeeder only.
Agente: deploy → queued
artisan db:seed --class=InvoiceStatusSeeder
db_query SELECT id, name FROM invoice_statuses
→ 4 rowsSin sesión SSH. No copiar y pegar desde storage/logs. La misma conversación funciona para un compañero de equipo que tiene el token MCP y nunca debería tener root en la caja, que es la mayor parte del equipo.
Proyecto MCP vs panel API MCP
Cipi barcos dos MCP servidores. Mezclarlos es el primer error habitual.
Proyecto MCP (cipi/agent) | Panel API MCP (cipi/api) | |
|---|---|---|
| donde | POST /cipi/mcp en el aplicación dominio | POST /mcp en el API vhost |
| Alcance | Una aplicación Laravel: su base de datos, registros, Artisan, bandera de implementación | Todo el servidor: aplicaciones, SSL, bases de datos, PHP, trabajadores |
| Herramientas | 6: salud, app_info, implementación, registros, db_query, artisan | 50+: crea aplicaciones, emite certificados, edita .env, ejecutar como usuario de la aplicación |
| Úselo para | Depurar, seeders, migrar: estado, vista de cola | Aprovisionar, SSL, enumerar cada base de datos, cabina del servidor |
Mantenga ambos en Cursor si lo desea. Pregunta al proyecto MCP sobre esto aplicación; pregunta al panel API MCP para crear el siguiente clon de prueba. el guía de IA basada en especificaciones cubre el circuito más amplio: esta página es la mitad de la aplicación.
Tokens, bloques y privilegios mínimos
- Ficha dedicada.
CIPI_MCP_TOKENNo es el secreto webhook ni la ficha de salud. Si gotea,php artisan cipi:generate-token mcpy reiniciar. Cualquiera que tenga el token puede ejecutar Artisan y escribir SQL (dentro del límite de 100 filas). - Apagado significa 404.
php artisan cipi:service mcp --disableoCIPI_MCP=false. Prefiere esto en producción hasta que realmente necesites conectar el IDE. - Bloqueado Artisan:
serve,tinker,queue:work,queue:listen,schedule:work,horizon,octane:start,reverb:start. - SQL bloqueado:
DROP,TRUNCATE,GRANT,REVOKE, E/S de archivos. - Solo HTTPS, sin SSH. Está bien para un desarrollador que debería implementar e inspeccionar sin
sudo. Sigue siendo un canal privilegiado: trate el token como una contraseña de producción.
Instale el paquete, luego el servidor.
cipi/agent es el compañero Laravel. Cipi es el despliegue gratuito open-source CLI que inyecta el entorno y ejecuta Deployer cuando el webhook o el MCP deploy incendios de herramientas.
Preguntas frecuentes
¿Necesito SSH para usar el proyecto MCP?
No. Una vez que el paquete se implementa y CIPI_MCP está encendido, el IDE habla con https://yourdomain.com/cipi/mcp con la ficha de Portador. Ese es el punto para los compañeros de equipo que nunca deberían iniciar sesión como root.
¿Cuál es la diferencia entre el agente MCP y el Cipi API MCP?
El agente MCP está dentro de una aplicación Laravel (seis herramientas: estado, registros, SQL, Artisan, implementación). El panel API MCP gestiona todo el VPS: crear aplicaciones, SSL, bases de datos, PHP. Utilice el agente para depuración y seeders; utilice el API para aprovisionar.
¿Puedo ejecutar db:seed en producción hasta MCP?
Técnicamente sí - db:seed no está bloqueado. En la práctica, sólo ejecute una seeder revisada y con nombre, y nunca migrate:fresh --seed en datos en vivo. Prefiere la puesta en escena, luego confirma con db_query.
¿Qué comandos Artisan están bloqueados?
serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start. Los procesos interactivos y de larga duración no pertenecen a una llamada a la herramienta HTTP.
¿Funciona cipi/agent sin un servidor Cipi?
Comprobación de estado y MCP sí, en cualquier host Laravel 12+. Se implementa el implementador activado por Webhook y los tipos de registros adicionales esperan el diseño Cipi en /home/<app>/.
¿Cómo puedo rotar una ficha MCP filtrada?
php artisan cipi:generate-token mcp, reinicie la aplicación (o vuelva a cargar PHP-FPM / Octane), actualice ~/.cursor/mcp.json. La vieja ficha muere con el .env reescribir.
