@frontmcp/skills 1.8.7 → 1.9.0

package/catalog/frontmcp-setup/references/project-structure-nx.md

@@ -167,8 +167,11 @@ nx g @frontmcp/nx:lib shared-utils
 ## Build and Test Commands
 
 ```bash
-# Build a specific server
-nx build gateway
+# Build a specific server (server projects are named server-<name>)
+nx build server-gateway
+
+# Type-check a project
+nx typecheck billing
 
 # Test a specific app
 nx test billing
@@ -233,8 +236,8 @@ Use `nx graph` to visualize the dependency graph and ensure no circular imports
 
 ### Build and Test
 
-- [ ] `nx build gateway` (or server name) succeeds without errors
-- [ ] `nx test billing` (or app name) passes all tests
+- [ ] `nx build server-gateway` (or `server-<name>`) succeeds without errors
+- [ ] `nx test billing` (or app name) passes all tests; new apps and libraries start with a spec
 - [ ] `nx run-many -t test` runs all tests across the workspace
 - [ ] `nx graph` shows no circular dependencies between apps
 

package/catalog/frontmcp-setup/references/setup-project.md

@@ -404,6 +404,19 @@ frontmcp dev --show-conflict
 > `http.port: 4000` in metadata makes the child bind to 4000 regardless of
 > `--port`/`PORT`, so the pre-flight probe becomes advisory only.
 
+Ctrl+C, or `SIGINT` / `SIGTERM` sent to the `frontmcp dev` process alone
+(`kill <pid>`), stops the whole tree — tsx, the server it forks and the type
+checker — and the command returns once the port is free.
+
+`frontmcp dev` and `frontmcp build` work from any subfolder: they find
+`frontmcp.config.*` by walking up and run from its folder, so `entry`,
+`tsconfig.json` and `.env` resolve from the project root.
+
+`frontmcp init` edits `tsconfig.json` in place, keeping comments and trailing
+commas; a file that is not valid JSON(C) is reported (line and column) and left
+untouched, never overwritten. So is one that declares an option `init` must set
+more than once — only the last occurrence takes effect, so remove the duplicate.
+
 Test with curl:
 
 ```bash
@@ -468,6 +481,8 @@ nx g @frontmcp/nx:app my-app --directory apps/my-app
 nx g @frontmcp/nx:server my-server --directory servers/my-server
 ```
 
+This works in `create-nx-workspace --preset=ts` workspaces too: the generated project `tsconfig.json` compiles CommonJS JavaScript whatever the TS-solution base inherits (`composite`, `emitDeclarationOnly`, `customConditions`), resolving with `node10` on TypeScript 5 and `bundler` on TypeScript 6+, and library path aliases are written as `./libs/<name>/src/index.ts`, which needs no `baseUrl`.
+
 ### 7c. Nx project.json example
 
 If manually configuring, add a `project.json`:

package/catalog/frontmcp-setup/references/setup-redis.md

@@ -138,6 +138,15 @@ redis: {
 },
 ```
 
