@lyrra/mcp-server 1.1.5 → 1.1.7

package/README.md

@@ -45,6 +45,16 @@ 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 name on `PATH`).
 
+## Streamable HTTP / n8n (`https://…/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`**.
+
+- **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`.
+
+Binaries after global install: **`lyrra-mcp`** (stdio) and **`lyrra-mcp-http`** (HTTP).
+
 ## Develop from this monorepo
 
 ```bash
@@ -78,6 +88,9 @@ Run `npm pkg fix` in this folder to apply npm’s suggested `package.json` fixes
 | `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 »).
 

package/dist/auth-session.js

@@ -4,7 +4,14 @@
  * - 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();
@@ -124,6 +131,10 @@ function headerAuthFromEnv() {
  * 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 };

package/dist/http-incoming-auth.js

@@ -0,0 +1,48 @@
+function single(h) {
+    if (h === undefined)
+        return undefined;
+    return Array.isArray(h) ? h[0] : h;
+}
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailers',
+    'transfer-encoding',
+    'upgrade',
+    'host',
+    'content-length',
+]);
+/**
+ * En-têtes d’auth reçus sur le MCP HTTP à réutiliser vers l’API Lyrra.
+ * n8n « Header Auth » envoie en général X-Lyrra-Api-Key (ou Authorization).
+ */
+export function pickIncomingAuthHeaders(headers) {
+    const out = {};
+    const auth = single(headers['authorization']);
+    if (auth)
+        out.Authorization = auth;
+    const lyrra = single(headers['x-lyrra-api-key']);
+    if (lyrra)
+        out['X-Lyrra-Api-Key'] = lyrra;
+    const xak = single(headers['x-api-key']);
+    if (xak)
+        out['X-Api-Key'] = xak;
+    const extra = process.env.LYRRA_MCP_EXTRA_INBOUND_HEADERS?.split(',') ?? [];
+    for (const raw of extra) {
+        const display = raw.trim();
+        if (!display)
+            continue;
+        const lower = display.toLowerCase();
+        if (HOP_BY_HOP.has(lower))
+            continue;
+        const val = single(headers[lower]);
+        if (val)
+            out[display] = val;
+    }
+    if (Object.keys(out).length === 0)
+        return null;
+    return out;
+}

package/dist/http-main.js

@@ -0,0 +1,104 @@
+#!/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).
+ */
+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';
+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;
+}
+/** 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;
+}
+async function validateAuth(headers) {
+    const origin = requestOrigin();
+    const url = `${origin}/api/auth/me`;
+    const r = await fetch(url, {
+        headers: { Accept: 'application/json', ...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) => {
+    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;
+    }
+    const skipValidate = process.env.LYRRA_MCP_SKIP_AUTH_VALIDATE === '1';
+    if (!skipValidate) {
+        const ok = await validateAuth(auth);
+        if (!ok) {
+            res.status(401).json({
+                success: false,
+                error: 'Invalid Lyrra credentials (GET /api/auth/me failed). Check your Header Auth value.',
+            });
+            return;
+        }
+    }
+    try {
+        await runWithInboundAuthHeaders(auth, async () => enqueueMcp(async () => {
+            const mcp = await getMcp();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await mcp.connect(transport);
+            try {
+                await transport.handleRequest(req, res, req.body);
+            }
+            finally {
+                try {
+                    await transport.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                try {
+                    await mcp.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }));
+    }
+    catch (e) {
+        process.stderr.write(`[lyrra-mcp-http] ${e instanceof Error ? e.stack ?? e.message : e}\n`);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32603, message: 'Internal server error' },
+                id: null,
+            });
+        }
+    }
+});
+app.get('/health', (_req, res) => {
+    res.status(200).type('text/plain').send('ok');
+});
+async function main() {
+    await getMcp();
+    app.listen(PORT, '0.0.0.0', () => {
+        process.stderr.write(`[lyrra-mcp-http] listening 0.0.0.0:${PORT}  path /mcp  health /health\n`);
+    });
+}
+main().catch((e) => {
+    process.stderr.write(`[lyrra-mcp-http] Fatal: ${e instanceof Error ? e.stack ?? e.message : e}\n`);
+    process.exit(1);
+});

package/dist/index.js

@@ -2,176 +2,13 @@
 /**
  * Lyrra Studio MCP stdio server.
  * Run: `npm run build && npm start` in apps/mcp-server (or `npm run dev`).
+ * HTTP (n8n URL) : `npm run start:http` → voir http-main.ts
  */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-import { getLyrraRequestAuthHeaders, requestOrigin } from './auth-session.js';
-import { callLyrraOperation } from './lyrra-http.js';
-import { fetchOpenApiJson, 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;
-function truncateDesc(s) {
-    if (s.length <= MAX_DESC_CHARS)
-        return s;
-    return `${s.slice(0, MAX_DESC_CHARS)}\n\n[… truncated description — see OpenAPI / Swagger]`;
-}
-function zodShapeForOperation(op) {
-    const shape = {
-        query: z
-            .record(z.string(), z.unknown())
-            .optional()
-            .describe('Query parameters (key → value). Serialize complex values as JSON in a key if needed.'),
-        body: z
-            .unknown()
-            .optional()
-            .describe('JSON body (object or array) for POST, PUT, PATCH. Ignored for GET/DELETE.'),
-    };
-    for (const p of op.pathParamNames) {
-        shape[p] = z
-            .string()
-            .describe(`Value for path segment "${p}" in ${op.path}`);
-    }
-    return shape;
-}
-function formatToolResult(result) {
-    const snippet = result.bodyText.length > 120_000 ? `${result.bodyText.slice(0, 120_000)}\n… [truncated]` : result.bodyText;
-    const text = [
-        `HTTP ${result.status}`,
-        result.headers['content-type'] ? `Content-Type: ${result.headers['content-type']}` : '',
-        '',
-        snippet || '(empty body)',
-    ]
-        .filter(Boolean)
-        .join('\n');
-    return {
-        content: [{ type: 'text', text }],
-        isError: result.status >= 400,
-    };
-}
+import { getLyrraRequestAuthHeaders } from './auth-session.js';
+import { createLyrraMcpServer } from './lyrra-mcp-core.js';
 async function main() {
-    process.stderr.write('[lyrra-mcp] Loading OpenAPI…\n');
-    const spec = await fetchOpenApiJson();
-    let ops = parseOpenApiOperations(spec);
-    const maxTools = MAX_TOOLS_ENV ? parseInt(MAX_TOOLS_ENV, 10) : NaN;
-    if (!Number.isNaN(maxTools) && maxTools > 0) {
-        ops = ops.slice(0, maxTools);
-        process.stderr.write(`[lyrra-mcp] LYRRA_MCP_MAX_TOOLS=${maxTools} — ${ops.length} tools registered.\n`);
-    }
-    process.stderr.write(`[lyrra-mcp] ${ops.length} operations → MCP tools.\n`);
-    const mcp = new McpServer({
-        name: 'lyrra-studio',
-        version: '1.0.0',
-        title: 'Lyrra Studio',
-    });
-    registerEduflowBlockDocumentationTools(mcp);
-    process.stderr.write(`[lyrra-mcp] EduFlow docs: ${eduflowBlockDocToolCount()} tools (index + per-block sheets).\n`);
-    mcp.registerTool('lyrra_meta', {
-        description: 'Configuration summary: API origin, registered tool count, useful environment variables (no secrets shown).',
-        inputSchema: z.object({}),
-    }, async () => {
-        let tokenMode = 'CLIENT_ID+SECRET';
-        if (process.env.LYRRA_ACCESS_TOKEN?.trim())
-            tokenMode = 'ACCESS_TOKEN';
-        const hn = process.env.LYRRA_MCP_HEADER_NAME?.trim() || process.env.LYRRA_HEADER_AUTH_NAME?.trim();
-        const hv = process.env.LYRRA_MCP_HEADER_SECRET?.trim() ||
-            process.env.LYRRA_MCP_HEADER_VALUE?.trim() ||
-            process.env.LYRRA_HEADER_AUTH_VALUE?.trim();
-        if (hn && hv)
-            tokenMode = 'HEADER_AUTH';
-        const text = [
-            `Request origin: ${requestOrigin()}`,
-            `OpenAPI tools registered: ${ops.length}`,
-            `EduFlow block doc tools: ${eduflowBlockDocToolCount()} (lyrra_eduflow_blocks_index + lyrra_eduflow_block_*)`,
-            `Token mode: ${tokenMode}`,
-            `LYRRA_API_URL: ${process.env.LYRRA_API_URL ? 'set' : 'missing'}`,
-            `LYRRA_OPENAPI_URL: ${process.env.LYRRA_OPENAPI_URL ? 'set' : 'default /api/openapi.json'}`,
-        ].join('\n');
-        return { content: [{ type: 'text', text }] };
-    });
-    mcp.registerTool('lyrra_search_operations', {
-        description: 'Search operations (operationId, method, path, start of description). Useful when the tool list is long.',
-        inputSchema: z.object({
-            q: z.string().min(1).describe('Search text (case-insensitive)'),
-            limit: z.number().int().min(1).max(80).optional().describe('Max results (default 30)'),
-        }),
-    }, async ({ q, limit }) => {
-        const lim = limit ?? 30;
-        const qq = q.toLowerCase();
-        const hits = ops
-            .filter((o) => o.operationId.toLowerCase().includes(qq) ||
-            o.path.toLowerCase().includes(qq) ||
-            o.method.toLowerCase().includes(qq) ||
-            o.description.toLowerCase().includes(qq))
-            .slice(0, lim);
-        const text = hits.length === 0
-            ? 'No operations found.'
-            : hits.map((o) => `${o.method} ${o.path}\n  operationId: ${o.operationId}`).join('\n\n');
-        return { content: [{ type: 'text', text }] };
-    });
-    const staticGuide = `# Lyrra Studio — MCP integration
-
-- Each tool named after an OpenAPI **operationId** calls **exactly** the documented endpoint.
-- **EduFlow blocks**: tools \`lyrra_eduflow_blocks_index\` then \`lyrra_eduflow_block_<type>\` (e.g. \`lyrra_eduflow_block_quiz_mcq\`) — full sheet: role, \`data\`, \`settings\`, graph.
-- API args: path segments \`{id}\` → required properties of the same name; \`query\`; \`body\` (JSON).
-- Auth: \`LYRRA_CLIENT_ID\` + \`LYRRA_CLIENT_SECRET\` (\`rak_…\`), or \`LYRRA_ACCESS_TOKEN\` (JWT).
-`;
-    mcp.registerResource('lyrra-mcp-guide', 'lyrra://flow-construction-guide', {
-        description: 'How to use the Lyrra MCP server',
-        mimeType: 'text/markdown',
-    }, async () => ({
-        contents: [{ uri: 'lyrra://flow-construction-guide', mimeType: 'text/markdown', text: staticGuide }],
-    }));
-    mcp.registerResource('lyrra-block-types', 'lyrra://block-types', {
-        description: 'Points to MCP tools lyrra_eduflow_block_* (per-type sheet) + persistence via eduflows API',
-        mimeType: 'text/markdown',
-    }, async () => ({
-        contents: [
-            {
-                uri: 'lyrra://block-types',
-                mimeType: 'text/markdown',
-                text: [
-                    '# EduFlow block types (MCP)',
-                    '',
-                    `1. Call **lyrra_eduflow_blocks_index** for documented types (${eduflowBlockDocToolCount() - 1} blocks).`,
-                    '2. Call **lyrra_eduflow_block_<type>** (e.g. `lyrra_eduflow_block_video`) for the full sheet: pedagogical role, `BlockData`, `settings`, connections.',
-                    '3. HTTP persistence: OpenAPI routes under `/api/eduflows/{id}/blocks` and flow save.',
-                    '',
-                    'Code reference: `apps/frontend/src/types/eduflow.ts`, palette `eduflow-designer-palette-blueprint.ts`.',
-                ].join('\n'),
-            },
-        ],
-    }));
-    for (const op of ops) {
-        const inputSchema = z.object(zodShapeForOperation(op));
-        const desc = truncateDesc(`${op.description}\n\n— HTTP ${op.method} \`${op.path}\``);
-        mcp.registerTool(op.operationId, {
-            description: desc,
-            inputSchema,
-        }, async (rawArgs) => {
-            const args = rawArgs;
-            const pathParams = {};
-            for (const name of op.pathParamNames) {
-                const v = args[name];
-                pathParams[name] = typeof v === 'string' ? v : String(v ?? '');
-            }
-            const query = args.query;
-            const body = args.body;
-            try {
-                const result = await callLyrraOperation(op.method, op.path, { pathParams, query, body });
-                return formatToolResult(result);
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                return {
-                    content: [{ type: 'text', text: `Error: ${msg}` }],
-                    isError: true,
-                };
-            }
-        });
-    }
-    // Resolve credentials early (clear message if .env is incomplete)
+    const { mcp } = await createLyrraMcpServer();
     try {
         await getLyrraRequestAuthHeaders();
         process.stderr.write('[lyrra-mcp] API credentials OK.\n');

package/dist/lyrra-mcp-core.js

@@ -0,0 +1,174 @@
+/**
+ * Construction du McpServer Lyrra (outils OpenAPI + EduFlow) — partagé entre stdio et HTTP.
+ */
+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 { eduflowBlockDocToolCount, registerEduflowBlockDocumentationTools, } from './register-eduflow-block-tools.js';
+const MAX_DESC_CHARS = 12_000;
+const MAX_TOOLS_ENV = process.env.LYRRA_MCP_MAX_TOOLS;
+function truncateDesc(s) {
+    if (s.length <= MAX_DESC_CHARS)
+        return s;
+    return `${s.slice(0, MAX_DESC_CHARS)}\n\n[… truncated description — see OpenAPI / Swagger]`;
+}
+function zodShapeForOperation(op) {
+    const shape = {
+        query: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Query parameters (key → value). Serialize complex values as JSON in a key if needed.'),
+        body: z
+            .unknown()
+            .optional()
+            .describe('JSON body (object or array) for POST, PUT, PATCH. Ignored for GET/DELETE.'),
+    };
+    for (const p of op.pathParamNames) {
+        shape[p] = z
+            .string()
+            .describe(`Value for path segment "${p}" in ${op.path}`);
+    }
+    return shape;
+}
+function formatToolResult(result) {
+    const snippet = result.bodyText.length > 120_000 ? `${result.bodyText.slice(0, 120_000)}\n… [truncated]` : result.bodyText;
+    const text = [
+        `HTTP ${result.status}`,
+        result.headers['content-type'] ? `Content-Type: ${result.headers['content-type']}` : '',
+        '',
+        snippet || '(empty body)',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return {
+        content: [{ type: 'text', text }],
+        isError: result.status >= 400,
+    };
+}
+export async function createLyrraMcpServer() {
+    process.stderr.write('[lyrra-mcp] Loading OpenAPI…\n');
+    const spec = await fetchOpenApiJson();
+    let ops = parseOpenApiOperations(spec);
+    const maxTools = MAX_TOOLS_ENV ? parseInt(MAX_TOOLS_ENV, 10) : NaN;
+    if (!Number.isNaN(maxTools) && maxTools > 0) {
+        ops = ops.slice(0, maxTools);
+        process.stderr.write(`[lyrra-mcp] LYRRA_MCP_MAX_TOOLS=${maxTools} — ${ops.length} tools registered.\n`);
+    }
+    process.stderr.write(`[lyrra-mcp] ${ops.length} operations → MCP tools.\n`);
+    const mcp = new McpServer({
+        name: 'lyrra-studio',
+        version: '1.0.0',
+        title: 'Lyrra Studio',
+    });
+    registerEduflowBlockDocumentationTools(mcp);
+    process.stderr.write(`[lyrra-mcp] EduFlow docs: ${eduflowBlockDocToolCount()} tools (index + per-block sheets).\n`);
+    mcp.registerTool('lyrra_meta', {
+        description: 'Configuration summary: API origin, registered tool count, useful environment variables (no secrets shown).',
+        inputSchema: z.object({}),
+    }, async () => {
+        let tokenMode = 'CLIENT_ID+SECRET';
+        if (process.env.LYRRA_ACCESS_TOKEN?.trim())
+            tokenMode = 'ACCESS_TOKEN';
+        const hn = process.env.LYRRA_MCP_HEADER_NAME?.trim() || process.env.LYRRA_HEADER_AUTH_NAME?.trim();
+        const hv = process.env.LYRRA_MCP_HEADER_SECRET?.trim() ||
+            process.env.LYRRA_MCP_HEADER_VALUE?.trim() ||
+            process.env.LYRRA_HEADER_AUTH_VALUE?.trim();
+        if (hn && hv)
+            tokenMode = 'HEADER_AUTH_ENV';
+        const text = [
+            `Request origin: ${requestOrigin()}`,
+            `OpenAPI tools registered: ${ops.length}`,
+            `EduFlow block doc tools: ${eduflowBlockDocToolCount()} (lyrra_eduflow_blocks_index + lyrra_eduflow_block_*)`,
+            `Token mode: ${tokenMode}`,
+            `HTTP MCP: forward Authorization, X-Lyrra-Api-Key, or X-Api-Key from each request (n8n Header Auth).`,
+            `LYRRA_API_URL: ${process.env.LYRRA_API_URL ? 'set' : 'missing'}`,
+            `LYRRA_OPENAPI_URL: ${process.env.LYRRA_OPENAPI_URL ? 'set' : 'default /api/openapi.json'}`,
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+    mcp.registerTool('lyrra_search_operations', {
+        description: 'Search operations (operationId, method, path, start of description). Useful when the tool list is long.',
+        inputSchema: z.object({
+            q: z.string().min(1).describe('Search text (case-insensitive)'),
+            limit: z.number().int().min(1).max(80).optional().describe('Max results (default 30)'),
+        }),
+    }, async ({ q, limit }) => {
+        const lim = limit ?? 30;
+        const qq = q.toLowerCase();
+        const hits = ops
+            .filter((o) => o.operationId.toLowerCase().includes(qq) ||
+            o.path.toLowerCase().includes(qq) ||
+            o.method.toLowerCase().includes(qq) ||
+            o.description.toLowerCase().includes(qq))
+            .slice(0, lim);
+        const text = hits.length === 0
+            ? 'No operations found.'
+            : hits.map((o) => `${o.method} ${o.path}\n  operationId: ${o.operationId}`).join('\n\n');
+        return { content: [{ type: 'text', text }] };
+    });
+    const staticGuide = `# Lyrra Studio — MCP integration
+
+- Each tool named after an OpenAPI **operationId** calls **exactly** the documented endpoint.
+- **EduFlow blocks**: tools \`lyrra_eduflow_blocks_index\` then \`lyrra_eduflow_block_<type>\` (e.g. \`lyrra_eduflow_block_quiz_mcq\`) — full sheet: role, \`data\`, \`settings\`, graph.
+- API args: path segments \`{id}\` → required properties of the same name; \`query\`; \`body\` (JSON).
+- Auth (stdio / env): \`LYRRA_CLIENT_ID\` + \`LYRRA_CLIENT_SECRET\`, \`LYRRA_ACCESS_TOKEN\`, or \`LYRRA_MCP_HEADER_NAME\` + value.
+- Auth (HTTP MCP / n8n): send **Header Auth** on every MCP request (e.g. \`X-Lyrra-Api-Key: rak_…\` matching your institution key).
+`;
+    mcp.registerResource('lyrra-mcp-guide', 'lyrra://flow-construction-guide', {
+        description: 'How to use the Lyrra MCP server',
+        mimeType: 'text/markdown',
+    }, async () => ({
+        contents: [{ uri: 'lyrra://flow-construction-guide', mimeType: 'text/markdown', text: staticGuide }],
+    }));
+    mcp.registerResource('lyrra-block-types', 'lyrra://block-types', {
+        description: 'Points to MCP tools lyrra_eduflow_block_* (per-type sheet) + persistence via eduflows API',
+        mimeType: 'text/markdown',
+    }, async () => ({
+        contents: [
+            {
+                uri: 'lyrra://block-types',
+                mimeType: 'text/markdown',
+                text: [
+                    '# EduFlow block types (MCP)',
+                    '',
+                    `1. Call **lyrra_eduflow_blocks_index** for documented types (${eduflowBlockDocToolCount() - 1} blocks).`,
+                    '2. Call **lyrra_eduflow_block_<type>** (e.g. `lyrra_eduflow_block_video`) for the full sheet: pedagogical role, `BlockData`, `settings`, connections.',
+                    '3. HTTP persistence: OpenAPI routes under `/api/eduflows/{id}/blocks` and flow save.',
+                    '',
+                    'Code reference: `apps/frontend/src/types/eduflow.ts`, palette `eduflow-designer-palette-blueprint.ts`.',
+                ].join('\n'),
+            },
+        ],
+    }));
+    for (const op of ops) {
+        const inputSchema = z.object(zodShapeForOperation(op));
+        const desc = truncateDesc(`${op.description}\n\n— HTTP ${op.method} \`${op.path}\``);
+        mcp.registerTool(op.operationId, {
+            description: desc,
+            inputSchema,
+        }, async (rawArgs) => {
+            const args = rawArgs;
+            const pathParams = {};
+            for (const name of op.pathParamNames) {
+                const v = args[name];
+                pathParams[name] = typeof v === 'string' ? v : String(v ?? '');
+            }
+            const query = args.query;
+            const body = args.body;
+            try {
+                const result = await callLyrraOperation(op.method, op.path, { pathParams, query, body });
+                return formatToolResult(result);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return {
+                    content: [{ type: 'text', text: `Error: ${msg}` }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    return { mcp, operationsCount: ops.length };
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@lyrra/mcp-server",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Lyrra Studio stdio MCP server — OpenAPI-aligned tools for Claude Desktop, Cursor, and compatible MCP clients",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "lyrra-mcp": "./dist/index.js"
+    "lyrra-mcp": "./dist/index.js",
+    "lyrra-mcp-http": "./dist/http-main.js"
   },
   "files": [
     "dist",
@@ -15,7 +16,9 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
+    "start:http": "node dist/http-main.js",
     "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/http-main.ts",
     "test:mcp": "npm run build && node scripts/mcp-smoke-test.mjs"
   },
   "engines": {
@@ -42,9 +45,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/express": "^5.0.0",
     "@types/node": "^20.10.8",
     "tsx": "^4.7.0",
     "typescript": "^5.2.2"