Como usar cipi/agent em Laravel — projeto MCP para depuração e seeders
Por Andrea Pollastri · Última atualização: · grátis para ler, sem acesso pago
SSHing em produção para um migrate:status, uma espiada de trabalho com falha ou um seeder de teste é lento, não compartilhável e inútil para um assistente de IA. O pacote oficial Laravel cipi/agent coloca webhooks, verificações de integridade e - o mais útil - um projeto MCP dentro do aplicativo, para que o Cursor possa ler logs, executar Artisan e consultar o banco de dados em HTTPS.
- Por que um agente dentro do aplicativo
- Instale cipi/agent
- O que o pacote realmente faz
- Ligue o projeto MCP
- Conecte Cursor, VS Code ou Claude
- Depurar sem SSH
- Semeadores, migração e cache via artisan
- Um loop diário que você pode copiar
- Projeto MCP vs painel API MCP
- Tokens, blocos e privilégios mínimos
- Perguntas frequentes
Por que um agente dentro do aplicativo
Cipi já possui o servidor: Nginx, PHP, bancos de dados, SSL, implantações com tempo de inatividade zero. Isso é infraestrutura. Um aplicativo Laravel ainda tem seu próprio mundo — modelos Eloquent, seeders, filas Horizon, rotação diária de logs, o conjunto de migração atual. Uma IA que só vê as suposições do repositório. Uma IA que pode chamar ferramentas nocorrendo o aplicativo para de adivinhar.
É para isso que serve o projeto MCP. Ele mora em POST /cipi/mcp no domínio do aplicativo, fala MCP 05/11/2024 em HTTPS e expõe seis ferramentas com escopo para isso aplicação. Sem SSH raiz. Nenhuma chave de implantação compartilhada no IDE. A assistente pede saúde, coroa laravel.log, corre db:seed --class=RoleSeeder na preparação e verifica a contagem de linhas com db_query.
Verificação de integridade e MCP funcionam em qualquer host Laravel 12+. Webhook implantações e o conjunto completo de logs (nginx, php, worker, deploy) espere um Cipi gerenciado ambiente. A referência mora no Cipi Documentos do agente.
Instale cipi/agent
Requisitos: PHP 8.3+ e Laravel 12 ou 13. O provedor de serviços descobre automaticamente — deixe config/app.php sozinho.
$ composer require cipi/agent
$ php artisan cipi:status # config + live DB connectivityEm um Cipi VPS, cipi app create já injeta CIPI_APP_USER, CIPI_WEBHOOK_TOKEN e os caminhos de implantação. Você ativa apenas os serviços opcionais desejados. Desative Cipi, publique a configuração se precisar de padrões diferentes:
$ php artisan vendor:publish --tag=cipi-configComprometa-se e empurre. A próxima implantação pega o pacote. Nada mais para conectar na lateral do painel.
O que o pacote realmente faz
| Recurso | Ponto final | Quando você usa |
|---|---|---|
| Webhook implantar | POST /cipi/webhook | GitHub / GitLab push escreve .deploy-trigger; O implantador é executado como usuário do aplicativo em um minuto |
| Verificação de saúde | GET /cipi/health | UptimeRobot/Grafana: aplicativo, banco de dados, cache, backlog de fila, último commit |
| Projeto MCP | POST /cipi/mcp | Cursor / VS Code / Claude: integridade, logs, SQL, Artisan, implantação — este guia |
| Anonimizador de banco de dados | POST /cipi/db | Dumps seguros para GDPR para local/QA, transformações Faker, download assinado de 15 minutos |
Cada recurso possui seu próprio token de portador e pode ser desativado de forma independente. Um endpoint desabilitado retorna 404 — não existe, no que diz respeito a um scanner.
Ligue o projeto MCP
O servidor MCP é desativado por padrão. Habilite-o, crie um token dedicado e imprima os snippets do cliente:
$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp
$ php artisan cipi:mcpcipi:mcp imprime as seis ferramentas e JSON prontos para colar para Cursor (nativo HTTP), VS Code/Copilot e Claude Desktop (via mcp-remote). O token cai em .env como CIPI_MCP_TOKEN. Não reutilize o segredo webhook.
Conecte Cursor, VS Code ou Claude
Para Cursor, coloque isso em ~/.cursor/mcp.json (ou Configurações → MCP). Substitua o domínio e o token do seu .env:
{
"mcpServers": {
"cipi-myapp": {
"type": "http",
"url": "https://yourdomain.com/cipi/mcp",
"headers": {
"Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
}
}
}
}O VS Code 1.102+ usa o mesmo transporte HTTP em .vscode/mcp.json sob um servers chave. Claude Desktop precisa do mcp-remote ponte estúdio — php artisan cipi:mcp imprime esse bloco também.
Nomeie o servidor com o nome do usuário do aplicativo (cipi-myapp, cipi-staging). Um aplicativo Laravel, um MCP. Se você executa teste e produção, registre dois servidores e diga qual deles você quer dizer.
Depurar sem SSH
Essa é a parte que muda o ritmo diário. Você permanece no IDE. O assistente fala com o aplicativo ao vivo.
saúde - está bom?
Mesma carga útil que GET /cipi/health: versão Laravel, APP_DEBUG, nome do banco de dados, cache, driver de fila, trabalhos pendentes, última confirmação de implantação. Pergunte: “A produção está saudável? Algum atraso na fila?” Se checks.app.debug é true em um host público, você acabou de encontrar um problema sem abrir .env.
logs – últimos erros, não o arquivo inteiro
O logs A ferramenta lê as últimas N linhas (padrão 50, máximo 500) e mantém os rastreamentos de pilha intactos. Filtros:
type—laravel,nginx,php,worker,deploylevel—error,warning, … (somente Laravel)search— palavra-chave que não diferencia maiúsculas de minúsculas, por ex.PaymentFailedou uma classe de trabalho
Rotação diária (laravel-YYYY-MM-DD.log) é detectado automaticamente. Um primeiro prompt útil após 500: “Mostre os últimos 100 Laravel erros e depois as nginx linhas correspondentes.”
db_query — olhe, não estrague
Leia: SELECT, SHOW, DESCRIBE, EXPLAIN. Escreva: INSERT, UPDATE, DELETE. Bloqueado: DROP, TRUNCATE, GRANT, REVOKE, E/S de arquivo. Os resultados retornam como uma tabela ASCII, limitada a 100 linhas – o suficiente para confirmar um seeder, não o suficiente para descartar a tabela de usuários.
# 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;Semeadores, migração e cache via artisan
O artisan tool é a razão pela qual este pacote ganha um espaço em um repositório Laravel. Ele executa qualquer comando Artisan, exceto os de longa duração/interativos (serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start). Todo o resto – incluindo os seeders – é um jogo justo.
Prompts que realmente salvam um salto no SSH:
- “Corra
migrate:statusna encenação.” - “Apenas funções iniciais:
db:seed --class=RoleSeeder.” - “Carregar pedidos de demonstração com
DemoDataSeeder, entãoSELECT COUNT(*) FROM orders.” - “
queue:failed— algum trabalho travado desde a última implantação?” - “
cache:cleareoptimize:clearapós a alteração da configuração.”
Não aponte isso para a produção e diga “execute o DatabaseSeeder”. migrate:fresh --seed é não na lista de bloqueados — o pacote irá executá-lo. Use seeders nomeados, na preparação, e confirme com db_query. Os dados de produção não são um playground só porque o transporte é MCP em vez de SSH.
Um padrão de teste seguro: uma classe seeder por fixture, idempotente onde possível, chamada pelo nome. O assistente dirige a aula, lê a tabela e só então você promove o mesmo seeder através do CI. Isso é o oposto de “despejar a produção e rezar”.
Combine-o com o anonimizador quando o local precisa de volume sem PII: torne anônimo um dump em formato de produção, carregue-o localmente, mantenha MCP seeders para as pequenas tabelas de referência (funções, planos, sinalizadores de recursos) que mudam a cada sprint.
Um loop diário que você pode copiar
Você: Staging healthy? Any pending jobs?
Agente: health → healthy, queue 0, debug false, commit a1b2c3d
Você: Last Laravel errors, search "InvoiceJob"
Agente: logs type=laravel level=error search=InvoiceJob
→ 1 error, missing column invoices.paid_at
Você: migrate:status. Is 2026_08_22_add_paid_at pending?
Agente: artisan migrate:status → yes, pending
Você: After I deploy, seed InvoiceStatusSeeder only.
Agente: deploy → queued
artisan db:seed --class=InvoiceStatusSeeder
db_query SELECT id, name FROM invoice_statuses
→ 4 rowsNenhuma sessão SSH. Sem copiar e colar de storage/logs. A mesma conversa funciona para um colega de equipe que tem o token MCP e nunca deveria ter root na caixa — que é a maior parte do time.
Projeto MCP vs painel API MCP
Cipi navios dois MCP servidores. Misturá-los é o primeiro erro comum.
Projeto MCP (cipi/agent) | Painel API MCP (cipi/api) | |
|---|---|---|
| Onde | POST /cipi/mcp no aplicativo domínio | POST /mcp no API vhost |
| Escopo | Um aplicativo Laravel: seu banco de dados, logs, Artisan, sinalizador de implantação | Todo o servidor: aplicativos, SSL, bancos de dados, PHP, trabalhadores |
| Ferramentas | 6 — saúde, app_info, implantação, logs, db_query, artisan | Mais de 50 – crie aplicativos, emita certificados, edite .env, execute como usuário do aplicativo |
| Use-o para | Depurar, seeders, migrar: status, espiar fila | Provisionar, SSL, listar todos os bancos de dados, cockpit do servidor |
Mantenha ambos no Cursor, se desejar. Pergunte ao projeto MCP sobre isso aplicativo; pergunte ao painel API MCP para criar o próximo clone de teste. O guia de IA baseado em especificações cobre o loop mais amplo – esta página é a metade do aplicativo.
Tokens, blocos e privilégios mínimos
- Token dedicado.
CIPI_MCP_TOKENnão é o segredo webhook e nem a ficha de saúde. Se vazar,php artisan cipi:generate-token mcpe reinicie. Qualquer pessoa com o token pode executar Artisan e escrever SQL (dentro do limite de 100 linhas). - Desligado significa 404.
php artisan cipi:service mcp --disableouCIPI_MCP=false. Prefira isso na produção até que você realmente precise do IDE conectado. - Bloqueado Artisan:
serve,tinker,queue:work,queue:listen,schedule:work,horizon,octane:start,reverb:start. - SQL bloqueado:
DROP,TRUNCATE,GRANT,REVOKE, E/S de arquivo. - Somente HTTPS, sem SSH. Ótimo para um desenvolvedor que deve implantar e inspecionar sem
sudo. Ainda é um canal privilegiado – trate o token como uma senha de produção.
Instale o pacote e depois o servidor
cipi/agent é o companheiro Laravel. Cipi é o open-source implantar CLI gratuito que injeta o env e executa o Deployer quando o webhook ou o MCP deploy ferramenta dispara.
Perguntas frequentes
Preciso de SSH para usar o projeto MCP?
Não. Depois que o pacote for implantado e CIPI_MCP está ativado, o IDE conversa com https://yourdomain.com/cipi/mcp com o token do portador. Esse é o ponto para colegas de equipe que nunca devem fazer login como root.
Qual é a diferença entre o agente MCP e o Cipi API MCP?
O agente MCP está dentro de um aplicativo Laravel (seis ferramentas: health, logs, SQL, Artisan, deploy). O painel API MCP gerencia todo o VPS — criar aplicativos, SSL, bancos de dados, PHP. Use o agente para depuração e seeders; use o API para provisionar.
Posso executar db:seed em produção através de MCP?
Tecnicamente sim - db:seed não está bloqueado. Praticamente, execute apenas um seeder nomeado e revisado e nunca migrate:fresh --seed em dados ao vivo. Prefira a preparação e confirme com db_query.
Quais comandos Artisan estão bloqueados?
serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start. Processos interativos e de longa duração não pertencem a uma chamada de ferramenta HTTP.
O cipi/agent funciona sem um servidor Cipi?
Verificação de integridade e MCP sim, em qualquer host Laravel 12+. As implantações do Deployer acionadas por Webhook e os tipos de log extras esperam o layout Cipi em /home/<app>/.
Como faço para girar um token MCP vazado?
php artisan cipi:generate-token mcp, reinicie o aplicativo (ou recarregue PHP-FPM / Octane), atualize ~/.cursor/mcp.json. O token antigo morre com o .env reescrever.
