Serveur MCP

joppa mcp est un serveur MCP (Model Context Protocol) sur stdio. Un assistant de code y fait ce que vous faites dans la journée : il démarre et redémarre les serveurs de dev de vos projets, lit leurs journaux, cherche pourquoi un domaine ne répond pas, modifie le .env, branche une base, consulte les analytics, démarre les services et crée des projets.

Brancher un assistant

Le plus simple : Réglages › Ligne de commande › Brancher les assistants. Ou depuis le terminal :

joppa mcp install                           # Claude Code, Claude Desktop et Cursor, ceux qui sont installés
joppa mcp install --client cursor --dry-run # montre ce qui serait écrit
joppa mcp uninstall

Client	Où Joppa s’inscrit
Claude Code	claude mcp add --scope user, sinon son fichier de config
Claude Desktop	claude_desktop_config.json
Cursor	~/.cursor/mcp.json

Seule l’entrée mcpServers.joppa est écrite, le reste du fichier ne bouge pas. Redémarrez l’assistant ensuite.

--client accepte claude-code, claude-desktop, cursor ou all.

Les outils

Processus

Les processus d’un projet : ses serveurs de dev, ses workers et ses services Docker Compose, tels que configurés dans son onglet Processus.

Outil	Rôle
list_processes	Les processus d’un projet (ou de tous) : état, commande, port, domaines qui y mènent, pid, durée, relances après un plantage, erreur ; asleep pour un processus en veille, ses actions et celles qui tournent, sleepAfterMinutes quand ses serveurs de dev se mettent en veille
start_process	Démarre un processus (et ceux dont il dépend), ou tout le projet sans process (comme Tout démarrer, services liés compris)
stop_process	Arrête un processus, ou tout le projet
restart_process	Redémarre un processus, ou tous ceux du projet qui tournent ou sont cochés
process_logs	Les dernières lignes d’un processus, ou de tous (préfixées par leur nom) : lines (100 par défaut, 2 000 au plus), grep pour ne garder que les lignes qui contiennent un texte
run_process_action	Lance une action d’un processus (migrate, seed, test…) et renvoie ce qu’elle a écrit, après avoir attendu qu’elle se termine (wait_seconds : 60 par défaut, 600 au plus, 0 pour ne pas attendre)

start_process et restart_process attendent que les processus répondent ou plantent (wait_seconds : 20 par défaut, 120 au plus, 0 pour ne pas attendre) et renvoient leur état, avec les dernières lignes du journal de ceux qui ont planté.

Diagnostic

Outil	Rôle
diagnose	Pourquoi un domaine (ou chaque domaine d’un projet) ne répond pas

diagnose suit le chemin d’une requête et dit, pour chaque maillon, s’il tient et comment le réparer : le domaine est activé, le proxy tourne, le nom résout vers 127.0.0.1, la CA est approuvée et le certificat valide, le port du serveur de dev répond, l’état du processus que Joppa lance sur ce port (planté, arrêté, port pris par un autre programme, avec ses dernières lignes), puis la réponse à travers le proxy (502, hôte refusé par Vite…).

.env

Outil	Rôle
get_env	Le .env d’un projet, secrets masqués sauf avec reveal
set_env	Écrit, modifie (values) ou retire (unset) des variables
link_service	Relie le projet à un service et écrit ses variables (DATABASE_URL, REDIS_URL…), en remplaçant un service du même genre
unlink_service	Délie un service : les clés qui ont encore la valeur de Joppa reprennent celle de .env.example ou sont retirées

Ces trois outils écrivent comme l’éditeur du .env (voir Ce que Joppa garantit) : seules les lignes concernées changent, le fichier d’origine est copié dans .env.joppa-backup à la première écriture, et rien n’est écrit si le fichier a changé sur le disque entre-temps. Ils renvoient le diff, secrets masqués sauf avec reveal ; dry_run montre le diff sans rien écrire.

Analytics

Outil	Rôle
get_analytics	Le résumé des analytics d’un projet ou d’un domaine sur 15m, 1h (par défaut), 24h ou 7d : requêtes, taux d’erreur, latences p50/p95/p99, disponibilité, chemins les plus lents, chemins en erreur avec un exemple de requête, rafales du même chemin (N+1)

get_analytics est inclus dans Joppa Pro, comme l’onglet Analytics ; en version gratuite, l’outil répond que la fonction est incluse dans Joppa Pro.

Partage

Outil	Rôle
share_start	Partage un domaine (ou le premier domaine actif d’un projet) : mode lan (par défaut, gratuit) sur le réseau local, ou public par un tunnel (Joppa Pro) avec provider (cloudflared par défaut, ngrok, localhost-run, pinggy) ; install_cloudflared le télécharge s’il manque. Renvoie l’adresse, celle du tunnel une fois ouvert
share_stop	Arrête le partage d’un domaine : mode lan, public, ou les deux
share_status	Les domaines partagés, leurs adresses et l’état des tunnels

L’assistant n’ouvre un lien public que si vous le lui demandez : qui a le lien atteint votre serveur de dev.

Projets, services et proxy

Outil	Rôle
get_status	État du proxy, de la CA, des projets et des services
list_projects	Les projets, leurs domaines et leur santé
list_services	Les services et leur état
start_service, stop_service	Démarre ou arrête un service
service_logs	Le journal d’un service (lines : 100 par défaut, 2 000 au plus)
list_databases	Les bases d’un serveur et leurs URL
create_database	Crée une base (service, name, extensions)
start_proxy, stop_proxy	Démarre ou arrête le proxy
set_route_enabled	Active ou désactive un domaine
add_project	Ajoute un dossier, avec ses domaines détectés ou donnés
add_service	Ajoute un service (engine, version, port, start)
list_templates	Les modèles de projet et leurs options
create_project	Crée un projet depuis un modèle (dry_run pour voir les commandes)
create_project_status	Suit ou annule une création en cours
open_app	Affiche la fenêtre de Joppa

Un projet se désigne par son nom, son identifiant ou l’un de ses domaines ; un service comme dans la commande joppa ; un processus par son nom dans l’onglet Processus (web, api, queue…).

Exemples de demandes

• « Redémarre le serveur de dev d’acme et montre-moi les erreurs du journal. »
• « Pourquoi api.acme.test ne répond plus ? »
• « Donne-moi un lien public vers app.acme.test pour le montrer au client. »
• « Passe APP_DEBUG à true dans le .env de blog, puis redémarre-le. »
• « Branche acme sur PostgreSQL avec une base acme. »
• « Quelles routes d’api.acme.test sont les plus lentes cette dernière heure ? Y a-t-il des N+1 ? »
• « Démarre PostgreSQL et crée une base blog avec pgvector. »
• « Crée un projet Astro docs dans ~/Code et ajoute-le à Joppa. »