@lyrra/mcp-server 1.1.7 → 1.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +39 -28
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,11 +1,20 @@
1
1
  # Lyrra Studio MCP server
2
2
 
3
- **stdio** process (Model Context Protocol): one tool per backend **OpenAPI** operation, plus `lyrra_meta`, `lyrra_search_operations`, and `lyrra://…` resources.
3
+ **Model Context Protocol (MCP)** server for **Lyrra Studio**: your assistant (Claude Desktop, Cursor, n8n MCP Client, …) connects via **MCP**. This process exposes one **MCP tool** per backend **OpenAPI** operation, plus `lyrra_meta`, `lyrra_search_operations`, and `lyrra://…` resources.
4
+
5
+ ## MCP vs “calling the API”
6
+
7
+ | What | Role |
8
+ |------|------|
9
+ | **MCP** | How the AI client talks **to this package** (`stdio` or Streamable HTTP `/mcp`). |
10
+ | **`LYRRA_API_URL`** | Where **this MCP server** reaches your **Lyrra Studio** app over HTTP (`…/api`). It is **not** a separate integration mode: every MCP tool call is translated into REST requests to that base. |
11
+
12
+ If you integrate **without** MCP (scripts, Postman, custom backend), call Lyrra’s REST API directly. If you use **this npm package**, you use **MCP**; the env var only points the server at your Lyrra instance.
4
13
 
5
14
  ## Prerequisites
6
15
 
7
16
  - Node.js ≥ 20
8
- - Reachable Lyrra backend with generated `openapi/openapi.json` (`npm run openapi:generate` in `apps/backend`)
17
+ - A running **Lyrra Studio** backend with `openapi/openapi.json` generated (`npm run openapi:generate` in `apps/backend` of the monorepo)
9
18
 
10
19
  ## Install from npm (Claude / Cursor)
11
20
 
@@ -15,7 +24,7 @@ Published as **`@lyrra/mcp-server`**. No local clone required:
15
24
  npx -y @lyrra/mcp-server
16
25
  ```
17
26
 
18
- In **Claude Desktop** (`claude_desktop_config.json`), prefer:
27
+ In **Claude Desktop** (`claude_desktop_config.json`):
19
28
 
20
29
  ```json
21
30
  {
@@ -33,6 +42,8 @@ In **Claude Desktop** (`claude_desktop_config.json`), prefer:
33
42
  }
34
43
  ```
35
44
 
45
+ `LYRRA_API_URL` must be your Lyrra **REST base** (usually `https://<host>/api`) so MCP tools can execute against the right environment.
46
+
36
47
  Use **Header Auth** keys from the institution dashboard instead of client id/secret:
37
48
 
38
49
  ```json
@@ -43,17 +54,17 @@ Use **Header Auth** keys from the institution dashboard instead of client id/sec
43
54
  }
44
55
  ```
45
56
 
46
- Global install (optional): `npm install -g @lyrra/mcp-server` then run **`lyrra-mcp`** (binary name on `PATH`).
57
+ Global install (optional): `npm install -g @lyrra/mcp-server` then run **`lyrra-mcp`** (binary on `PATH`).
47
58
 
48
- ## Streamable HTTP / n8n (`https://…/mcp`)
59
+ ## Streamable HTTP / n8n (MCP URL `https://…/mcp`)
49
60
 
50
- 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`**.
61
+ Some clients need an **HTTPS MCP endpoint** (not stdio). They use [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) on path **`/mcp`** — still **MCP**, not “the REST API” as the client protocol.
51
62
 
52
- - **Docker:** enable service **`mcp-http`** in `docker-compose.yml` and Nginx **`location /mcp`** (see `apps/frontend/nginx.default.conf`).
63
+ - **Docker:** service **`mcp-http`** in `docker-compose.yml` and Nginx **`location /mcp`** (see `apps/frontend/nginx.default.conf` in the monorepo).
53
64
  - **Auth:** n8n **Header Auth** — same header name and **full** secret as an institution **Header auth** key (e.g. `X-Lyrra-Api-Key` + `rak_…`).
54
- - **Run locally:** `LYRRA_API_URL=http://localhost:3001/api npm run start:http` → listens on **`LYRRA_MCP_HTTP_PORT`** (default **3457**), path `/mcp`.
65
+ - **Run locally:** `LYRRA_API_URL=http://localhost:3001/api npm run start:http` → listens on **`LYRRA_MCP_HTTP_PORT`** (default **3457**), MCP path `/mcp`.
55
66
 
56
- Binaries after global install: **`lyrra-mcp`** (stdio) and **`lyrra-mcp-http`** (HTTP).
67
+ Binaries after global install: **`lyrra-mcp`** (stdio MCP) and **`lyrra-mcp-http`** (HTTP MCP).
57
68
 
58
69
  ## Develop from this monorepo
59
70
 
@@ -80,27 +91,27 @@ Run `npm pkg fix` in this folder to apply npm’s suggested `package.json` fixes
80
91
 
81
92
  | Variable | Purpose |
82
93
  |----------|---------|
83
- | `LYRRA_API_URL` | API base, e.g. `https://yourdomain/api` or `http://localhost:3001/api` |
84
- | `LYRRA_CLIENT_ID` | Key prefix (`keyPrefix`) |
94
+ | `LYRRA_API_URL` | **Lyrra Studio REST base** the MCP server uses **internally** to run tools (e.g. `https://yourdomain/api`). Required for MCP to reach your app — not a choice between “API or MCP”. |
95
+ | `LYRRA_CLIENT_ID` | Key prefix (`keyPrefix`) for **client_credentials** keys |
85
96
  | `LYRRA_CLIENT_SECRET` | Full secret `rak_…` |
