@lenne.tech/nest-server 11.42.4 → 11.42.6

package/docs/REQUEST-LIFECYCLE.md

@@ -569,7 +569,7 @@ Both use body-parser's default limit of **100 kB** unless `bodyParser` says othe
 bodyParser: { json: { limit: '2mb' } },
 ```
 
-`CoreBodyParserInitializer` applies it during module init by replacing the handle of the global parser layers NestJS created — in place, because NestJS registers them before any init hook runs and a parser appended later would sit behind the routes. Running during module init is what makes the limit hold under `Test.createTestingModule()`, which never runs `main.ts`. A path-scoped parser (`server.use('/upload', json({ limit }))` in `main.ts`) runs before the global one and is left untouched — that remains the way to give one path a different limit.
+`CoreBodyParserInitializer` applies it during module init by replacing the handle of the global parser layers NestJS created — in place, because NestJS registers them before any init hook runs and a parser appended later would sit behind the routes. Running during module init is what makes the limit hold under `Test.createTestingModule()`, which never runs `main.ts`. A path-scoped parser (`server.use('/upload', json({ limit }))` in `main.ts`) runs before the global one and is left untouched — that remains the way to give one path a different limit. Keep `server.useBodyParser('json')` (or `'urlencoded'`) in `main.ts` next to it: NestJS registers its global parser only when no layer with the same function name exists, so a path-scoped one registered before `app.init()` suppresses it, and every other path receives an empty body. Since 11.42.6 `CoreBodyParserInitializer` warns at boot in that case.
 
 The parser runs **before authentication and routing**. Over the limit, the whole request is refused:
 

package/migration-guides/11.42.3-to-11.42.4.md

@@ -19,7 +19,8 @@ pnpm update --depth Infinity proxy-addr
 ```
 
 Then add the `@graphql-tools/utils` override from §3 to `pnpm-workspace.yaml`, run `pnpm install`,
-and check §3 for an older `@graphql-tools/utils` 11.x copy, which the override does not reach.
+refresh `source-map-js` (§3), check §3 for an older `@graphql-tools/utils` 11.x copy, which the
+override does not reach, and commit `pnpm-workspace.yaml` together with `pnpm-lock.yaml`.
 Vendor-mode projects pick up the core update and need the same two dependency steps. The body limit
 needs no configuration: unset, both parsers keep the 100 kB they had.
 
