@lyrra/mcp-server 1.1.3 → 1.1.7

package/README.md

@@ -1,34 +1,21 @@
-# LYRRA Studio MCP Server
+# Lyrra Studio MCP server
 
-Serveur MCP (Model Context Protocol) pour piloter **LYRRA Studio** depuis un outil IA externe (Claude Desktop, Claude.ai, Cursor, Copilot CLI, etc.).
+**stdio** process (Model Context Protocol): one tool per backend **OpenAPI** operation, plus `lyrra_meta`, `lyrra_search_operations`, and `lyrra://…` resources.
 
-## Modes de transport
+## Prerequisites
 
-### Mode stdio (Claude Desktop, Cursor)
-Transport stdio classique — le serveur MCP tourne en processus local.
+- Node.js ≥ 20
+- Reachable Lyrra backend with generated `openapi/openapi.json` (`npm run openapi:generate` in `apps/backend`)
 
-### Mode HTTP (Claude.ai, applications web)
-Transport HTTP Streamable avec OAuth 2.0 — le serveur MCP tourne comme service web accessible via `https://lyrrastudio.com/mcp`.
+## Install from npm (Claude / Cursor)
 
-## Installation
+Published as **`@lyrra/mcp-server`**. No local clone required:
 
 ```bash
-npm install -g @lyrra/mcp-server
+npx -y @lyrra/mcp-server
 ```
 
-Ou utilisez directement avec `npx` (aucune installation requise) — voir la configuration ci-dessous.
-
-## Configuration
-
-### 1. Obtenir vos identifiants
-
-Connectez-vous à LYRRA Studio → Dashboard Entreprise → Serveur MCP → Onglet "Identifiants" → Créer un nouveau client.
-
-Vous obtiendrez un **Client ID** et un **Client Secret** (affiché une seule fois).
-
-### 2. Claude Desktop (mode stdio)
-
-Ajoutez dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :
+In **Claude Desktop** (`claude_desktop_config.json`), prefer:
 
 ```json
 {
@@ -37,257 +24,100 @@ Ajoutez dans `~/Library/Application Support/Claude/claude_desktop_config.json` (
       "command": "npx",
       "args": ["-y", "@lyrra/mcp-server"],
       "env": {
-        "LYRRA_CLIENT_ID": "votre_client_id",
-        "LYRRA_CLIENT_SECRET": "rak_votre_client_secret",
-        "LYRRA_API_URL": "https://lyrrastudio.com/api",
-        "LYRRA_EDUFLOW_API_URL": "https://lyrrastudio.com/api/eduflow"
+        "LYRRA_API_URL": "https://your-domain.com/api",
+        "LYRRA_CLIENT_ID": "rak_xxxxxxxx",
+        "LYRRA_CLIENT_SECRET": "rak_xxxxxxxx_yyyyyyyy_zzzzzzzzzzzzzzzz"
       }
     }
   }
 }
 ```
 
-> Après modification, quittez complètement Claude Desktop (Cmd+Q / Ctrl+Q) et relancez-le.
+Use **Header Auth** keys from the institution dashboard instead of client id/secret:
 
-### 3. Claude.ai (mode HTTP)
+```json
+"env": {
+  "LYRRA_API_URL": "https://your-domain.com/api",
+  "LYRRA_MCP_HEADER_NAME": "X-Lyrra-Api-Key",
+  "LYRRA_MCP_HEADER_VALUE": "rak_…full secret…"
+}
+```
 
-Ajoutez le MCP serveur dans Claude.ai Settings → Integrations → Add MCP Server :
+Global install (optional): `npm install -g @lyrra/mcp-server` then run **`lyrra-mcp`** (binary name on `PATH`).
 
-- **URL** : `https://lyrrastudio.com/mcp`
+## Streamable HTTP / n8n (`https://…/mcp`)
 
-Claude.ai lancera automatiquement le flux OAuth :
-1. Vous serez redirigé vers la page d'autorisation LYRRA Studio
-2. Entrez votre **Client Secret** (clé API `rak_...`)
-3. L'accès est autorisé, Claude.ai peut utiliser vos outils MCP
+Clients that need an **HTTPS URL** (e.g. n8n **MCP Client**) use the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport on path **`/mcp`**.
 
