Comment utiliser cipi/agent en Laravel — projet MCP pour le débogage et les seeders
Par Andrea Pollastri · Dernière mise à jour : · lecture gratuite, pas de paywall
SSH en production pour un migrate:status, un aperçu d'un travail échoué ou un seeder intermédiaire est lent, impossible à partager et inutile pour un assistant IA. Le package officiel Laravel cipi/agent met des webhooks, des contrôles de santé et - le plus utile - un projet MCP dans l'application, afin que Cursor puisse lire les journaux, exécuter Artisan et interroger la base de données via HTTPS.
- Pourquoi un agent dans l'application
- Installer cipi/agent
- Ce que fait réellement le package
- Allumez le projet MCP
- Connectez Curseur, VS Code ou Claude
- Déboguer sans SSH
- Seeders, migration et cache via artisan
- Une boucle quotidienne que vous pouvez copier
- Projet MCP vs panneau API MCP
- Jetons, blocs et moindre privilège
- FAQ
Pourquoi un agent dans l'application
Cipi possède déjà le serveur : Nginx, PHP, bases de données, SSL, déploiements sans temps d'arrêt. C'est l'infrastructure. Une application Laravel a toujours son propre monde : modèles éloquents, seeders, files d'attente Horizon, rotation quotidienne des journaux, ensemble de migration actuel. Une IA qui ne voit que les suppositions du repo. Une IA capable d'appeler des outils sur lecourir l'application arrête de deviner.
C'est à cela que sert le projet MCP. Il vit à POST /cipi/mcp sur le domaine de l'application, parle du MCP 2024-11-05 au HTTPS et expose six outils destinés à que demande. Pas de SSH racine. Aucune clé de déploiement partagée dans l'EDI. L'assistant demande de la santé, des queues laravel.log, court db:seed --class=RoleSeeder lors de la mise en scène et vérifie le nombre de lignes avec db_query.
Bilan de santé et MCP fonctionnent sur n'importe quel hôte Laravel 12+. Webhook déploie et l'ensemble complet des journaux (nginx, php, worker, deploy) attendez-vous à un Cipi-géré environnement. La référence réside dans le Cipi Documents d'agent.
Installer cipi/agent
Exigences : PHP 8.3+ et Laravel 12 ou 13. Le fournisseur de services découvre automatiquement — quittez config/app.php seul.
$ composer require cipi/agent
$ php artisan cipi:status # config + live DB connectivitySur un Cipi VPS, cipi app create injecte déjà CIPI_APP_USER, CIPI_WEBHOOK_TOKEN et les chemins de déploiement. Vous activez uniquement les services optionnels que vous souhaitez. Désactivé Cipi, publiez la configuration si vous avez besoin de valeurs par défaut différentes :
$ php artisan vendor:publish --tag=cipi-configEngagez-vous et poussez. Le prochain déploiement récupère le package. Rien d'autre à câbler côté panneau.
Ce que fait réellement le package
| Caractéristique | Point de terminaison | Quand tu l'utilises |
|---|---|---|
| Webhook déployer | POST /cipi/webhook | GitHub / GitLab écritures push .deploy-trigger; Le déployeur s'exécute en tant qu'utilisateur de l'application en une minute |
| Bilan de santé | GET /cipi/health | UptimeRobot / Grafana : application, base de données, cache, backlog de file d'attente, dernier commit |
| Projet MCP | POST /cipi/mcp | Curseur / VS Code / Claude : santé, logs, SQL, Artisan, déploiement — ce guide |
| Anonymiseur de base de données | POST /cipi/db | Dumps sécurisés par le RGPD pour le contrôle local/QA, les transformations Faker, le téléchargement signé de 15 minutes |
Chaque fonctionnalité possède son propre jeton Bearer et peut être désactivée indépendamment. Un point de terminaison désactivé renvoie 404 — il n'existe pas, en ce qui concerne un scanner.
Allumez le projet MCP
Le serveur MCP est désactivé par défaut. Activez-le, créez un jeton dédié, puis imprimez les extraits du client :
$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp
$ php artisan cipi:mcpcipi:mcp imprime les six outils et les JSON prêts à coller pour Cursor (natif HTTP), VS Code/Copilot et Claude Desktop (via mcp-remote). Le jeton atterrit dans .env comme CIPI_MCP_TOKEN. Ne réutilisez pas le secret webhook.
Connectez Curseur, VS Code ou Claude
Pour le curseur, mettez ceci ~/.cursor/mcp.json (ou Paramètres → MCP). Remplacez le domaine et le token de votre .env:
{
"mcpServers": {
"cipi-myapp": {
"type": "http",
"url": "https://yourdomain.com/cipi/mcp",
"headers": {
"Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
}
}
}
}VS Code 1.102+ utilise le même transport HTTP dans .vscode/mcp.json sous un servers clé. Claude Desktop a besoin du mcp-remote pont stdio — php artisan cipi:mcp imprime également ce bloc.
Nommez le serveur d'après l'utilisateur de l'application (cipi-myapp, cipi-staging). Une Laravel application, une MCP. Si vous exécutez la préparation et la production, enregistrez deux serveurs et dites de lequel vous parlez.
Déboguer sans SSH
C'est la partie qui change le rythme quotidien. Vous restez dans l'IDE. L'assistant parle à l'application en direct.
la santé – est-ce encore en hausse ?
Même charge utile que GET /cipi/health: version Laravel, APP_DEBUG, nom de la base de données, cache, pilote de file d'attente, tâches en attente, dernière validation de déploiement. Demandez : « La production est-elle saine ? Y a-t-il un retard dans la file d’attente ? » Si checks.app.debug est true sur un hébergeur public, vous venez de trouver un problème sans ouvrir .env.
journaux - dernières erreurs, pas le fichier entier
Le logs L'outil lit les N dernières lignes (par défaut 50, max 500) et conserve les traces de pile intactes. Filtres :
type—laravel,nginx,php,worker,deploylevel—error,warning, … (Laravel uniquement)search— mot clé insensible à la casse, par ex.PaymentFailedou une catégorie d'emplois
Rotation quotidienne (laravel-YYYY-MM-DD.log) est détecté automatiquement. Une première invite utile après un 500 : "Affichez les 100 dernières erreurs Laravel, puis les lignes nginx correspondantes."
db_query — écoute, ne détruis pas
Lire : SELECT, SHOW, DESCRIBE, EXPLAIN. Écrivez : INSERT, UPDATE, DELETE. Bloqué : DROP, TRUNCATE, GRANT, REVOKE, fichier E/S. Les résultats reviennent sous forme de table ASCII, limitée à 100 lignes – suffisamment pour confirmer un seeder, pas assez pour vider la table des utilisateurs.
# 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, migration et cache via artisan
Le artisan est la raison pour laquelle ce package gagne une place dans un dépôt Laravel. Il exécute n'importe quelle commande Artisan à l'exception des commandes de longue durée/interactives (serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start). Tout le reste – y compris les seeders – est un jeu équitable.
Invites qui enregistrent réellement un saut sur SSH :
- « Courez
migrate:statussur la mise en scène. - « Rôles de départ uniquement :
db:seed --class=RoleSeeder.” - « Chargez les commandes de démonstration avec
DemoDataSeeder, alorsSELECT COUNT(*) FROM orders.” - “
queue:failed— des tâches bloquées depuis le dernier déploiement ? » - “
cache:clearetoptimize:clearaprès le changement de configuration.
Ne pointez-le vers la production et dites « exécutez DatabaseSeeder ». migrate:fresh --seed est pas dans la liste bloquée — le package l’exécutera. Utilisez des seeders nommés, lors de la mise en scène, et confirmez avec db_query. Les données de production ne sont pas un terrain de jeu simplement parce que le transport est MCP au lieu de SSH.
Un modèle de mise en scène sûr : une classe de seeder par match, idempotente là où vous le pouvez, appelée par son nom. L'assistant dirige la classe, lit le tableau et ce n'est qu'alors que vous faites la promotion du même seeder via CI. C’est le contraire de « abandonner la production et prier ».
Associez-le avec le anonymiseur lorsque le local a besoin de volume sans PII : anonymisez un dump en forme de production, chargez-le localement, conservez MCP seeders pour les petites tables de référence (rôles, plans, indicateurs de fonctionnalités) qui changent à chaque sprint.
Une boucle quotidienne que vous pouvez copier
Vous : Staging healthy? Any pending jobs?
Agent : health → healthy, queue 0, debug false, commit a1b2c3d
Vous : Last Laravel errors, search "InvoiceJob"
Agent : logs type=laravel level=error search=InvoiceJob
→ 1 error, missing column invoices.paid_at
Vous : migrate:status. Is 2026_08_22_add_paid_at pending?
Agent : artisan migrate:status → yes, pending
Vous : After I deploy, seed InvoiceStatusSeeder only.
Agent : deploy → queued
artisan db:seed --class=InvoiceStatusSeeder
db_query SELECT id, name FROM invoice_statuses
→ 4 rowsPas de session SSH. Pas de copier-coller de storage/logs. La même conversation fonctionne pour un coéquipier qui possède le jeton MCP et ne devrait jamais avoir de root sur la boîte – ce qui représente la majeure partie de l'équipe.
Projet MCP vs panneau API MCP
Cipi navires deux MCP serveurs. Les mélanger est la première erreur habituelle.
Projet MCP (cipi/agent) | Panneau API MCP (cipi/api) | |
|---|---|---|
| Où | POST /cipi/mcp sur le application domaine | POST /mcp sur le API vhost |
| Portée | Une Laravel application : sa base de données, ses journaux, son Artisan, son indicateur de déploiement | L'ensemble du serveur : applications, SSL, bases de données, PHP, Workers |
| Outils | 6 — santé, app_info, déploiement, journaux, db_query, artisan | 50+ – créer des applications, émettre des certificats, modifier .env, exécuter en tant qu'utilisateur de l'application |
| Utilisez-le pour | Débogage, seeders, migration : statut, aperçu de la file d'attente | Provision, SSL, liste chaque base de données, cockpit du serveur |
Gardez les deux dans le curseur si vous le souhaitez. Interrogez le projet MCP à propos ceci application ; demander au panneau API MCP pour créer le prochain clone intermédiaire. Le guide d'IA basé sur les spécifications couvre la boucle la plus large – cette page est la moitié intégrée à l’application.
Jetons, blocs et moindre privilège
- Jeton dédié.
CIPI_MCP_TOKENn'est pas le secret webhook ni le jeton de santé. S'il fuit,php artisan cipi:generate-token mcpet redémarrez. Toute personne possédant le jeton peut exécuter Artisan et écrire du SQL (dans la limite de 100 lignes). - Désactivé signifie 404.
php artisan cipi:service mcp --disableouCIPI_MCP=false. Préférez cela en production jusqu'à ce que vous ayez réellement besoin de connecter l'IDE. - Artisan bloqué :
serve,tinker,queue:work,queue:listen,schedule:work,horizon,octane:start,reverb:start. - SQL bloqué :
DROP,TRUNCATE,GRANT,REVOKE, fichier E/S. - HTTPS uniquement, pas de SSH. Très bien pour un développeur qui devrait déployer et inspecter sans
sudo. Cela reste un canal privilégié : traitez le token comme un mot de passe de production.
Installez le package, puis le serveur
cipi/agent est le Laravel compagnon. Cipi est le déploiement gratuit open-source CLI qui injecte l'environnement et exécute Deployer lorsque le webhook ou le MCP deploy les incendies d’outils.
Questions fréquemment posées
Ai-je besoin de SSH pour utiliser le projet MCP ?
Non. Une fois le package déployé et CIPI_MCP est allumé, l'IDE parle à https://yourdomain.com/cipi/mcp avec le jeton Porteur. C'est le point pour les coéquipiers qui ne devraient jamais se connecter en tant que root.
Quelle est la différence entre l'agent MCP et l'agent Cipi API MCP ?
L'agent MCP se trouve dans une application Laravel (six outils : santé, journaux, SQL, Artisan, déploiement). Le panneau API MCP gère l'ensemble VPS — créer des applications, SSL, des bases de données, PHP. Utilisez l'agent pour le débogage et les seeders ; utilisez le API pour approvisionner.
Puis-je exécuter db:seed en production via MCP ?
Techniquement oui - db:seed n'est pas bloqué. En pratique, exécutez uniquement un seeder nommé et révisé, et jamais migrate:fresh --seed sur des données en direct. Préférez la mise en scène, puis validez avec db_query.
Quelles Artisan commandes sont bloquées ?
serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start. Les processus interactifs et de longue durée n'ont pas leur place dans un appel d'outil HTTP.
Est-ce que cipi/agent fonctionne sans serveur Cipi ?
Bilan de santé et MCP oui, sur n'importe quel hôte Laravel 12+. Les déploiements de déploiement déclenchés par Webhook et les types de journaux supplémentaires attendent la disposition Cipi sous /home/<app>/.
Comment puis-je faire pivoter un jeton MCP ayant fui ?
php artisan cipi:generate-token mcp, redémarrez l'application (ou rechargez PHP-FPM / Octane), mettez à jour ~/.cursor/mcp.json. L'ancien jeton meurt avec le .env réécrire.
