NovaFormation — serveur MCP

Serveur MCP distant de NovaFormation (programmes de formation, exercices, activités réelles, livres, objectifs, XP). Il donne à un client MCP un accès complet en lecture et écriture aux données de l'application, avec les mêmes règles que l'interface.

• Lit et écrit directement la base Supabase de l'application (clé service_role), chaque requête étant limitée au compte NovaFormation.

• Les règles métier de l'app sont reprises à l'identique (src/domain, src/services) : XP accordée une seule fois et retirée à l'annulation, progression des programmes, objectifs d'exercice franchis enregistrés une seule fois.

• Toute suppression est définitive et exige confirm: true. Pour ranger sans rien perdre : update_program avec status: "archived", update_exercise avec archived: true.

• Les sections Today et Habits, masquées dans l'app, ne sont pas exposées.

Outils

Un échec renvoie un résultat isError contenant {"error": {"code": "not_found", "message": "..."}} — codes : bad_request, not_found, conflict, unavailable, server_error.

Related MCP server: Gym Coach MCP Server

Points d'entrée

Authentification

Avec MCP_AUTH_TOKEN, le client fournit le jeton par l'en-tête Authorization: Bearer <jeton> ou, s'il n'accepte qu'une URL, dans l'adresse : https://mcp.exemple.fr/sse?token=<jeton> ou https://mcp.exemple.fr/mcp?token=<jeton>. /health reste public ; /.well-known/* répond 404 (pas de fournisseur OAuth).

Configuration

La base doit avoir les migrations de l'application appliquées, dont 0004_exercise_goals.sql pour les objectifs et milestones (sans elle, les outils d'objectifs répondent unavailable et le reste fonctionne). La migration 0007_reconcile_exercise_goals.sql répare les jalons historiques manquants et enregistre les nouveaux franchissements directement en base. Le MCP les lit après la création d'une session et calcule les périodes selon Europe/Paris. 0008_activities.sql crée les entités dédiées aux activités, séances, récurrences versionnées, compétences, liens et fichiers privés. Les fonctions SQL recalculent les occurrences futures sans modifier les séances déjà réalisées ni les exceptions déplacées par l’utilisateur. Une suppression ponctuelle d’une occurrence est mémorisée pour qu’elle ne réapparaisse pas lors du recalcul. Le taux de présence exclut les annulations par l’organisateur et les reports. Les pièces jointes MCP sont échangées en base64, sans URL avec jeton. Les compétences travaillées sont figées sur chaque séance réalisée pour conserver des statistiques historiques cohérentes si les liens de l’activité changent. La migration 0009_activity_history.sql génère aussi les occurrences passées depuis la date de début d’une activité récurrente. Elles peuvent ensuite être marquées réalisées par le MCP, y compris en lot. La migration 0010_one_off_events.sql ajoute les événements ponctuels multi-jours : set_one_off_event_days règle séparément chaque date en journée entière, plage horaire ou durée. Les journées entières occupent le calendrier sans être comptées comme 24 heures de pratique. La migration 0011_exercise_session_cleanup.sql supprime les XP liés à une séance d’exercice dans la même transaction que sa suppression. Le jalon déjà atteint reste historique et la progression courante est recalculée. La migration 0012_entity_connections.sql généralise les connexions bidirectionnelles entre programmes, livres, exercices et activités. connect_entities et disconnect_entities prennent une source (entity_type, entity_id) et jusqu’à 100 cibles {type, id}. Ces opérations sont atomiques, idempotentes et limitées au compte pour la source comme pour chaque cible. Déconnecter retire un lien explicite et ne supprime aucune donnée : l’opération ne demande donc pas confirm. Les références de livres et exercices présentes dans les plannings apparaissent avec in_planning: true, et restent visibles après déconnexion du lien explicite. Les liens Activité–Programme existants gardent leur stockage canonique et sont visibles depuis les deux fiches. Les quatre outils get_program, get_book, get_exercise, get_activity incluent connections, avec les titres actuels des éléments liés, sans copie des données. La recherche est paginée, filtrable par section et limitée au nom de l’élément.

La migration 0013_planning_item_connections.sql étend ce même système aux éléments des semaines : entity_type: "item" désigne un module_items, quelle que soit sa nature (cours, livre, exercice, objectif ou tâche). Un item peut être relié aux quatre sections et à d’autres items distincts, sans se connecter à lui-même. Les éléments liés et les résultats de recherche incluent leur contexte program_id, week_id, week_number, module_id, ainsi qu’un sous-titre programme / semaine / module. La recherche accepte entity_id avec entity_type pour vérifier la source et exclure l’item source. get_program ajoute connections à chaque weeks[].modules[].items[], récupérées en un seul appel SQL pour le programme. Les contrôles de compte remontent de l’item à son module, sa semaine et son programme. Les anciennes références ref_book_id / ref_exercise_id apparaissent comme des connexions d’item (direct: true, in_planning: true). Déconnecter l’item de cette ressource, depuis l’une ou l’autre fiche, retire aussi cette référence sans supprimer l’item. Les liens programme / ressource agrégés à partir du planning restent visibles tant qu’un item les établit.

Développement

npm install
cp .env.example .env    # puis renseigner les variables
npm run build && node --env-file=.env dist/index.js
npm test                # logique métier + protocole MCP (SSE et Streamable HTTP)

Déploiement (Docker / Coolify)

docker build -t novaformation-mcp .
docker run -p 8080:8080 --env-file .env novaformation-mcp

Coolify : ressource depuis ce dépôt, build pack Dockerfile, port exposé 8080, variables ci-dessus. Le healthcheck de l'image interroge /health.