-### 4. Cursor (mode stdio)
+- **Docker:** enable service **`mcp-http`** in `docker-compose.yml` and Nginx **`location /mcp`** (see `apps/frontend/nginx.default.conf`).
+- **Auth:** n8n **Header Auth** — same header name and **full** secret as an institution **Header auth** key (e.g. `X-Lyrra-Api-Key` + `rak_…`).
+- **Run locally:** `LYRRA_API_URL=http://localhost:3001/api npm run start:http` → listens on **`LYRRA_MCP_HTTP_PORT`** (default **3457**), path `/mcp`.
 
-Ajoutez dans `.cursor/mcp.json` :
+Binaries after global install: **`lyrra-mcp`** (stdio) and **`lyrra-mcp-http`** (HTTP).
 
-```json
-{
-  "mcpServers": {
-    "lyrra-studio": {
-      "command": "npx",
-      "args": ["-y", "@lyrra/mcp-server"],
-      "env": {
-        "LYRRA_CLIENT_ID": "votre_client_id",
-        "LYRRA_CLIENT_SECRET": "rak_votre_client_secret",
-        "LYRRA_API_URL": "https://lyrrastudio.com/api",
-        "LYRRA_EDUFLOW_API_URL": "https://lyrrastudio.com/api/eduflow"
-      }
-    }
-  }
-}
+## Develop from this monorepo
+
+```bash
+cd lyrra-studio-app/apps/mcp-server
+npm ci
+npm run build
 ```
 
-### 5. GitHub Copilot CLI / VS Code
+### Publish a new version (maintainers)
 
-Ajoutez dans `.vscode/mcp.json` ou les settings Copilot :
+1. Create an **npm** organization or user scope **`@lyrra`** and log in: `npm login`.
+2. Bump **`version`** in `package.json` (semver).
+3. From `apps/mcp-server`: `npm publish`  
+   (`publishConfig.access` is `public` for the scoped package.)
 
-```json
-{
-  "mcpServers": {
-    "lyrra-studio": {
-      "command": "npx",
-      "args": ["-y", "@lyrra/mcp-server"],
-      "env": {
-        "LYRRA_CLIENT_ID": "votre_client_id",
-        "LYRRA_CLIENT_SECRET": "rak_votre_client_secret",
-        "LYRRA_API_URL": "https://lyrrastudio.com/api",
-        "LYRRA_EDUFLOW_API_URL": "https://lyrrastudio.com/api/eduflow"
-      }
-    }
-  }
-}
-```
+Ensure `dist/` is built (`prepublishOnly` runs `npm run build` automatically).
 
-## Variables d'environnement
-
-| Variable | Défaut | Description |
-|---|---|---|
-| `LYRRA_CLIENT_ID` | - | Client ID (nom du client) |
-| `LYRRA_CLIENT_SECRET` | - | Client Secret (clé secrète, préfixe `rak_`) |
-| `LYRRA_API_URL` | `http://localhost:3001/api` | URL de l'API REST |
-| `LYRRA_EDUFLOW_API_URL` | `http://localhost:3001/api/eduflow` | URL de l'API EduFlow |
-
-## Tools disponibles (58)
-
-### 🔐 Authentification
-| Tool | Description |
-|---|---|
-| `auth_login` | Se connecter avec email/mot de passe |
-| `auth_get_profile` | Profil utilisateur connecté |
-| `auth_list_api_keys` | Lister les clés API |
-
-### 📚 Parcours EduFlow
-| Tool | Description |
-|---|---|
-| `eduflow_list` | Lister tous les parcours |
-| `eduflow_get` | Détails d'un parcours |
-| `eduflow_create` | Créer un parcours |
-| `eduflow_update` | Mettre à jour un parcours |
-| `eduflow_delete` | Supprimer un parcours |
-| `eduflow_duplicate` | Dupliquer un parcours |
-| `eduflow_change_status` | Changer le statut (draft/published/archived) |
-| `eduflow_export` | Exporter un parcours |
-| `eduflow_get_public` | Infos publiques d'un parcours |
-| `eduflow_get_urls` | Obtenir les liens (prévisualisation, édition, analytics, etc.) |
-
-### 🧱 Blocs
-| Tool | Description |
-|---|---|
-| `block_list_types` | Documentation des 29 types de blocs |
-| `block_get` | Détails d'un bloc |
-| `block_create` | Créer un bloc |
-| `block_update` | Mettre à jour un bloc |
-| `block_batch_update` | Mise à jour en lot |
-| `block_delete` | Supprimer un bloc |
-| `block_generate_tts` | Générer audio TTS |
-
-### 🔗 Connexions
-| Tool | Description |
-|---|---|
-| `connection_list` | Lister les connexions |
-| `connection_add` | Ajouter une connexion |
-| `connection_remove` | Supprimer une connexion |
-
-### 👥 Participants
-| Tool | Description |
-|---|---|
-| `participant_list` | Lister les participants |
-| `participant_add` | Ajouter des participants |
-| `participant_remove` | Retirer un participant |
-| `participant_get_progress` | Progression d'un participant |
-| `participant_get_overview` | Vue d'ensemble participant |
-| `participant_get_flow_stats` | Stats de tous les participants |
-
-### 📊 Analytics
-| Tool | Description |
-|---|---|
-| `analytics_overview` | Dashboard global |
-| `analytics_flow_learners` | Stats apprenants par parcours |
-| `analytics_flow_dashboard` | Dashboard analytics parcours |
-| `analytics_my_stats` | Mes statistiques |
-
-### 🤖 AI Designer
-| Tool | Description |
-|---|---|
-| `ai_generate_plan` | Générer un plan de parcours |
-| `ai_generate_block` | Générer le contenu d'un bloc |
-| `ai_generate_presentation` | Générer la page de présentation |
-| `ai_generate_objectives` | Générer les objectifs pédagogiques |
-| `ai_save_objectives` | Sauvegarder les objectifs |
-| `ai_chat_message` | Discuter avec le designer IA |
-| `ai_get_conversation` | Historique de conversation IA |
-
-### 🎭 Présentation
-| Tool | Description |
-|---|---|
-| `presentation_get` | Page de présentation |
-| `presentation_update` | Mettre à jour la présentation |
-| `presentation_toggle` | Activer/désactiver |
-
-### 🏪 Store
-| Tool | Description |
-|---|---|
-| `store_list_audiobooks` | Lister les audiobooks |
-| `store_get_audiobook` | Détails d'un audiobook |
-| `store_list_authors` | Auteurs en vedette |
-| `store_my_library` | Ma bibliothèque |
-| `store_search` | Rechercher dans le store |
-
-### 🎵 Projets Audio
-| Tool | Description |
-|---|---|
-| `project_list` | Lister mes projets |
-| `project_get` | Détails d'un projet |
-| `project_create` | Créer un projet |
-| `project_update` | Mettre à jour un projet |
-| `project_delete` | Supprimer un projet |
-
-### 📁 Ressources
-| Tool | Description |
-|---|---|
-| `resource_list` | Lister les ressources |
-| `resource_delete` | Supprimer une ressource |
-| `resource_list_categories` | Catégories disponibles |
-
-### 🔧 Versions, Gamification & Webhooks
-| Tool | Description |
-|---|---|
-| `version_list` | Versions d'un parcours |
-| `version_create` | Créer une version |
-| `version_activate` | Activer une version |
-| `gamification_stats` | Stats de gamification |
-| `gamification_objectives` | Objectifs à atteindre |
-| `activity_history` | Historique d'activité |
-| `activity_stats` | Stats d'utilisation |
-| `webhook_list` | Lister les webhooks |
-| `webhook_create` | Créer un webhook |
-| `webhook_delete` | Supprimer un webhook |
-| `webhook_test` | Tester un webhook |
-
-## Resources MCP
-
-| URI | Description |
-|---|---|
-| `lyrra://block-types` | Documentation complète des 29 types de blocs |
-| `lyrra://flow-construction-guide` | Guide de construction de parcours |
-
-## Exemples d'utilisation avec Claude
-
-### Créer un parcours complet
-> "Crée un parcours EduFlow sur les fractions pour des élèves de CM2, avec 3 leçons en texte, un quiz après chaque leçon, et un certificat de réussite à la fin."
-
-### Analyser les statistiques
-> "Montre-moi les statistiques de mon parcours 'Introduction au Python'. Quels sont les blocs où les étudiants passent le plus de temps ?"
-
-### Modifier un parcours existant
-> "Dans mon parcours sur la photosynthèse, ajoute un bloc vidéo après le texte d'introduction et connecte-le au quiz."
-
-## Développement
+**Publish error:** `Cannot implicitly apply the "latest" tag because previously published version … is higher` — the registry already has a **newer** semver on `latest` (e.g. `1.1.3`). Bump `package.json` to something **greater** (e.g. `1.1.4`), not `1.0.x`. Alternatively: `npm publish --tag maintenance` to publish an older line without moving `latest`.
 
