@lyrra/mcp-server 1.1.8 → 1.1.10

package/README.md

@@ -21,9 +21,11 @@ If you integrate **without** MCP (scripts, Postman, custom backend), call Lyrra
 Published as **`@lyrra/mcp-server`**. No local clone required:
 
 ```bash
-npx -y @lyrra/mcp-server
+npx -y @lyrra/mcp-server lyrra-mcp
 ```
 
+(Paquet avec **plusieurs** binaires : `lyrra-mcp`, `lyrra-mcp-http`, `mcp-server` — sans nom explicite, `npx` peut répondre *could not determine executable to run*.)
+
 In **Claude Desktop** (`claude_desktop_config.json`):
 
 ```json
@@ -31,7 +33,7 @@ In **Claude Desktop** (`claude_desktop_config.json`):
   "mcpServers": {
     "lyrra-studio": {
       "command": "npx",
-      "args": ["-y", "@lyrra/mcp-server"],
+      "args": ["-y", "@lyrra/mcp-server", "lyrra-mcp"],
       "env": {
         "LYRRA_API_URL": "https://your-domain.com/api",
         "LYRRA_CLIENT_ID": "rak_xxxxxxxx",
@@ -42,7 +44,7 @@ In **Claude Desktop** (`claude_desktop_config.json`):
 }
 ```
 
-`LYRRA_API_URL` must be your Lyrra **REST base** (usually `https://<host>/api`) so MCP tools can execute against the right environment.
+`LYRRA_API_URL` must be your Lyrra **REST base** (usually `https://<host>/api`) so MCP tools can execute against the right environment. **Do not** use the Streamable HTTP MCP URL here (not `…/mcp/api`) — that is only for clients that speak MCP over HTTPS to path `/mcp`, not for `LYRRA_API_URL`.
 
 Use **Header Auth** keys from the institution dashboard instead of client id/secret:
 
@@ -54,7 +56,18 @@ Use **Header Auth** keys from the institution dashboard instead of client id/sec
 }
 ```
 
-Global install (optional): `npm install -g @lyrra/mcp-server` then run **`lyrra-mcp`** (binary on `PATH`).
+Global install (optional): `npm install -g @lyrra/mcp-server` then run **`lyrra-mcp`** or **`mcp-server`** (binaries on `PATH`).
+
+## Troubleshooting (logs Claude / Cursor)
+
+| Symptôme | Cause fréquente | Correctif |
+|----------|-----------------|-----------|
+| `Cannot find module '/dist/index.js'` | `command` = `node` et args = `dist/index.js` **sans** répertoire de travail du paquet | Utiliser `npx` + args ci-dessus, **ou** `node` avec chemin **absolu** vers `…/node_modules/@lyrra/mcp-server/dist/index.js` |
+| `node: bad option: -y` | `command` = `node` au lieu de `npx` | `command` doit être **`npx`**, pas `node` |
+| `could not determine executable to run` | Plusieurs `bin` dans le paquet npm | Ajouter **`lyrra-mcp`** en dernier argument : `["-y", "@lyrra/mcp-server", "lyrra-mcp"]` |
+| Réponses API en HTML (`Unexpected token '<'`) | `LYRRA_API_URL` pointe vers le **frontend** ou une URL sans `/api` | Mettre `https://<hôte>/api` (base REST réelle) |
+| `OpenAPI introuvable …/mcp/api/openapi.json` | `LYRRA_API_URL` = `…/mcp/api` (confusion avec l’URL MCP HTTP) | Utiliser `…/api` uniquement ; optionnel : `LYRRA_OPENAPI_URL=https://<hôte>/api/openapi.json` |
+| `@lyrra/mcp-server` 404 sur npm | Scope / publication | Vérifier que le paquet est bien public sur npm sous `@lyrra/mcp-server` |
 
 ## Streamable HTTP / n8n (MCP URL `https://…/mcp`)
 
@@ -63,6 +76,7 @@ Some clients need an **HTTPS MCP endpoint** (not stdio). They use [Streamable HT
 - **Docker:** service **`mcp-http`** in `docker-compose.yml` and Nginx **`location /mcp`** (see `apps/frontend/nginx.default.conf` in the monorepo).
 - **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**), MCP path `/mcp`.
+- **n8n « Could not connect » :** the MCP SDK requires `Accept` to include **both** `application/json` and `text/event-stream` on POST. **`lyrra-mcp-http` patches missing values** so n8n can connect; ensure **`mcp-http`** + Nginx `/mcp` are deployed, and Header Auth **Value** is the **full** `rak_…` secret (same as at key creation).
 
 Binaries after global install: **`lyrra-mcp`** (stdio MCP) and **`lyrra-mcp-http`** (HTTP MCP).
 

