@frontmcp/skills 1.7.2 → 1.8.1

package/catalog/frontmcp-observability/references/structured-logging.md

@@ -99,6 +99,41 @@ logging: {
 
 Redaction is recursive (handles nested objects) and case-insensitive.
 
+## CodeCall Audit Events
+
+If `CodeCallPlugin` is installed, it emits a structured audit event at every meaningful point in a
+script execution. The plugin registers the bridge itself, so the events reach your normal log
+output at `info` under the `codecall:audit` prefix with no wiring.
+
+Event families, all carrying `executionId` for correlation:
+
+- `codecall:execution:start` / `:success` / `:failure` / `:timeout`
+- `codecall:tool:call:start` / `:success` / `:failure`
+- `codecall:security:self-reference` / `:access-denied` / `:ast-blocked`
+- `codecall:search:performed` / `codecall:describe:performed` / `codecall:invoke:performed`
+
+No event carries script source, tool arguments, tool results, or query text — a script is reduced
+to `scriptHash` + `scriptLength`, a query to `queryLength`. Do not add those fields when building
+on this; the omission is what makes the events safe to emit at `info`.
+
+To route events elsewhere, subscribe rather than parsing logs:
+
+```typescript
+import { AUDIT_EVENT_TYPES, AuditLoggerService, type AuditEvent } from '@frontmcp/plugin-codecall';
+
+const audit = scope.providers.get(AuditLoggerService);
+const unsubscribe = audit.subscribe((event: AuditEvent) => myShipper.send(event));
+```
+
+Fan-out is synchronous and on the execution hot path — hand off to a queue, never do network I/O
+inside the listener. Note the file transport writes only the message, so structured fields are
+dropped there; use the structured transport or subscribe directly.
+
+**Over stdio:** stdout carries the MCP JSON-RPC frames, so nothing else may be written there.
+`runStdio()` redirects the stdout-bound `console` methods to stderr, and the NDJSON `stdout` sink
+defaults to stderr when `FRONTMCP_STDIO` is set. Never configure a sink with an explicit
+`stream: process.stdout` on a stdio server — an explicit stream overrides the guard.
+
 ## Examples
 
 | Example                                                                        | Level        | Description                                                                                                                    |

package/catalog/frontmcp-setup/SKILL.md

@@ -118,13 +118,14 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Troubleshooting
 
-| Problem                  | Cause                            | Solution                                                              |
-| ------------------------ | -------------------------------- | --------------------------------------------------------------------- |
-| `frontmcp create` fails  | Missing Node.js 24+ or npm/yarn  | Install Node.js 24+ and ensure npm/yarn is available                  |
-| Server fails to start    | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts`                       |
-| Redis connection refused | Redis not running or wrong URL   | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var    |
-| Nx generator not found   | `@frontmcp/nx` not installed     | Run `npm install -D @frontmcp/nx`                                     |
-| Skills not loading       | Skills placed in wrong directory | Catalog skills go in top-level `skills/`, app skills in `src/skills/` |
+| Problem                                                                   | Cause                                                                   | Solution                                                                                                                                                 |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `frontmcp create` fails                                                   | Missing Node.js 24+ or npm/yarn                                         | Install Node.js 24+ and ensure npm/yarn is available                                                                                                     |
+| Server fails to start                                                     | `main.ts` missing default export                                        | Add `export default MyServerClass` to `main.ts`                                                                                                          |
+| Redis connection refused                                                  | Redis not running or wrong URL                                          | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var                                                                                       |
+| Nx generator not found                                                    | `@frontmcp/nx` not installed                                            | Run `npm install -D @frontmcp/nx`                                                                                                                        |
+| Skills not loading                                                        | Skills placed in wrong directory                                        | Catalog skills go in top-level `skills/`, app skills in `src/skills/`                                                                                    |
+| Build or start fails under Yarn 4 with peer-dependency or `TS2688` errors | Yarn defaults to Plug'n'Play, which enforces peer dependencies strictly | `frontmcp create --pm yarn` scaffolds `.yarnrc.yml` with `nodeLinker: node-modules`; add that file and reinstall for projects scaffolded by an older CLI |
 
 ## Examples
 

package/catalog/frontmcp-testing/SKILL.md

@@ -99,6 +99,7 @@ This is a router skill. Follow this order to pick a testing approach, then move
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Environment        | `frontmcp test` loads `.env` / `.env.local` into the Jest child, same precedence as `dev` (real environment wins over the files, config `env.shared` + `env.test` underneath). `--no-env` skips it                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config; discovers `src/**/*.spec.ts(x)`, `__tests__/**/*.spec.ts(x)`, and `e2e/**/*.e2e.spec.ts(x)`; transforms both `.ts` and `.tsx` with the automatic JSX runtime; transpiles ESM-only deps such as `jose` under npm, yarn AND pnpm's `node_modules/.pnpm/` store — add your own via `test.esmPackages` in `frontmcp.config.ts`; delegates to a user-provided `jest.config.{ts,js,mjs,cjs,json}` if present, which drops the injected ESM transforms). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly |
 | Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -145,14 +146,17 @@ 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                                                                                                                                                                                                                                                            |
+| 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                                                                                                                                                                          |
+| 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                                                                                                                                                                                                                 |
 
 ## Examples
 

package/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md

@@ -8,6 +8,7 @@ features:
   - 'Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`'
   - 'Asserting text content with the `toHaveTextContent()` matcher'
   - 'Asserting error results with `toBeError()` for invalid input and unknown tools'
+  - 'Matching the tool error code: invalid input is an `isError` result with `_meta.code: "INVALID_INPUT"`, so `toBeError(''INVALID_INPUT'')` matches it (a numeric code matches JSON-RPC errors only)'
   - 'Testing edge cases like zero values'
 ---
 
@@ -53,7 +54,7 @@ describe('Tool Call E2E', () => {
 
   it('returns an error for invalid input', async () => {
     const result = await client.tools.call('add_numbers', { a: 'bad' });
-    expect(result).toBeError();
+    expect(result).toBeError('INVALID_INPUT');
   });
 
   it('returns an error for a nonexistent tool', async () => {
@@ -74,6 +75,7 @@ describe('Tool Call E2E', () => {
 - Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`
 - Asserting text content with the `toHaveTextContent()` matcher
 - Asserting error results with `toBeError()` for invalid input and unknown tools
+- Matching the tool error code: invalid input is an `isError` result with `_meta.code: "INVALID_INPUT"`, so `toBeError('INVALID_INPUT')` matches it (a numeric code matches JSON-RPC errors only)
 - Testing edge cases like zero values
 
 ## Related

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

@@ -380,6 +380,39 @@ test('unauthenticated call is rejected', async ({ mcp }) => {
 });
 ```
 
+### Servers that serve MCP somewhere other than `/`
+
+A server configured with `http: { entryPath: '/mcp' }` serves MCP at `/mcp`, and the test client follows it:
+
+```typescript
+test.use({
+  server: './src/main.ts',
+  entryPath: '/mcp',
+});
+```
+
+You usually do not need to set this: when the client's first request 404s and the server reports where it does serve MCP (`{"error":"Not Found","entryPaths":["/mcp"]}`), the client reconnects there on its own, and a failure names the reported paths instead of a bare `HTTP 404`. `entryPath` applies to the MCP endpoint only — OAuth and discovery endpoints stay at the server root.
+
+`baseUrl` may also be supplied alongside `server` to override the booted server's own URL (for a proxy, or a different host than it binds).
+
+### Gating a block on credentials
+
+`test.skip(condition, reason)` is the Playwright signature and skips every test registered after it in the enclosing block:
+
+```typescript
+const hasCredentials = Boolean(process.env.TWILIO_ACCOUNT_SID);
+
+test.describe('against the live API', () => {
+  test.skip(!hasCredentials, 'credentials not set');
+
+  test('looks up a carrier', async ({ mcp }) => {
+    // ...
+  });
+});
+```
+
+A nested `test.describe` inherits an outer skip. The `(name, fn)` form still skips a single named test. `frontmcp test` loads `.env` / `.env.local`, so a credential in `.env` reaches the condition above.
+
 ## Custom MCP Matchers
 
 `@frontmcp/testing` provides Jest matchers tailored for MCP responses. Import `expect` from `@frontmcp/testing` instead of from Jest:
@@ -388,15 +421,15 @@ test('unauthenticated call is rejected', async ({ mcp }) => {
 import { expect } from '@frontmcp/testing';
 ```
 
-| Matcher                   | Asserts                                               |
-| ------------------------- | ----------------------------------------------------- |
-| `toContainTool(name)`     | Tools list includes a tool with the given name        |
-| `toContainResource(uri)`  | Resources list includes a resource with the given URI |
-| `toContainPrompt(name)`   | Prompts list includes a prompt with the given name    |
-| `toBeSuccessful()`        | Tool call result is not an error                      |
-| `toBeError()`             | Tool call result is an MCP error                      |
-| `toHaveTextContent(text)` | Result contains text content matching the string      |
-| `toHaveMimeType(mime)`    | Resource content has the expected MIME type           |
+| Matcher                   | Asserts                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `toContainTool(name)`     | Tools list includes a tool with the given name                                                                     |
+| `toContainResource(uri)`  | Resources list includes a resource with the given URI                                                              |
+| `toContainPrompt(name)`   | Prompts list includes a prompt with the given name                                                                 |
+| `toBeSuccessful()`        | Tool call result is not an error                                                                                   |
+| `toBeError(code?)`        | Result is an error; a string code matches `_meta.code` (`'INVALID_INPUT'`), a number matches a JSON-RPC error code |
+| `toHaveTextContent(text)` | Result contains text content matching the string                                                                   |
+| `toHaveMimeType(mime)`    | Resource content has the expected MIME type                                                                        |
 
 ## Running Tests with Nx
 

package/catalog/frontmcp-testing/references/test-e2e-handler.md

@@ -67,6 +67,41 @@ describe('Server E2E', () => {
 });
 ```
 
+## Error Codes
+
+Errors raised while a tool runs, including invalid input, come back as a tool result with `isError: true` and a string `_meta.code`, not as a JSON-RPC error. Match them with the string form, and keep the numeric form for JSON-RPC errors:
+
+```typescript
+expect(await client.tools.call('add_numbers', { a: 5 })).toBeError('INVALID_INPUT');
+expect(await client.tools.call('nonexistent_tool', {})).toBeError('TOOL_NOT_FOUND');
+expect(await client.prompts.get('nonexistent_prompt')).toBeError(-32602);
+```
+
+A tool without an `outputSchema` that returns a plain number sends `{ value: 8 }`, so assert `expect(result.json()).toEqual({ value: 8 })`.
+
+## Notifications and Progress
+
+After `initialize`, `McpTestClient` opens the session's notification stream (a `GET` on the MCP endpoint) and records what the server sends there and on each request's own response:
+
+```typescript
+it('records progress and log messages', async () => {
+  const progress = client.notifications.collectProgress(); // tools.call now sends a _meta.progressToken
+  const notifications = client.notifications.collect();
+  await client.raw.request({ jsonrpc: '2.0', id: 1, method: 'logging/setLevel', params: { level: 'info' } });
+
+  await client.tools.call('import_files', {});
+
+  await progress.waitForComplete(5000);
+  expect(progress.all.length).toBeGreaterThan(0);
+  await notifications.waitFor('notifications/message', 5000);
+});
+```
+
+- Pass `{ progressToken }` as the third argument of `tools.call()` to choose the token yourself.
+- The server sends `notifications/message` (from `this.notify()`) only after `logging/setLevel`.
+- Session-stream notifications can arrive after the call's result, so wait with `waitFor()` / `waitForComplete()` before asserting.
+- `McpTestClient` speaks `2025-06-18` by default. `2026-07-28` has no `initialize` handshake, so `withProtocolVersion('2026-07-28')` makes `build()` throw.
+
 ## Examples
 
 | Example                                                                                        | Level        | Description                                                                                                          |

package/catalog/skills-manifest.json

@@ -365,7 +365,7 @@
           "features": [
             "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)",
             "Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs",
-            "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)",
+            "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `<`, `>` and `&`)",
             "Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback"
           ]
         },
@@ -1069,7 +1069,7 @@
                 "Top-level `instructions` on `@FrontMcp` exposes a global system prompt to MCP clients",
                 "`skillsConfig.injectInstructions: 'append'` adds the skill catalog summary after the user prompt",
                 "Dynamic skills are picked up because the composer runs on every initialize request",
-                "Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://catalog"
+                "Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://index.json"
               ]
             },
             {
@@ -1276,7 +1276,7 @@
               "tags": ["deployment", "json-rpc", "cloudflare", "worker", "custom", "domain"],
               "features": [
                 "Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts",
-                "Adding a custom domain with `wrangler domains add` for production-ready URLs",
+                "Adding a custom domain with `wrangler deploy --domain` for production-ready URLs",
                 "End-to-end verification of both the health check and MCP JSON-RPC endpoint"
               ]
             },
@@ -3449,6 +3449,7 @@
                 "Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`",
                 "Asserting text content with the `toHaveTextContent()` matcher",
                 "Asserting error results with `toBeError()` for invalid input and unknown tools",
+                "Matching the tool error code: invalid input is an `isError` result with `_meta.code: \"INVALID_INPUT\"`, so `toBeError('INVALID_INPUT')` matches it (a numeric code matches JSON-RPC errors only)",
                 "Testing edge cases like zero values"
               ]
             }

package/package.json

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