-```bash
-# Lancer en mode stdio (développement local)
-npm run dev
+Run `npm pkg fix` in this folder to apply npm’s suggested `package.json` fixes (`bin`, `repository`, …).
 
-# Lancer en mode HTTP (développement local)
-npm run dev:http
+## Environment variables
 
-# Rebuild après modifications
-npm run build
+| Variable | Purpose |
+|----------|---------|
+| `LYRRA_API_URL` | API base, e.g. `https://yourdomain/api` or `http://localhost:3001/api` |
+| `LYRRA_CLIENT_ID` | Key prefix (`keyPrefix`) |
+| `LYRRA_CLIENT_SECRET` | Full secret `rak_…` |
+| `LYRRA_ACCESS_TOKEN` | *(optional)* Bearer JWT if not using key exchange |
+| `LYRRA_MCP_HEADER_NAME` | *(optional)* HTTP header name for **Header Auth** keys (e.g. `X-Lyrra-Api-Key`; alias `LYRRA_HEADER_AUTH_NAME`) |
+| `LYRRA_MCP_HEADER_VALUE` | *(optional)* Same secret as shown once at key creation (alias `LYRRA_MCP_HEADER_SECRET` or `LYRRA_HEADER_AUTH_VALUE`) |
+| `LYRRA_OPENAPI_URL` | *(optional)* OpenAPI JSON URL |
+| `LYRRA_MCP_MAX_TOOLS` | *(optional)* Max number of tools (integer) |
+| `LYRRA_MCP_HTTP_PORT` | *(HTTP mode only)* Listen port (default `3457`) |
+| `LYRRA_MCP_SKIP_AUTH_VALIDATE` | *(optional)* Set to `1` to skip `GET /api/auth/me` on each MCP request (insecure; dev only) |
+| `LYRRA_MCP_EXTRA_INBOUND_HEADERS` | *(HTTP mode)* Comma-separated extra header names to copy from the MCP request into Lyrra API calls |
+
+Client ID + Secret → JWT exchange uses `POST /api/auth/api-key/token`. **Header Auth** keys do not use that route: send the header on each API request instead (same as n8n MCP « Header Auth »).
+
+## EduFlow block documentation
 