+From a single connection URL (what managed Redis providers hand out). It is read into `host` / `port` / `password` / `db` at parse time; `rediss://` sets `tls: true`; the user part must be empty or `default`; percent-encode reserved password characters (`@` as `%40`, `%` as `%25`), since a malformed escape is a validation error:
+
+```typescript
+redis: {
+  url: process.env['REDIS_URL'], // redis://:password@host:6379/0 (or rediss:// for TLS)
+  keyPrefix: 'mcp:', // optional, as with the other forms
+},
+```
+
 ### For Vercel KV
 
 ```typescript
@@ -313,13 +322,13 @@ You should see session keys like `mcp:session:<session-id>`.
 
 Every instance behind the load balancer needs the **same** values:
 
-- `MCP_SESSION_SECRET` -- session ids are encrypted with it. An id minted under a different secret is answered with HTTP 404 and the client re-initializes (every auth mode, including `public`, where the id is the caller's only credential). An anonymous session minted by one instance is honored by any instance with the same secret.
+- `MCP_SESSION_SECRET` -- session ids are encrypted with it. An id minted under a different secret is answered with HTTP 404 and the client re-initializes (every auth mode, including `public`, where the id is the caller's only credential). An anonymous session minted by one instance is honored by any instance with the same secret: the receiving instance recreates the transport from the stored session (in distributed mode it relays the request to the live node that owns the session, or takes the session over from a node that stopped).
 - `VAULT_SECRET` (or `JWT_SECRET`) -- signs MCP 2026-07-28 `requestState`. Without either, each instance uses a random per-process key and a multi-round tool (`elicit()` / `sample()`) whose next round lands elsewhere asks its first question again. In production, `redis` or `transport.persistence` without either secret logs a startup warning; each rejected round logs `mcp-20260728: rejected requestState` with `reason: 'bad-signature'` and a `hint` naming `VAULT_SECRET`.
 
 ### What happens when Redis is down at startup
 
 - `redis` and `transport.persistence` fall back to in-memory storage and log the failure (`[TransportService] Failed to connect to redis - session persistence disabled`); the server starts.
-- `throttle.storage` fails closed: startup aborts with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: …`), the default in production. If Redis goes away while the server runs, a rate-limited call is refused with the same error, not `Internal FrontMCP error`. Opt in to per-instance counters explicitly (they also cover a mid-run outage):
+- `throttle.storage` fails closed: startup aborts with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: …`), the default in production. If Redis goes away while the server runs, a rate-limited call is refused with the same error, not `Internal FrontMCP error` (HTTP 503 from the `global` check; an `isError` result with `_meta.code: 'GUARD_STORAGE_UNAVAILABLE'` inside `tools/call`). Opt in to per-instance counters explicitly (they also cover a mid-run outage):
 
 ```typescript
 throttle: {
@@ -332,7 +341,7 @@ throttle: {
 },
 ```
 
-`throttle.storage` takes the `@frontmcp/utils` storage shape (`{ type: 'redis', redis: { config } }` or `{ type: 'redis', redis: { url } }`), not the top-level `redis` shape.
+`throttle.storage` takes the `@frontmcp/utils` storage shape (`{ type: 'redis', redis: { config } }` or `{ type: 'redis', redis: { url } }`), not the top-level `redis` shape (which takes `{ host, ... }` or `{ url }`).
 
 ## Common Patterns
 

package/catalog/frontmcp-setup/references/setup-sqlite.md

@@ -77,6 +77,9 @@ interface SqliteOptionsInput {
 
   /** Interval in ms for purging expired keys (default: 60000) */
   ttlCleanupIntervalMs?: number;
+
+  /** Ms to wait for a lock held by another process before SQLITE_BUSY (default: 5000) */
+  busyTimeoutMs?: number;
 }
 ```
 
@@ -406,14 +409,15 @@ The change in `src/main.ts`:
 
 ## Troubleshooting
 
-| Problem                                 | Cause                                                           | Solution                                                                                                                  |
-| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
-| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
-| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`) or ensure only one process writes to the database                                       |
-| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
-| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
-| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
+| Problem                                 | Cause                                                           | Solution                                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                     |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall     |
+| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`), raise `busyTimeoutMs` (default 5000), or ensure only one process writes to the database |
+| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                              |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                      |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                  |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated  |
 
 ## Examples
 

package/catalog/frontmcp-testing/SKILL.md

@@ -146,18 +146,22 @@ This is a router skill. Follow this order to pick a testing approach, then move
 
 ## Troubleshooting
 