@@ -62,13 +63,28 @@ server.useBodyParser('json', { limit: '2mb' });
 bodyParser: { json: { limit: '2mb' } },
 ```
 
+**Exception: keep `useBodyParser()` when `main.ts` also registers a path-scoped parser** such as
+`server.use('/upload', json({ limit: '20mb' }))`. NestJS registers its own global parser only if no
+layer with the same function name exists yet, and a path-scoped `json()` registered before
+`app.init()` counts as one. Removing `useBodyParser()` then leaves the app without a global JSON
+parser: every request outside that path reaches its handler with an empty body, and a sign-in fails
+with a validation error. Keep `server.useBodyParser('json')` (the configured limit is applied to it)
+and set the limit in the config as above. Since 11.42.6 the server warns at boot when it finds this.
+
+**Starter-based projects:** `config.env.ts` builds `local` / `e2e` / `ci` from `localConfig()` and the
+deployed environments from `deployedConfig()`. Put the limit where BOTH see it — the starter ships a
+shared `PROJECT_BODY_PARSER` constant for this since its 11.42.4 update — or set
+`NSC__BODY_PARSER__JSON__LIMIT` in the environment. A value only in the deployed block leaves the e2e
+suite and `lt dev up` at 100 kB.
+
 The config is applied during module init, so it holds in every test that builds the app with
 `Test.createTestingModule(...).createNestApplication()` — which never runs `main.ts`, so a
 `useBodyParser()` call there never reached the e2e suite. Once configured, the value also replaces a
 global parser your `main.ts` registered; keeping both is harmless, but the config wins.
 
 A **path-scoped** parser is left alone: `server.use('/upload', json({ limit: '20mb' }))` in `main.ts`
-still gives that one path its own limit. The parser runs before routing, so a per-route limit can only
+still gives that one path its own limit, as long as the global parser stays registered next to it
+(see the exception above). The parser runs before routing, so a per-route limit can only
 key on the path — and all GraphQL operations share one.
 
 **`rawBody: true`:** `req.rawBody` is kept for apps created with `NestFactory.create(…, { rawBody:
@@ -101,7 +117,7 @@ refused request, with method, path (without query string) and the config key to
 The status code is unchanged. Only clients that compare the message text against
 `'request entity too large'` need adjusting — branch on the status or on `LTNS_0304` instead.
 
-## 3. Two dependency advisories your project must fix itself
+## 3. Dependency advisories your project must fix itself
 
 `pnpm` overrides apply only to the project that runs the install, so the framework's own fixes do not
 reach your tree — see [docs/security-overrides.md](../docs/security-overrides.md).
@@ -110,6 +126,7 @@ reach your tree — see [docs/security-overrides.md](../docs/security-overrides.
 | ------- | -------- | ----------------------- |
 | `proxy-addr` | [GHSA-jqcg-44mw-7w3h](https://github.com/advisories/GHSA-jqcg-44mw-7w3h) — **critical**: IP spoofing through an IPv4-mapped IPv6 address in a trusted subnet. Patched `>=2.0.8` | A lockfile refresh. `express` requests `^2.0.7`, so `2.0.8` is in range, but an existing lockfile stays on `2.0.7` |
 | `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep` (schema assembly). Covers `<=12.0.0` — **11.x included, with no 11.x fix**. Patched `>=12.0.1` | An override for the copy `@nestjs/graphql` 13.4.5 exact-pins (`12.0.0`), and — in an older lockfile — a refresh of `@graphql-tools/schema` / `merge`, which can still pull in 11.x (see below) |
+| `source-map-js` | [GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q) — high: event-loop DoS through indexed source-map section offsets. Patched `>=1.2.2`. **Dev tooling only** (vitest > vite > postcss), but `pnpm audit` — and therefore `check` — reports it | A lockfile refresh: `pnpm update --depth Infinity source-map-js`. If `postcss` keeps a `1.2.1` copy, re-resolve it the same way rather than with `pnpm dedupe`, which moves unrelated peers too |
 
 `proxy-addr` is what Express uses to compute `request.ip` from `X-Forwarded-For` as far as
 `trustProxy` allows. With `trustProxy` set, every IP-keyed rate limit — the framework's own and any of
@@ -146,7 +163,13 @@ The current releases (schema 10.1.3, merge 9.2.6) request utils `^12.0.3`, which
 (22.22) and Node 24 satisfy that; if your `engines.node` still declares a lower floor, raise it — the
 override above cannot hold this copy back, because `^12.0.3` does not intersect its key.
 
-Then `pnpm install` and `pnpm audit` — both advisories must be gone.
+Then `pnpm install` and `pnpm audit` — the advisories must be gone.
+
+**Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** Every step above leaves a consistent
+lockfile once it has run to the end, but the override only reaches the lockfile through the
+`pnpm install` that follows it. A `pnpm-workspace.yaml` committed with the override and without the
+re-installed lockfile fails every `pnpm install --frozen-lockfile` — typically the Docker image build.
+Check with `pnpm install --frozen-lockfile` locally before you push.
 
 ## 4. Native Better-Auth endpoints accept the session when the secret is auto-generated
 

package/migration-guides/11.42.4-to-11.42.5.md

@@ -0,0 +1,104 @@
+# Migration Guide: 11.42.4 → 11.42.5
+
+## Overview
+
+| Category             | Details                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **New feature**      | `TestHelper.mcpSession()` / `TestHelper.mcp()` — MCP tests without hand-written SSE parsing (§1)            |
+| **Tooling**          | `check:overrides` accepts a declared "fix exists, but this consumer cannot use it" suppression that expires by itself (§2) |
+| **Docs**             | The 11.42.3 → 11.42.4 guide gained three steps; check them if you already applied it (§3)                   |
+| **Breaking Changes** | None                                                                                                        |
+| **Migration Effort** | None required — `pnpm update`. Adopting the helpers is optional                                             |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; the new helpers arrive with `src/test/`. No configuration
+change is required.
+
+## 1. TestHelper: MCP tests without SSE parsing
+
+Projects that enable the AI module's MCP server (`ai.mcp` in `config.env.ts`) should test their tools over
+MCP as well as over REST/GraphQL: MCP has its own role filter and sessions, and a refused tool comes back as
+a result with `isError: true`, not as an HTTP error. Until now such a test had to set the right `Accept`
+header, carry the `mcp-session-id` header, and parse the SSE stream by hand. `TestHelper` now does that:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+expect((await session.listTools()).map((tool) => tool.name)).not.toContain('delete_user');
+
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.json.data.length).toBeGreaterThan(0);
+
+await session.close();
+```
+
+`testHelper.mcp(message, { statusCode, sessionId, token })` sends a single JSON-RPC message for the
+HTTP-level cases (401 without a token, 404 for another user's session). Full reference: `src/test/README.md`
+→ "MCP Testing".
+
+The helpers are additive and build on `testHelper.rest()`, so `token` and `cookies` behave as there. They add
+no dependency, so vendor-mode projects receive them with `src/test/`. A project with its own MCP module (not
+the AI module's `/ai/mcp`) passes its endpoint as `path`.
+
+## 2. `check:overrides`: a suppression for a fix the consumer cannot use
+
+`auditConfig.ignoreGhsas` used to be usable only for advisories with no fix at all — the moment any fix
+appeared, `check:overrides` failed with `FIX AVAILABLE`. That is right in the common case and a dead end in
+one: the fix exists, but the package that pulls in the vulnerable version cannot use it (for example, a
+patched major removed an export the consumer imports).
+
+That case can now be declared next to the suppression:
+
+```yaml
+auditConfig:
+  ignoreGhsas:
+    - GHSA-x6jw-m9v5-85vh
+  unusableFixConsumers:
+    GHSA-x6jw-m9v5-85vh: '@nuxt/devtools@3.4.1 cannot use 4.0.1'
+```
+
+The declaration expires by itself: `check:overrides` fails with `RE-TEST` as soon as the consumer leaves the
+tree or changes version, the advisory offers a patched version nobody assessed (a backport), or anything other
+than exactly that consumer version pulls the vulnerable package — including a direct dependency of your own
+project. An undeclared suppression of a fixed advisory still fails on sight.
+
+This is a change to the guard script, not to the published runtime: projects created from
+nest-server-starter or lt-monorepo receive it with their template update. Exhaust the remedies first (raise
+the vulnerable package, raise or patch the consumer); the rules and the reasoning are in
+`.claude/rules/package-management.md` → "When the fix exists and the consumer cannot use it".
+
+## 3. Three steps added to the 11.42.3 → 11.42.4 guide
+
+If you already applied [11.42.3 → 11.42.4](./11.42.3-to-11.42.4.md), check these — they were added after its
+release:
+
+1. **`source-map-js` < 1.2.2** ([GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q),
+   high, dev tooling only) is also reported by `pnpm audit`: `pnpm update --depth Infinity source-map-js`.
+2. **Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** An override only reaches the lockfile through
+   the `pnpm install` that follows it; a workspace file committed without the re-installed lockfile fails every
+   `pnpm install --frozen-lockfile`, typically the Docker image build.
+3. **Starter-based projects:** set `bodyParser` where both `localConfig()` and `deployedConfig()` see it (the
+   starter ships a shared `PROJECT_BODY_PARSER` constant), or via `NSC__BODY_PARSER__JSON__LIMIT`. A value only
+   in the deployed block leaves the e2e suite and `lt dev up` at 100 kB.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `check:overrides` fails with `RE-TEST` on a declared suppression | The consumer moved, a new patched version appeared, or another package (or your project directly) now pulls the vulnerable package | Re-assess: take the fix if it is now usable, otherwise update the declaration with what you re-checked (§2) |
+| `check:overrides` fails with `FIX AVAILABLE` | A suppressed advisory gained a fix, and no declaration explains why it cannot be used | Take the fix; declare only after the remedies are exhausted (§2) |
+| `session.callTool()` throws instead of returning `isError` | The JSON-RPC call itself failed (protocol error), not the tool | Assert on `session.request(...)` for protocol-level errors (§1) |
+
+## Module Documentation
+
+- [TestHelper README — MCP Testing](../src/test/README.md)
+- [AI module README](../src/core/modules/ai/README.md)
+- `.claude/rules/package-management.md` — suppressions, overrides and the `check:overrides` guard

package/migration-guides/11.42.5-to-11.42.6.md

@@ -0,0 +1,97 @@
+# Migration Guide: 11.42.5 → 11.42.6
+
+## Overview
+
+| Category             | Details                                                                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Correction**       | The 11.42.3 → 11.42.4 guide told every project to drop `useBodyParser()` from `main.ts`. With a path-scoped parser in `main.ts` that removes JSON parsing everywhere else (§1) |
+| **Improvement**      | The server warns at boot when NestJS skipped its global body parser because of such a path-scoped one (§1)   |
+| **Tooling**          | `check:overrides` no longer reports a failed audit as clean, and its probe follows `pnpm_config_registry` (§2) |
+| **Breaking Changes** | None                                                                                                         |
+| **Migration Effort** | None for most projects. Projects that removed `useBodyParser()` while registering a path-scoped parser in `main.ts` must add it back (§1) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Then check `main.ts` as described in §1. Vendor-mode projects pick up the core update and need the
+same check.
+
+## 1. Keep `useBodyParser()` next to a path-scoped parser
+
+§1 of the [11.42.3 → 11.42.4 guide](./11.42.3-to-11.42.4.md) recommended moving the body limit from
+`main.ts` into `bodyParser.json.limit` and deleting the `useBodyParser()` call. That is right, with one
+exception the guide did not name.
+
+NestJS registers its own global JSON and URL-encoded parsers inside `app.init()`, but only when no
+layer with the same function name exists yet. It compares the NAME and nothing else. A path-scoped
+parser registered in `main.ts` before `listen()` carries that name:
+
+```typescript
+// main.ts
+server.use('/diagnostics', json({ limit: '256kb' })); // a layer named `jsonParser`
+```
+
+With `useBodyParser()` removed, NestJS treats the JSON parser as already applied and registers none.
+Every request outside `/diagnostics` then reaches its handler with an empty body. A sign-in fails with
+a validation error such as "Missing input", and before this release nothing was logged.
+
+**Check `main.ts`.** If it registers `json(...)` or `urlencoded(...)` on a path, keep or restore the
+global parser next to it:
+
+```typescript
+// main.ts
+server.use('/diagnostics', json({ limit: '256kb' }));
+server.useBodyParser('json'); // the configured bodyParser.json.limit is applied to it
+```
+
+Keep the limit itself in the config (`bodyParser.json.limit`), where it also holds under
+`Test.createTestingModule()`. The e2e suite cannot catch the missing parser: the testing module never
+runs `main.ts`, so it never registers the path-scoped parser either.
+
+Since 11.42.6 the server logs a warning at boot in exactly this situation:
+
+```
+No global json body parser is registered: NestJS skips its own when a layer named `jsonParser`
+already exists, and a path-scoped `json()` parser registered before `app.init()` counts as one. …
+```
+
+The framework only reports it. It does not register the missing parser itself: NestJS would have put
+it after everything `main.ts` registered, and that position is no longer known during module init. A
+raw-body webhook or a proxy registered after the path-scoped parser must keep receiving the unread
+request stream.
+
+## 2. `check:overrides`: a failed audit is no longer reported as clean
+
+Two fixes in `scripts/check-overrides.mjs` (and the shared registry block in `scripts/check.mjs`):
+
+- When pnpm 11 cannot reach the registry, `pnpm audit --json` prints
+  `{"error": {"message": "fetch failed"}}` instead of a report. The guard read that as "0 advisories"
+  and printed `ok — N override(s) checked … none is failing`. It now prints
+  `could not obtain an audit report` (exit 0) on a live run, and fails (exit 1) when the failed report
+  was passed in with `--audit-file`, which is the CI path. The suppression checks still run in that
+  case, because they ask the GitHub Advisory API rather than the audit: a suppressed advisory that
+  gained a fix still fails with `FIX AVAILABLE`.
+- The clean-tree probe reads `pnpm_config_registry`, the variable pnpm 11 audits against. It used to
+  read `npm_config_registry`, which pnpm 11 ignores, and could then ask a registry the audit never used.
+
+`scripts/` is not part of the npm package. Projects created from nest-server-starter or lt-monorepo
+receive these fixes with their template update.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Boot warning "No global json body parser is registered" | `main.ts` registers a path-scoped `json()` and no global parser | Add `server.useBodyParser('json')` to `main.ts` (§1) |
+| Requests arrive with an empty body outside one path; sign-in reports "Missing input" | Same cause, on a version before 11.42.6 | Same fix (§1) |
+| `check:overrides` prints `could not obtain an audit report (fetch failed)` | The npm registry was not reachable during the audit | Re-run with network access, or pass a captured report with `--audit-file` |
+| `check:overrides` fails with `records a failed audit, not a result` | The report passed with `--audit-file` is a pnpm error, not an audit | Capture the report again once the registry answers |
+
+## Module Documentation
+
+- [REQUEST-LIFECYCLE.md — 0d. Body parsers](../docs/REQUEST-LIFECYCLE.md)
+- [11.42.3 → 11.42.4 guide §1](./11.42.3-to-11.42.4.md)
+- `.claude/rules/configurable-features.md` — Body Parser Limits row
+- `.claude/rules/package-management.md` — the `check:overrides` guard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.4",
+  "version": "11.42.6",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/interfaces/server-options.interface.ts

@@ -2335,6 +2335,11 @@ export interface IServerOptions {
    * (`server.use('/upload', json({ limit }))`) is left alone, and stays the way to give ONE path a
    * different limit, since the parser runs before routing and GraphQL shares a single path anyway.
    *
+   * Keep `server.useBodyParser('json')` in `main.ts` next to such a path-scoped parser. NestJS
+   * registers its own global parser only if no layer with the same function name exists yet, so a
+   * path-scoped `json()` registered before `app.init()` makes it skip the global one, and requests
+   * outside that path arrive with an empty body. The initializer warns at boot when it finds that.
+   *
    * One caveat: under the testing module the options passed to `createNestApplication()` are not
    * visible to providers, so a test app created with `{ rawBody: true }` gets no `req.rawBody` from
    * a CONFIGURED parser. Applications created with `NestFactory.create()` are not affected.

package/src/core/common/services/core-body-parser.initializer.ts

@@ -90,11 +90,8 @@ export class CoreBodyParserInitializer implements OnModuleInit {
       const limit = this.resolveLimit(type, config?.[type]?.limit);
       const layers = stack.filter((layer) => this.isGlobalParserLayer(layer, type));
 
-      if (limit !== undefined && !layers.length) {
-        this.logger.warn(
-          `bodyParser.${type}.limit is configured, but no global ${type} body parser is registered ` +
-            '(was the app created with `bodyParser: false`?) — the limit has no effect.',
-        );
+      if (!layers.length) {
+        this.warnMissingGlobalParser(type, stack, limit);
         continue;
       }
 
@@ -147,6 +144,18 @@ export class CoreBodyParserInitializer implements OnModuleInit {
     return layer?.slash === true && typeof layer.handle === 'function' && layer.handle.name === PARSER_NAMES[type];
   }
 
+  /**
+   * Whether the application was created without `bodyParser: false`.
+   *
+   * Read from the same container options as `rawBody`. Under `Test.createTestingModule()` those
+   * options never reach the container, so the answer there is always "enabled".
+   */
+  protected isBodyParserEnabled(): boolean {
+    const container = (this.moduleRef as unknown as { container?: { contextOptions?: { bodyParser?: boolean } } })
+      ?.container;
+    return container?.contextOptions?.bodyParser !== false;
+  }
+
   /**
    * Whether the application was created with `rawBody: true`.
    *
@@ -210,6 +219,39 @@ export class CoreBodyParserInitializer implements OnModuleInit {
     );
   }
 
+  /**
+   * Explain why there is no global parser of this type, when there should be one.
+   *
+   * NestJS registers its own parsers inside `app.init()` only if no layer with the parser's function
+   * name exists yet (`ExpressAdapter.isMiddlewareApplied()` compares the NAME and nothing else). A
+   * path-scoped `server.use('/upload', json({ limit }))` in `main.ts` therefore counts as "applied",
+   * NestJS skips its global parser, and every request outside that path reaches its handler with an
+   * empty body — a sign-in fails with a validation error, and nothing says why. Restoring the parser
+   * from here is not safe: NestJS would have placed it after everything `main.ts` registered, and that
+   * position is no longer knowable during module init (a raw-body webhook or a proxy registered after
+   * the path-scoped parser must keep seeing the unread stream). So this reports, with the remedy.
+   */
+  protected warnMissingGlobalParser(type: CoreBodyParserType, stack: ExpressLayer[], limit: number | undefined): void {
+    const name = PARSER_NAMES[type];
+    const shadowed = stack.some((layer) => layer?.slash !== true && layer?.handle?.name === name);
+    if (shadowed && this.isBodyParserEnabled()) {
+      this.logger.warn(
+        `No global ${type} body parser is registered: NestJS skips its own when a layer named \`${name}\` ` +
+          `already exists, and a path-scoped \`${type}()\` parser registered before \`app.init()\` counts as one. ` +
+          `Every request outside that path reaches its handler with an EMPTY body. Register the global parser ` +
+          `in main.ts as well — \`server.useBodyParser('${type}')\` — a configured \`bodyParser.${type}.limit\` ` +
+          'is applied to it.',
+      );
+      return;
+    }
+    if (limit !== undefined) {
+      this.logger.warn(
+        `bodyParser.${type}.limit is configured, but no global ${type} body parser is registered ` +
+          '(was the app created with `bodyParser: false`?) — the limit has no effect.',
+      );
+    }
+  }
+
   /**
    * Wrap a parser so its 413 is translated, keeping the name NestJS identifies the layer by.
    *

package/src/test/README.md

@@ -243,4 +243,82 @@ const result = await testHelper.graphQl(
 );
 ```
 
-See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+
+## MCP Testing (`testHelper.mcp()` / `testHelper.mcpSession()`)
+
+An MCP client reaches the same services as REST and GraphQL through its own door: the MCP server of the AI module
+(`/ai/mcp`, enabled with `ai.mcp` in `config.env.ts`) has its own role filter, its own sessions, and reports a refused
+or failing tool as a result with `isError: true` instead of an HTTP error. A project that enables MCP therefore tests
+its tools over MCP too, next to its API tests.
+
+The transport answers requests as an SSE stream. These helpers handle the stream, the session header and the
+handshake, so a test reads results directly.
+
+### `mcpSession(options?)`
+
+Opens a session the way every MCP client does (`initialize`, then `notifications/initialized`) for the user of `token`
+or `cookies`:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+// tools/list — filtered by the user's roles
+const names = (await session.listTools()).map((tool) => tool.name);
+expect(names).toContain('find_users');
+
+// tools/call — `json` is the first text content parsed as JSON (the tool's own result)
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.isError).toBeFalsy();
+expect(result.json.data.length).toBeGreaterThan(0);
+
+// A tool outside the user's roles is refused, not run
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+// Any other JSON-RPC request; returns the whole message, protocol errors included
+const reply = await session.request('prompts/list');
+
+// End the session server-side
+await session.close();
+```
+
+| Member                               | Description                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| `sessionId`                          | `mcp-session-id` the server assigned                                     |
+| `initializeResult`                   | Result of `initialize` (`serverInfo`, `capabilities`, `protocolVersion`) |
+| `listTools()`                        | `tools/list`, returns the tools array                                    |
+| `callTool(name, args?)`              | `tools/call`, returns the `CallToolResult` plus `json`                   |
+| `request(method, params?, options?)` | Any request in the session, returns the JSON-RPC message                 |
+| `close()`                            | `DELETE` with the session id                                             |
+
+### `mcp(message, options?)`
+
+Sends a single JSON-RPC message and returns `{ message, response, sessionId }`. Use it for the HTTP-level cases a
+session hides:
+
+```typescript
+// No token → 401
+await testHelper.mcp({ id: 1, method: 'initialize', params: {} }, { statusCode: 401 });
+
+// Another user's session id → 404 (not 403: confirming the id exists would be an oracle)
+await testHelper.mcp(
+  { id: 2, method: 'tools/list' },
+  { sessionId: adminSession.sessionId, statusCode: 404, token: userToken },
+);
+```
+
+### TestMcpOptions
+
+| Option             | Type                               | Default                         | Description                                     |
+| ------------------ | ---------------------------------- | ------------------------------- | ----------------------------------------------- |
+| `token`            | `string`                           | -                               | Bearer token, the same one `rest()` takes       |
+| `cookies`          | `string \| Record<string, string>` | -                               | Cookie authentication, same modes as `rest()`   |
+| `sessionId`        | `string`                           | -                               | `mcp-session-id` header (`mcp()` only)          |
+| `statusCode`       | `number`                           | `200`, `202` for a notification | Expected HTTP status (`mcp()` only)             |
+| `path`             | `string`                           | `'/ai/mcp'`                     | Endpoint, for a project with its own MCP module |
+| `headers`          | `Record<string, string>`           | -                               | Additional headers                              |
+| `log` / `logError` | `boolean`                          | `false`                         | Same as `rest()`                                |
+
+`mcpSession()` additionally takes `clientInfo` and `protocolVersion` for the `initialize` request.
+`TestHelper.parseMcpMessage(response)` is the parser behind both, for tests that send requests themselves.