-# Lancer en production (stdio)
+- Tool **`lyrra_eduflow_blocks_index`**: list of documented types.
+- One tool per type: **`lyrra_eduflow_block_<type>`** (e.g. `lyrra_eduflow_block_quiz_mcq`) — role, `data` / `settings` fields, graph, persistence.
+- Sheet source: `src/eduflow-block-docs.ts` (keep aligned with the React designer).
+
+## Run
+
+```bash
 npm start
+```
+
+Development (no pre-build): `npm run dev`
+
+## Automated test (no Lyrra backend)
 
-# Lancer en production (HTTP)
-npm run start:http
+A minimal OpenAPI is served locally; the script checks `initialize`, `tools/list`, and a `tools/call` on a block sheet:
+
+```bash
+npm run test:mcp
 ```
 
-## Architecture HTTP
-
-Le mode HTTP expose les endpoints suivants :
-
-| Endpoint | Méthode | Description |
-|---|---|---|
-| `/.well-known/oauth-protected-resource/mcp` | GET | Métadonnées RFC 9728 |
-| `/mcp/.well-known/oauth-authorization-server` | GET | Métadonnées OAuth AS |
-| `/mcp/register` | POST | Enregistrement dynamique de client OAuth |
-| `/mcp/authorize` | GET | Page d'autorisation OAuth |
-| `/mcp/approve` | POST | Validation des identifiants |
-| `/mcp/token` | POST | Échange de code → token |
-| `/mcp/revoke` | POST | Révocation de token |
-| `/mcp` | POST | Protocole MCP (messages) |
-| `/mcp` | GET | SSE stream (notifications serveur) |
-| `/mcp` | DELETE | Fermeture de session |
-| `/mcp/health` | GET | Health check |
-
-### Variables d'environnement (mode HTTP)
-
-| Variable | Défaut | Description |
-|---|---|---|
-| `MCP_HTTP_PORT` | `3002` | Port du serveur HTTP |
-| `MCP_BASE_URL` | `https://lyrrastudio.com` | URL publique de base |
-| `LYRRA_API_URL` | `http://localhost:3001/api` | URL de l'API backend |
-| `LYRRA_EDUFLOW_API_URL` | `http://localhost:3001/api/eduflow` | URL de l'API EduFlow |
+## MCP client (local build vs npm)
+
+- **Recommended:** `command` `npx`, `args` `["-y", "@lyrra/mcp-server"]` (see above).
+- **Local monorepo:** `command` `node`, `args`: **absolute** path to `apps/mcp-server/dist/index.js`  
+  `env`: `LYRRA_API_URL`, `LYRRA_CLIENT_ID`, `LYRRA_CLIENT_SECRET` (or `LYRRA_ACCESS_TOKEN` / header variables).