-| Problem                                                                           | Cause                                                                  | Solution                                                                                                                                                                                                                                                                                                                                          |
-| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Jest not finding test files                                                       | Wrong file extension (`.test.ts` instead of `.spec.ts`)                | Rename to `.spec.ts`; check `testMatch` in jest.config                                                                                                                                                                                                                                                                                            |
-| `SyntaxError: Unexpected token 'export'`                                          | An ESM-only dependency is being ignored instead of transpiled          | Add it to `test.esmPackages` in `frontmcp.config.ts`. With a hand-written `jest.config.ts`, use the pnpm-safe `transformIgnorePatterns` in [`setup-testing`](./references/setup-testing.md#jest-configuration) AND make sure `transform` matches `.js` (`^.+\.[tj]sx?$` + `allowJs`) — un-ignoring a file does nothing if no transform matches it |
-| Coverage below 95%                                                                | Untested error paths or conditional branches                           | Run `frontmcp test --coverage` and inspect uncovered lines in the report                                                                                                                                                                                                                                                                          |
-| E2E test timeout                                                                  | Server startup too slow or port conflict                               | Increase Jest timeout; use random port allocation                                                                                                                                                                                                                                                                                                 |
-| DI resolution fails in tests                                                      | Provider not registered in test scope                                  | Register mock providers before creating the test context                                                                                                                                                                                                                                                                                          |
-| Istanbul shows 0% on async methods                                                | TypeScript source-map mismatch with Istanbul                           | Known issue with some TS compilation settings; verify coverage with actual test output                                                                                                                                                                                                                                                            |
-| Specs see no `.env` values                                                        | An older CLI did not load `.env` for `frontmcp test`, only for `dev`   | Upgrade the CLI — `frontmcp test` now loads `.env` / `.env.local` with the same precedence as `dev` (real environment wins, so CI secrets still override). Pass `--no-env` for a hermetic run                                                                                                                                                     |
-| `Invalid first argument, true` at collection time                                 | `test.skip(condition, reason)` reached Jest's `skip(name, fn)`         | Upgrade the CLI — the Playwright signature is supported: `test.skip(!hasCredentials, 'credentials not set')` skips every test registered after it in the enclosing block                                                                                                                                                                          |
-| `test.use()` in one `describe` leaks into another, or two files fight over a port | Older `@frontmcp/testing` kept one global config and per-process ports | Upgrade — `test.use()` is scoped per `describe` and ports are locked across Jest workers; use `port: 0`                                                                                                                                                                                                                                           |
-| Every spec fails with `HTTP 404` after setting `http.entryPath`                   | The test client always connected to the server root                    | Upgrade the CLI — the client now follows the `entryPaths` a 404 reports, and `test.use({ entryPath: '/mcp' })` sets it explicitly                                                                                                                                                                                                                 |
+| Problem                                                                           | Cause                                                                                 | Solution                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Jest not finding test files                                                       | Wrong file extension (`.test.ts` instead of `.spec.ts`)                               | Rename to `.spec.ts`; check `testMatch` in jest.config                                                                                                                                                                                                                                                                                            |
+| `SyntaxError: Unexpected token 'export'`                                          | An ESM-only dependency is being ignored instead of transpiled                         | Add it to `test.esmPackages` in `frontmcp.config.ts`. With a hand-written `jest.config.ts`, use the pnpm-safe `transformIgnorePatterns` in [`setup-testing`](./references/setup-testing.md#jest-configuration) AND make sure `transform` matches `.js` (`^.+\.[tj]sx?$` + `allowJs`) — un-ignoring a file does nothing if no transform matches it |
+| Coverage below 95%                                                                | Untested error paths or conditional branches                                          | Run `frontmcp test --coverage` and inspect uncovered lines in the report                                                                                                                                                                                                                                                                          |
+| E2E test timeout                                                                  | Server startup too slow or port conflict                                              | Increase Jest timeout; use random port allocation                                                                                                                                                                                                                                                                                                 |
+| DI resolution fails in tests                                                      | Provider not registered in test scope                                                 | Register mock providers before creating the test context                                                                                                                                                                                                                                                                                          |
+| Istanbul shows 0% on async methods                                                | TypeScript source-map mismatch with Istanbul                                          | Known issue with some TS compilation settings; verify coverage with actual test output                                                                                                                                                                                                                                                            |
+| Specs see no `.env` values                                                        | An older CLI did not load `.env` for `frontmcp test`, only for `dev`                  | Upgrade the CLI — `frontmcp test` now loads `.env` / `.env.local` with the same precedence as `dev` (real environment wins, so CI secrets still override). Pass `--no-env` for a hermetic run                                                                                                                                                     |
+| `Invalid first argument, true` at collection time                                 | `test.skip(condition, reason)` reached Jest's `skip(name, fn)`                        | Upgrade the CLI — the Playwright signature is supported: `test.skip(!hasCredentials, 'credentials not set')` skips every test registered after it in the enclosing block                                                                                                                                                                          |
+| `test.use()` in one `describe` leaks into another, or two files fight over a port | Older `@frontmcp/testing` kept one global config and per-process ports                | Upgrade — `test.use()` is scoped per `describe` and ports are locked across Jest workers; use `port: 0`                                                                                                                                                                                                                                           |
+| Every spec fails with `HTTP 404` after setting `http.entryPath`                   | The test client always connected to the server root                                   | Upgrade the CLI — the client now follows the `entryPaths` a 404 reports, and `test.use({ entryPath: '/mcp' })` sets it explicitly                                                                                                                                                                                                                 |
+| `test.beforeEach(async ({ mcp }) => …)` times out waiting for `done`              | Older `@frontmcp/testing` handed the hook to Jest, which read the parameter as `done` | Upgrade — hooks that take a parameter now receive the test's fixtures (same `mcp` as the test); `beforeAll` / `afterAll` never get fixtures                                                                                                                                                                                                       |
+| `test.use({ transport: 'sse' })` throws "SSE transport not yet implemented"       | Older `@frontmcp/testing` had no legacy SSE client                                    | Upgrade — `'sse'` is the legacy HTTP+SSE transport; the server must enable it with `transport: { protocol: { legacy: true } }`                                                                                                                                                                                                                    |
+| `Module @swc/jest in the transform option was not found` from `frontmcp test`     | Older `@frontmcp/testing` did not install the transformer the injected config uses    | Upgrade — `@frontmcp/testing` depends on `@swc/jest` / `@swc/core`, and `frontmcp test` resolves the transformer through it                                                                                                                                                                                                                       |
+| `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG` from a server started inside a spec | Older SDKs loaded the optional `vectoriadb` with `import()` at boot                   | Upgrade the SDK — `vectoriadb` loads on the first skill search, through `require` where available; no `--experimental-vm-modules` needed                                                                                                                                                                                                          |
 
 ## Examples
 

package/catalog/frontmcp-testing/references/setup-testing.md

@@ -399,6 +399,16 @@ You usually do not need to set this: when the client's first request 404s and th
 ### Scoping config, parameterised tests, ports and restarts
 
 - `test.use()` is scoped to the `describe` block it is called in. Nested blocks merge over outer ones (`env` key by key); each distinct configuration gets its own server, stopped by the block that configured it. At file level it applies to the whole file.
+- The `env` object is read when the server starts, so a `beforeAll` may fill in values known only later (e.g. the port of an upstream `TestServer` it started).
+- `test.beforeEach` / `test.afterEach` callbacks that take a parameter get the test's fixtures, Playwright-style — the **same** `mcp` / `server` / `auth` as the test. `beforeEach` runs outer blocks first, `afterEach` inner blocks first, and fixtures are torn down after the last `afterEach`. A callback without parameters is a plain Jest hook; `test.beforeAll` / `test.afterAll` never receive fixtures. Jest's `done` style is not supported on `test.beforeEach` / `test.afterEach`.
+
+```typescript
+test.beforeEach(async ({ mcp }) => {
+  await mcp.tools.call('reset_state', {});
+});
+```
+
+- `transport: 'sse'` (in `test.use()` or `server.createClient()`) uses the legacy HTTP+SSE transport: `GET <entryPath>/sse`, messages POSTed to the endpoint the server names, responses read from the stream. The server must enable it (`transport: { protocol: { legacy: true } }`); otherwise connecting fails with the HTTP status.
 - `port: 0` (or omitting `port`) picks any free port. Ports are reserved with a cross-process lock, so parallel Jest workers do not collide.
 - `auth: { mode, type }` reaches the server process as `FRONTMCP_TEST_AUTH_MODE` / `FRONTMCP_TEST_AUTH_TYPE`; `mode: 'public'` also keeps the `mcp` client anonymous.
 - `test.each` / `test.describe.each` pass the row values to the callback (fixtures first for `test.each`):
@@ -518,7 +528,10 @@ In standalone projects driven by `frontmcp test`, prefer `test.esmPackages` in
 `frontmcp.config.ts` — the injected config already carries the pattern above,
 and already transpiles `jose`, `@noble/hashes` and `@noble/ciphers` (CodeCall).
 `frontmcp test` does not set `NODE_OPTIONS=--experimental-vm-modules` (it would make Jest
-load ESM natively and bypass these transforms); use Jest 30 (what `frontmcp create` scaffolds):
+load ESM natively and bypass these transforms); use Jest 30 (what `frontmcp create` scaffolds).
+A server created inside the test process (`FrontMcpInstance.createHandler()`, `createDirect()`,
+`create()`) works without the flag too. `@frontmcp/testing` brings `@swc/jest` and `@swc/core`, so a
+bare project needs only `@frontmcp/testing` and `jest` installed:
 
 ```typescript
 // frontmcp.config.ts

package/catalog/skills-manifest.json

@@ -998,7 +998,7 @@
               "features": [
                 "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely",
                 "Each request is standalone with no server-side state",
-                "Pair with `sessionMode: 'stateless'` for serverless execution",
+                "No `sessionMode` needed: sessions follow the protocol preset",
                 "Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed"
               ]
             }
@@ -1040,7 +1040,7 @@
               "level": "basic",
               "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
               "features": [
-                "Using `sessionMode: 'stateless'` to disable session management",
+                "Serving without sessions: whether the server keeps sessions follows `transport.protocol` (`sessionMode` has no effect)",
                 "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response",
                 "Each request is standalone with no server-side state between invocations",
                 "Required for serverless targets (Vercel, Lambda, Cloudflare Workers)"
@@ -1619,13 +1619,15 @@
             },
             {
               "name": "nested-agents-with-swarm",
-              "description": "Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table.",
+              "description": "Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table.",
               "level": "advanced",
               "tags": ["development", "agent", "nested", "agents", "swarm"],
               "features": [
-                "Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers appear as `use-agent:*` tools",
+                "Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers are offered to its model as `invoke_*` tools",
                 "Setting `swarm: { isVisible: true }` (the default) on specialist peers so they can be called",
-                "Routing is driven by the orchestrator LLM choosing among `use-agent:<peer>` tools, not by a declarative handoff table",
+                "Routing is driven by the orchestrator LLM choosing among `invoke_<peer>` tools, not by a declarative handoff table",
+                "A nested sub-agent (`agents: [...]`) private to the orchestrator, called from code with `this.invokeAgent()`",
+                "`swarm.maxCallDepth` bounding how deep agents may call each other",
                 "Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization"
               ]
             }
@@ -2061,7 +2063,7 @@
         },
         {
           "name": "official-plugins",
-          "description": "Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring",
+          "description": "Guide to the 7 official plugins for discovery, memory, auth, caching, flags, monitoring, and WebMCP",
           "examples": [
             {
               "name": "cache-and-feature-flags",
@@ -2173,7 +2175,7 @@
                 "Secure defaults: external `$ref` resolution off, spec-URL redirects not followed, internal/private targets blocked (DNS-resolved) \u2014 on `mcp-from-openapi` >= 2.5.0",
                 "Opting back into external refs with `allowedProtocols`, and restricting the spec URL + `$ref`s with `allowedHosts`",
                 "Using `allowInternalIPs` for trusted internal/local targets (governs the spec URL and `$ref`s)",
-                "Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`",
+                "Filtering operations with `readOnlyOnly`, `includeTags`, `includePaths`, `excludeMethods`, `includeOperations`, `excludeOperations`, and `filterFn`",
                 "Combining security hardening with operation filtering for a production-ready setup"
               ]
             }
@@ -2474,7 +2476,7 @@
         },
         {
           "name": "distributed-ha",
-          "description": "Deploy FrontMCP across multiple pods with heartbeat, session takeover, and notification relay for zero-downtime failover",
+          "description": "Deploy FrontMCP across multiple pods with heartbeat, cross-pod request relay, session takeover, and notification relay for zero-downtime failover",
           "examples": [
             {
               "name": "ha-kubernetes-3-replicas",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/skills",
-  "version": "1.8.7",
+  "version": "1.9.0",
   "description": "Curated skills catalog for FrontMCP projects",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",