86
97
  | `LYRRA_ACCESS_TOKEN` | *(optional)* Bearer JWT if not using key exchange |
87
- | `LYRRA_MCP_HEADER_NAME` | *(optional)* HTTP header name for **Header Auth** keys (e.g. `X-Lyrra-Api-Key`; alias `LYRRA_HEADER_AUTH_NAME`) |
88
- | `LYRRA_MCP_HEADER_VALUE` | *(optional)* Same secret as shown once at key creation (alias `LYRRA_MCP_HEADER_SECRET` or `LYRRA_HEADER_AUTH_VALUE`) |
89
- | `LYRRA_OPENAPI_URL` | *(optional)* OpenAPI JSON URL |
90
- | `LYRRA_MCP_MAX_TOOLS` | *(optional)* Max number of tools (integer) |
91
- | `LYRRA_MCP_HTTP_PORT` | *(HTTP mode only)* Listen port (default `3457`) |
92
- | `LYRRA_MCP_SKIP_AUTH_VALIDATE` | *(optional)* Set to `1` to skip `GET /api/auth/me` on each MCP request (insecure; dev only) |
93
- | `LYRRA_MCP_EXTRA_INBOUND_HEADERS` | *(HTTP mode)* Comma-separated extra header names to copy from the MCP request into Lyrra API calls |
98
+ | `LYRRA_MCP_HEADER_NAME` | *(optional)* HTTP header for **Header Auth** keys (e.g. `X-Lyrra-Api-Key`; alias `LYRRA_HEADER_AUTH_NAME`) |
99
+ | `LYRRA_MCP_HEADER_VALUE` | *(optional)* Same secret as shown once at key creation (aliases `LYRRA_MCP_HEADER_SECRET`, `LYRRA_HEADER_AUTH_VALUE`) |
100
+ | `LYRRA_OPENAPI_URL` | *(optional)* Full OpenAPI JSON URL if not `{origin}/api/openapi.json` |
101
+ | `LYRRA_MCP_MAX_TOOLS` | *(optional)* Cap registered tools (integer) |
102
+ | `LYRRA_MCP_HTTP_PORT` | *(HTTP MCP only)* Listen port (default `3457`) |
103
+ | `LYRRA_MCP_SKIP_AUTH_VALIDATE` | *(optional)* `1` = skip `GET /api/auth/me` on each HTTP MCP request (insecure; dev only) |
104
+ | `LYRRA_MCP_EXTRA_INBOUND_HEADERS` | *(HTTP MCP)* Extra incoming header names to forward to Lyrra when calling REST |
94
105
 
95
- 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 »).
106
+ **Client ID + Secret** → `POST /api/auth/api-key/token` for a JWT. **Header Auth** keys skip that: the MCP server sends the header on **each REST call it makes to Lyrra** (same idea as n8n Header Auth).
96
107
 
97
- ## EduFlow block documentation
108
+ ## EduFlow block documentation (MCP tools)
98
109
 
99
- - Tool **`lyrra_eduflow_blocks_index`**: list of documented types.
100
- - One tool per type: **`lyrra_eduflow_block_<type>`** (e.g. `lyrra_eduflow_block_quiz_mcq`) — role, `data` / `settings` fields, graph, persistence.
101
- - Sheet source: `src/eduflow-block-docs.ts` (keep aligned with the React designer).
110
+ - **`lyrra_eduflow_blocks_index`**: documented block types.
111
+ - **`lyrra_eduflow_block_<type>`** (e.g. `lyrra_eduflow_block_quiz_mcq`): per-type sheet — role, `data` / `settings`, graph, persistence.
112
+ - Source: `src/eduflow-block-docs.ts` in the monorepo.
102
113
 
103
- ## Run
114
+ ## Run (local / monorepo)
104
115
 
105
116
  ```bash
106
117
  npm start
@@ -110,14 +121,14 @@ Development (no pre-build): `npm run dev`
110
121
 
111
122
  ## Automated test (no Lyrra backend)
112
123
 
113
- A minimal OpenAPI is served locally; the script checks `initialize`, `tools/list`, and a `tools/call` on a block sheet:
124
+ A minimal OpenAPI is served locally; the script checks MCP `initialize`, `tools/list`, and a `tools/call` on a block sheet:
114
125
 
115
126
  ```bash
116
127
  npm run test:mcp
117
128
  ```
118
129
 
119
- ## MCP client (local build vs npm)
130
+ ## MCP client wiring (npm vs monorepo)
120
131
 
121
132
  - **Recommended:** `command` `npx`, `args` `["-y", "@lyrra/mcp-server"]` (see above).
122
- - **Local monorepo:** `command` `node`, `args`: **absolute** path to `apps/mcp-server/dist/index.js`
123
- `env`: `LYRRA_API_URL`, `LYRRA_CLIENT_ID`, `LYRRA_CLIENT_SECRET` (or `LYRRA_ACCESS_TOKEN` / header variables).
133
+ - **Local monorepo:** `command` `node`, `args`: absolute path to `apps/mcp-server/dist/index.js` after `npm run build`.
134
+ Same `env` as npm (`LYRRA_API_URL`, credentials or header variables).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lyrra/mcp-server",
3
- "version": "1.1.7",
4
- "description": "Lyrra Studio stdio MCP server — OpenAPI-aligned tools for Claude Desktop, Cursor, and compatible MCP clients",
3
+ "version": "1.1.8",
4
+ "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.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "bin": {