package/dist/http-main.js

@@ -1,25 +1,26 @@
 #!/usr/bin/env node
 /**
- * MCP Streamable HTTP — pour n8n / clients qui attendent une URL https://…/mcp
- * (Header Auth : X-Lyrra-Api-Key ou Authorization, aligné tableau de bord institution).
+ * MCP Streamable HTTP — URL publique https://lyrrastudio.com/mcp
+ * Sessions stateful (comme ReadAudioPDF) : initialize → mcp-session-id → POST / GET SSE / DELETE.
+ * Auth : Header Auth (X-Lyrra-Api-Key, Authorization, …) validée via GET /api/auth/me.
  */
+import { createHash, randomUUID } from 'node:crypto';
 import express from 'express';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createLyrraMcpServer } from './lyrra-mcp-core.js';
 import { runWithInboundAuthHeaders, requestOrigin } from './auth-session.js';
 import { pickIncomingAuthHeaders } from './http-incoming-auth.js';
+import { getOpenApiJsonCached } from './openapi-parse.js';
 const PORT = parseInt(process.env.LYRRA_MCP_HTTP_PORT ?? '3457', 10);
-let mcpSingleton = null;
-async function getMcp() {
-    mcpSingleton ??= createLyrraMcpServer().then((r) => r.mcp);
-    return mcpSingleton;
+const mcpSessions = new Map();
+function authFingerprint(headers) {
+    const keys = Object.keys(headers).sort();
+    const payload = keys.map((k) => `${k}:${headers[k]}`).join('\n');
+    return createHash('sha256').update(payload).digest('hex');
 }
-/** Sérialise les requêtes MCP : un seul transport à la fois sur l’instance McpServer. */
-let mutexChain = Promise.resolve();
-function enqueueMcp(fn) {
-    const next = mutexChain.then(() => fn());
-    mutexChain = next.then(() => undefined, () => undefined);
-    return next;
+function setMcpCors(res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Expose-Headers', 'mcp-session-id');
 }
 async function validateAuth(headers) {
     const origin = requestOrigin();
@@ -29,17 +30,37 @@ async function validateAuth(headers) {
     });
     return r.ok;
 }
-const app = express();
-app.disable('x-powered-by');
-app.use('/mcp', express.json({ limit: '50mb' }));
-app.all('/mcp', async (req, res) => {
+/**
+ * @modelcontextprotocol/sdk (Streamable HTTP) exige sur POST :
+ * Accept contenant à la fois `application/json` et `text/event-stream`.
+ */
+function patchAcceptForMcpStreamable(req) {
+    const method = (req.method ?? 'GET').toUpperCase();
+    const a = String(req.headers.accept ?? '').toLowerCase();
+    if (method === 'POST') {
+        if (!a.includes('application/json') || !a.includes('text/event-stream')) {
+            req.headers.accept = 'application/json, text/event-stream';
+        }
+    }
+    else if (method === 'GET') {
+        if (!a.includes('text/event-stream')) {
+            const orig = typeof req.headers.accept === 'string' ? req.headers.accept : '';
+            req.headers.accept =
+                orig.trim() && a.includes('application/json')
+                    ? `${orig}, text/event-stream`
+                    : 'text/event-stream, application/json';
+        }
+    }
+}
+async function requireValidAuth(req, res) {
+    setMcpCors(res);
     const auth = pickIncomingAuthHeaders(req.headers);
     if (!auth) {
         res.status(401).json({
             success: false,
             error: 'Missing auth: use n8n Header Auth with X-Lyrra-Api-Key (institution key) or Authorization Bearer.',
         });
-        return;
+        return null;
     }
     const skipValidate = process.env.LYRRA_MCP_SKIP_AUTH_VALIDATE === '1';
     if (!skipValidate) {
@@ -49,37 +70,107 @@ app.all('/mcp', async (req, res) => {
                 success: false,
                 error: 'Invalid Lyrra credentials (GET /api/auth/me failed). Check your Header Auth value.',
             });
-            return;
+            return null;
         }
     }
+    return auth;
+}
+function sessionIdFromReq(req) {
+    const h = req.headers['mcp-session-id'];
+    if (typeof h === 'string' && h.length > 0)
+        return h;
+    if (Array.isArray(h) && h[0])
+        return h[0];
+    return undefined;
+}
+function getSessionOr403(req, res, auth) {
+    setMcpCors(res);
+    const sid = sessionIdFromReq(req);
+    if (!sid || !mcpSessions.has(sid)) {
+        res.status(404).json({
+            error: 'Session not found. Please re-initialize.',
+            jsonrpc: '2.0',
+            id: null,
+        });
+        return null;
+    }
+    const session = mcpSessions.get(sid);
+    if (session.authFp !== authFingerprint(auth)) {
+        res.status(403).json({
+            success: false,
+            error: 'Session credentials mismatch.',
+        });
+        return null;
+    }
+    return session;
+}
+const app = express();
+app.disable('x-powered-by');
+app.use('/mcp', express.json({ limit: '50mb' }));
+app.options('/mcp', (_req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Authorization, X-Lyrra-Api-Key, X-Api-Key, Mcp-Session-Id, Last-Event-ID');
+    res.setHeader('Access-Control-Expose-Headers', 'mcp-session-id');
+    res.status(204).end();
+});
+app.post('/mcp', async (req, res) => {
+    patchAcceptForMcpStreamable(req);
+    const auth = await requireValidAuth(req, res);
+    if (!auth)
+        return;
+    const sessionId = sessionIdFromReq(req);
+    const body = req.body;
+    const isInitialize = body?.method === 'initialize';
     try {
-        await runWithInboundAuthHeaders(auth, async () => enqueueMcp(async () => {
-            const mcp = await getMcp();
+        if (sessionId && mcpSessions.has(sessionId)) {
+            const session = mcpSessions.get(sessionId);
+            if (session.authFp !== authFingerprint(auth)) {
+                setMcpCors(res);
+                res.status(403).json({ success: false, error: 'Session credentials mismatch.' });
+                return;
+            }
+            setMcpCors(res);
+            await runWithInboundAuthHeaders(auth, () => session.transport.handleRequest(req, res, body));
+            return;
+        }
+        if (sessionId && !isInitialize) {
+            setMcpCors(res);
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Session not found. Please re-initialize.' },
+                id: body?.id ?? null,
+            });
+            return;
+        }
+        const fp = authFingerprint(auth);
+        setMcpCors(res);
+        await runWithInboundAuthHeaders(auth, async () => {
+            const { mcp: server } = await createLyrraMcpServer();
             const transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: undefined,
+                sessionIdGenerator: () => randomUUID(),
             });
-            await mcp.connect(transport);
-            try {
-                await transport.handleRequest(req, res, req.body);
-            }
-            finally {
-                try {
-                    await transport.close();
-                }
-                catch {
-                    /* ignore */
-                }
+            transport.onclose = () => {
+                const sid = transport.sessionId;
+                if (sid)
+                    mcpSessions.delete(sid);
                 try {
-                    await mcp.close();
+                    void server.close();
                 }
                 catch {
                     /* ignore */
                 }
+            };
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+            const newSid = transport.sessionId;
+            if (newSid && !mcpSessions.has(newSid)) {
+                mcpSessions.set(newSid, { transport, server, authFp: fp });
             }
-        }));
+        });
     }
     catch (e) {
-        process.stderr.write(`[lyrra-mcp-http] ${e instanceof Error ? e.stack ?? e.message : e}\n`);
+        process.stderr.write(`[lyrra-mcp-http] POST ${e instanceof Error ? e.stack ?? e.message : e}\n`);
         if (!res.headersSent) {
             res.status(500).json({
                 jsonrpc: '2.0',
@@ -89,11 +180,57 @@ app.all('/mcp', async (req, res) => {
         }
     }
 });
+app.get('/mcp', async (req, res) => {
+    patchAcceptForMcpStreamable(req);
+    const auth = await requireValidAuth(req, res);
+    if (!auth)
+        return;
+    const session = getSessionOr403(req, res, auth);
+    if (!session)
+        return;
+    try {
+        await runWithInboundAuthHeaders(auth, () => session.transport.handleRequest(req, res));
+    }
+    catch (e) {
+        process.stderr.write(`[lyrra-mcp-http] GET ${e instanceof Error ? e.stack ?? e.message : e}\n`);
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+});
+app.delete('/mcp', async (req, res) => {
+    patchAcceptForMcpStreamable(req);
+    const auth = await requireValidAuth(req, res);
+    if (!auth)
+        return;
+    const sid = sessionIdFromReq(req);
+    const session = getSessionOr403(req, res, auth);
+    if (!session)
+        return;
+    try {
+        setMcpCors(res);
+        await runWithInboundAuthHeaders(auth, () => session.transport.handleRequest(req, res));
+        if (sid)
+            mcpSessions.delete(sid);
+    }
+    catch (e) {
+        process.stderr.write(`[lyrra-mcp-http] DELETE ${e instanceof Error ? e.stack ?? e.message : e}\n`);
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+});
 app.get('/health', (_req, res) => {
     res.status(200).type('text/plain').send('ok');
 });
 async function main() {
-    await getMcp();
+    try {
+        await getOpenApiJsonCached();
+        process.stderr.write('[lyrra-mcp-http] OpenAPI cache warmed.\n');
+    }
+    catch (e) {
+        process.stderr.write(`[lyrra-mcp-http] OpenAPI warm skipped (first session will load): ${e instanceof Error ? e.message : e}\n`);
+    }
     app.listen(PORT, '0.0.0.0', () => {
         process.stderr.write(`[lyrra-mcp-http] listening 0.0.0.0:${PORT}  path /mcp  health /health\n`);
     });

package/dist/lyrra-mcp-core.js

@@ -5,7 +5,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { requestOrigin } from './auth-session.js';
 import { callLyrraOperation } from './lyrra-http.js';
-import { fetchOpenApiJson, parseOpenApiOperations } from './openapi-parse.js';
+import { getOpenApiJsonCached, parseOpenApiOperations } from './openapi-parse.js';
 import { eduflowBlockDocToolCount, registerEduflowBlockDocumentationTools, } from './register-eduflow-block-tools.js';
 const MAX_DESC_CHARS = 12_000;
 const MAX_TOOLS_ENV = process.env.LYRRA_MCP_MAX_TOOLS;
@@ -49,7 +49,7 @@ function formatToolResult(result) {
 }
 export async function createLyrraMcpServer() {
     process.stderr.write('[lyrra-mcp] Loading OpenAPI…\n');
-    const spec = await fetchOpenApiJson();
+    const spec = await getOpenApiJsonCached();
     let ops = parseOpenApiOperations(spec);
     const maxTools = MAX_TOOLS_ENV ? parseInt(MAX_TOOLS_ENV, 10) : NaN;
     if (!Number.isNaN(maxTools) && maxTools > 0) {

package/dist/openapi-parse.js

@@ -49,13 +49,44 @@ export function parseOpenApiOperations(spec) {
     out.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
     return out;
 }
-export async function fetchOpenApiJson() {
+/** URLs à essayer pour charger le spec OpenAPI (ordre = priorité). */
+function openApiCandidateUrls() {
     const override = process.env.LYRRA_OPENAPI_URL?.trim();
+    if (override)
+        return [override];
     const origin = requestOrigin();
-    const url = override || `${origin}/api/openapi.json`;
-    const r = await fetch(url, { headers: { Accept: 'application/json' } });
-    if (!r.ok) {
-        throw new Error(`OpenAPI introuvable (${r.status}) : ${url}`);
+    const urls = [`${origin}/api/openapi.json`];
+    /**
+     * Si `LYRRA_API_URL` vaut `https://hôte/mcp/api` (confusion avec l’URL MCP HTTP),
+     * `requestOrigin()` devient `https://hôte/mcp` et l’OpenAPI testée est fausse (502, etc.).
+     * On retente alors la base API standard.
+     */
+    const m = /^(.+)\/mcp$/i.exec(origin);
+    if (m?.[1]) {
+        urls.push(`${m[1]}/api/openapi.json`);
+    }
+    return urls;
+}
+export async function fetchOpenApiJson() {
+    const urls = openApiCandidateUrls();
+    let lastStatus = 0;
+    let lastUrl = '';
+    for (const url of urls) {
+        lastUrl = url;
+        const r = await fetch(url, { headers: { Accept: 'application/json' } });
+        if (r.ok) {
+            return r.json();
+        }
+        lastStatus = r.status;
     }
-    return r.json();
+    throw new Error(`OpenAPI introuvable (${lastStatus}) : ${lastUrl}` +
+        (urls.length > 1
+            ? ` (essayé aussi : ${urls.slice(1).join(', ')})`
+            : ''));
+}
+let openApiJsonPromise = null;
+/** Une seule récupération OpenAPI en mémoire — les sessions MCP HTTP créent chacune un McpServer mais partagent le spec. */
+export function getOpenApiJsonCached() {
+    openApiJsonPromise ??= fetchOpenApiJson();
+    return openApiJsonPromise;
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lyrra/mcp-server",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "MCP server for Lyrra Studio — Claude/Cursor/n8n connect via MCP; tools call your Lyrra REST API (LYRRA_API_URL). Not a REST client substitute.",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
+    "mcp-server": "./dist/index.js",
     "lyrra-mcp": "./dist/index.js",
     "lyrra-mcp-http": "./dist/http-main.js"
   },