package/dist/auth-session.js

@@ -0,0 +1,171 @@
+/**
+ * Access token for Lyrra API calls.
+ * - LYRRA_ACCESS_TOKEN: JWT directly
+ * - or LYRRA_CLIENT_ID (keyPrefix) + LYRRA_CLIENT_SECRET (rak_… secret) → POST /api/auth/api-key/token
+ * - or clé institution « header_auth » : LYRRA_MCP_HEADER_NAME + LYRRA_MCP_HEADER_VALUE
+ *   (alias : LYRRA_HEADER_AUTH_NAME / LYRRA_HEADER_AUTH_VALUE) — même en-tête que n8n « Header Auth »
+ * - or (HTTP MCP) en-têtes par requête via runWithInboundAuthHeaders (n8n Header Auth sur /mcp)
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const inboundAuthAls = new AsyncLocalStorage();
+/** Exécute une callback avec des en-têtes d’auth injectés pour les appels API (transport MCP HTTP). */
+export function runWithInboundAuthHeaders(headers, fn) {
+    return inboundAuthAls.run(headers, fn);
+}
+let cached = null;
+function apiBase() {
+    const u = process.env.LYRRA_API_URL?.trim();
+    if (!u) {
+        throw new Error('LYRRA_API_URL is required (e.g. https://lyrrastudio.com/api or http://localhost:3001/api)');
+    }
+    return u.replace(/\/+$/, '');
+}
+/** HTTP origin without /api suffix, for /api/auth/… and /api/openapi.json */
+export function requestOrigin() {
+    const base = apiBase();
+    if (base.endsWith('/api')) {
+        const o = base.slice(0, -4);
+        return o.length > 0 ? o : base;
+    }
+    return base;
+}
+function parseJsonEnvelope(json) {
+    if (!json || typeof json !== 'object')
+        return {};
+    const o = json;
+    const data = o.data;
+    if (data && typeof data === 'object')
+        return data;
+    return o;
+}
+async function exchangeApiKey(prefix, secret) {
+    const origin = requestOrigin();
+    const url = `${origin}/api/auth/api-key/token`;
+    const r = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ keyPrefix: prefix, secret }),
+    });
+    const text = await r.text();
+    if (!r.ok) {
+        throw new Error(`API key exchange failed (${r.status}): ${text.slice(0, 800)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error('Invalid auth response (expected JSON)');
+    }
+    const body = parseJsonEnvelope(parsed);
+    const access = typeof body.accessToken === 'string' ? body.accessToken : '';
+    const refresh = typeof body.refreshToken === 'string' ? body.refreshToken : '';
+    if (!access) {
+        throw new Error('Auth response missing accessToken');
+    }
+    let expMs = Date.now() + 10 * 60_000;
+    try {
+        const part = access.split('.')[1];
+        if (part) {
+            const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+            if (typeof payload.exp === 'number') {
+                expMs = payload.exp * 1000;
+            }
+        }
+    }
+    catch {
+        /* keep default expMs */
+    }
+    cached = { access, refresh, expMs };
+}
+async function refreshAccess() {
+    if (!cached?.refresh)
+        return false;
+    const origin = requestOrigin();
+    const r = await fetch(`${origin}/api/auth/refresh`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ refreshToken: cached.refresh }),
+    });
+    const text = await r.text();
+    if (!r.ok)
+        return false;
+    try {
+        const parsed = JSON.parse(text);
+        const body = parseJsonEnvelope(parsed);
+        const access = typeof body.accessToken === 'string' ? body.accessToken : '';
+        if (!access)
+            return false;
+        let expMs = Date.now() + 10 * 60_000;
+        try {
+            const part = access.split('.')[1];
+            if (part) {
+                const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+                if (typeof payload.exp === 'number')
+                    expMs = payload.exp * 1000;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        cached = { ...cached, access, expMs };
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function headerAuthFromEnv() {
+    const name = process.env.LYRRA_MCP_HEADER_NAME?.trim() ||
+        process.env.LYRRA_HEADER_AUTH_NAME?.trim() ||
+        '';
+    const value = process.env.LYRRA_MCP_HEADER_SECRET?.trim() ||
+        process.env.LYRRA_MCP_HEADER_VALUE?.trim() ||
+        process.env.LYRRA_HEADER_AUTH_VALUE?.trim() ||
+        '';
+    if (!name || !value)
+        return null;
+    return { name, value };
+}
+/**
+ * En-têtes à envoyer sur chaque appel API Lyrra (Bearer ou clé header_auth).
+ */
+export async function getLyrraRequestAuthHeaders() {
+    const inbound = inboundAuthAls.getStore();
+    if (inbound && Object.keys(inbound).length > 0) {
+        return { ...inbound };
+    }
+    const headerPair = headerAuthFromEnv();
+    if (headerPair) {
+        return { [headerPair.name]: headerPair.value };
+    }
+    const token = await getAccessToken();
+    return { Authorization: `Bearer ${token}` };
+}
+export async function getAccessToken() {
+    if (headerAuthFromEnv()) {
+        throw new Error('Header auth is configured (LYRRA_MCP_HEADER_*); use getLyrraRequestAuthHeaders for API calls');
+    }
+    const direct = process.env.LYRRA_ACCESS_TOKEN?.trim();
+    if (direct)
+        return direct;
+    const prefix = process.env.LYRRA_CLIENT_ID?.trim();
+    const secret = process.env.LYRRA_CLIENT_SECRET?.trim();
+    if (!prefix || !secret) {
+        throw new Error('Set LYRRA_ACCESS_TOKEN (JWT), LYRRA_CLIENT_ID + LYRRA_CLIENT_SECRET, or LYRRA_MCP_HEADER_NAME + LYRRA_MCP_HEADER_VALUE');
+    }
+    const margin = 90_000;
+    if (cached && cached.expMs > Date.now() + margin) {
+        return cached.access;
+    }
+    if (cached?.refresh && (await refreshAccess())) {
+        return cached.access;
+    }
+    cached = null;
+    await exchangeApiKey(prefix, secret);
+    return cached.access;
+}
+/** Clear cache (e.g. after persistent 401) */
+export function clearTokenCache() {
+    cached = null;
+}