@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-testing/SKILL.md

@@ -38,22 +38,38 @@ Entry point for testing FrontMCP applications. This skill helps you navigate tes
 
 > **Decision:** Use this skill for testing strategy and routing. Use `setup-testing` for hands-on Jest configuration and test writing.
 
+## Prerequisites
+
+- A FrontMCP project with at least one component to test (see `frontmcp-development`).
+- Jest installed and configured — if not, start with `setup-testing` before opening any other testing skill.
+- The component itself implemented and exported; tests reach decorated classes through the SDK, not by importing internal builders.
+
+## Steps
+
+This is a router skill. Follow this order to pick a testing approach, then move to the target skill.
+
+1. **Pick the test layer** — unit (fastest, mock DI), integration (real DI scope), or E2E (real MCP client + server). Use the Testing Strategy table below.
+2. **Pick the component flavour** — tool / resource / prompt / agent / job — each has a distinct recipe.
+3. **Pick the runtime concern** — auth, browser/CLI build, direct vs streamable transport — and add the matching skill to your reading list.
+4. **Open the target skill** (e.g. `test-tool-unit`, `test-e2e-handler`, `test-auth`) and follow its Steps section.
+5. **Enforce coverage** — confirm the project's 95%+ thresholds are wired into Jest before merging (see `setup-testing`).
+
 ## Scenario Routing Table
 
-| Scenario                                | Skill / Section                 | Description                                                  |
-| --------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
-| Set up Jest, coverage, and test harness | `setup-testing`                 | Full Jest config, test utilities, and coverage thresholds    |
-| Write unit tests for a tool             | `setup-testing` (Unit Testing)  | Mock DI, validate input/output, test error paths             |
-| Write unit tests for a resource         | `setup-testing` (Unit Testing)  | Test URI resolution, template params, read results           |
-| Write unit tests for a prompt           | `setup-testing` (Unit Testing)  | Test argument handling, message generation                   |
-| Write E2E protocol-level tests          | `setup-testing` (E2E Testing)   | Real MCP client/server, full protocol flow                   |
-| Test authenticated endpoints            | `test-auth`                     | E2E with OAuth tokens, session validation, role-based access |
-| Test deployment builds                  | `setup-testing` + `deploy-to-*` | Smoke tests against built output                             |
-| Test browser builds                     | `test-browser-build`            | Testing browser builds                                       |
-| Test CLI binary builds                  | `test-cli-binary`               | Testing CLI binary builds                                    |
-| Test with the direct API client         | `test-direct-client`            | Testing with the direct API client                           |
-| Write E2E test handler patterns         | `test-e2e-handler`              | E2E test handler patterns                                    |
-| Unit test individual tools              | `test-tool-unit`                | Unit testing individual tools                                |
+| Scenario                                | Skill / Section                 | Description                                                                                          |
+| --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Set up Jest, coverage, and test harness | `setup-testing`                 | Full Jest config, test utilities, and coverage thresholds                                            |
+| Write unit tests for a tool             | `test-tool-unit`                | Mock DI, validate input/output, test error paths                                                     |
+| Write unit tests for a resource         | `setup-testing` (Unit Testing)  | Test URI resolution, template params, read results                                                   |
+| Write unit tests for a prompt           | `setup-testing` (Unit Testing)  | Test argument handling, message generation                                                           |
+| Write E2E protocol-level tests          | `setup-testing` (E2E Testing)   | Real MCP client/server, full protocol flow                                                           |
+| Test authenticated endpoints            | `test-auth`                     | E2E with OAuth tokens, session validation, role-based access                                         |
+| Test deployment builds                  | `setup-testing` + `deploy-to-*` | Smoke tests against built output                                                                     |
+| Test browser builds                     | `test-browser-build`            | Smoke-test a `frontmcp build --target browser` bundle (import the bundle, optional Playwright suite) |
+| Test CLI binary builds                  | `test-cli-binary`               | Spawn-and-curl smoke tests for `frontmcp build --target cli` artifacts                               |
+| Test with the direct API client         | `test-direct-client`            | In-memory testing via `create()`, `connectOpenAI()`, `connectClaude()` (no HTTP)                     |
+| Write E2E test handler patterns         | `test-e2e-handler`              | Manual `McpTestClient` + `TestServer` E2E patterns (alternative to fixture API)                      |
+| Unit test individual tools              | `test-tool-unit`                | Unit testing individual `ToolContext` subclasses with a mock context                                 |
 
 ## Testing Strategy by Component Type
 
@@ -75,7 +91,7 @@ Entry point for testing FrontMCP applications. This skill helps you navigate tes
 | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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`                                                                                                                                                            |
-| Test runner        | Use `frontmcp test` (not `jest --config ...`). It auto-generates the correct Jest/SWC config                                                                                                                                                                                                         |
+| Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config). 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                                                                                                                                                                                                                       |
 | Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                    |
@@ -129,6 +145,77 @@ Entry point for testing FrontMCP applications. This skill helps you navigate tes
 | 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 |
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `setup-testing`
+
+| Example                                                                                        | Level        | Description                                                                                                                                       |
+| ---------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`fixture-based-e2e-test`](./examples/setup-testing/fixture-based-e2e-test.md)                 | Advanced     | Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers. |
+| [`jest-config-with-coverage`](./examples/setup-testing/jest-config-with-coverage.md)           | Basic        | Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.                                           |
+| [`unit-test-tool-resource-prompt`](./examples/setup-testing/unit-test-tool-resource-prompt.md) | Intermediate | Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.                                |
+
+### `test-auth`
+
+| Example                                                                    | Level        | Description                                                                                               |
+| -------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| [`oauth-flow-test`](./examples/test-auth/oauth-flow-test.md)               | Advanced     | Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.        |
+| [`role-based-access-test`](./examples/test-auth/role-based-access-test.md) | Intermediate | Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints. |
+| [`token-factory-test`](./examples/test-auth/token-factory-test.md)         | Basic        | Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.            |
+
+### `test-browser-build`
+
+| Example                                                                                   | Level    | Description                                                                                      |
+| ----------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| [`browser-bundle-validation`](./examples/test-browser-build/browser-bundle-validation.md) | Basic    | Verify that the browser build produces a valid bundle without Node.js-only module references.    |
+| [`playwright-browser-test`](./examples/test-browser-build/playwright-browser-test.md)     | Advanced | Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server. |
+
+### `test-cli-binary`
+
+| Example                                                                        | Level        | Description                                                                                                        |
+| ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`binary-startup-test`](./examples/test-cli-binary/binary-startup-test.md)     | Basic        | Verify that a compiled CLI binary starts correctly and responds to health checks.                                  |
+| [`js-bundle-import-test`](./examples/test-cli-binary/js-bundle-import-test.md) | Intermediate | Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step. |
+
+### `test-direct-client`
+
+| Example                                                                                   | Level        | Description                                                                                                                   |
+| ----------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-create-test`](./examples/test-direct-client/basic-create-test.md)                 | Basic        | Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.                            |
+| [`openai-claude-format-test`](./examples/test-direct-client/openai-claude-format-test.md) | Intermediate | Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`. |
+
+### `test-e2e-handler`
+
+| Example                                                                                       | Level        | Description                                                                                                          |
+| --------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`basic-e2e-test`](./examples/test-e2e-handler/basic-e2e-test.md)                             | Basic        | Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.                      |
+| [`manual-client-with-transport`](./examples/test-e2e-handler/manual-client-with-transport.md) | Advanced     | Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.               |
+| [`tool-call-and-error-e2e`](./examples/test-e2e-handler/tool-call-and-error-e2e.md)           | Intermediate | Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol. |
+
+### `test-tool-unit`
+
+| Example                                                                             | Level        | Description                                                                                              |
+| ----------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
+| [`basic-tool-test`](./examples/test-tool-unit/basic-tool-test.md)                   | Basic        | Test a simple tool's `execute()` method with mock context and verify the output.                         |
+| [`schema-validation-test`](./examples/test-tool-unit/schema-validation-test.md)     | Intermediate | Validate that a tool's Zod input schema rejects invalid data before `execute()` is called.               |
+| [`tool-error-handling-test`](./examples/test-tool-unit/tool-error-handling-test.md) | Advanced     | Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes. |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-testing/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                              |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-testing`, `frontmcp skills read frontmcp-testing:references/<file>.md`, `frontmcp skills install frontmcp-testing` — no server required.                                                                                                                                                   |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-testing/SKILL.md`, `skill://frontmcp-testing/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
 ## Reference
 
 - [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)

package/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md

@@ -6,7 +6,7 @@ description: 'Write unit tests for the three core MCP primitives, verifying that
 tags: [testing, jest, unit-test, setup, unit, tool]
 features:
   - 'Testing tool `execute()` with a mock context object assigned via `Object.assign`'
-  - 'Verifying resource `read()` output matches the MCP `ReadResourceResult` shape'
+  - 'Verifying resource `execute(uri, params)` output matches the MCP `ReadResourceResult` shape'
   - 'Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape'
   - 'Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions'
 ---
@@ -66,7 +66,7 @@ import { MyResource } from '../my-resource';
 describe('MyResource', () => {
   it('should return resource contents matching ReadResourceResult', async () => {
     const resource = new MyResource();
-    const result = await resource.read({ id: '123' });
+    const result = await resource.execute('resource://item/123', { id: '123' });
 
     expect(result).toEqual({
       contents: [
@@ -105,7 +105,7 @@ describe('MyPrompt', () => {
 ## What This Demonstrates
 
 - Testing tool `execute()` with a mock context object assigned via `Object.assign`
-- Verifying resource `read()` output matches the MCP `ReadResourceResult` shape
+- Verifying resource `execute(uri, params)` output matches the MCP `ReadResourceResult` shape
 - Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape
 - Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions
 

package/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md

@@ -2,76 +2,87 @@
 name: oauth-flow-test
 reference: test-auth
 level: advanced
-description: 'Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.'
-tags: [testing, oauth, auth, flow]
+description: Use `MockOAuthServer` to simulate an OAuth/OIDC identity provider. The server publishes a JWKS endpoint backed by your `TestTokenFactory`, so any token created by that factory is valid against the mock IDP.
+tags:
+  - testing
+  - oauth
+  - auth
+  - flow
 features:
-  - 'Setting up `MockOAuthServer` with a mock issuer URL and port'
-  - 'Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes'
-  - 'Verifying the authorization URL contains an authorization code'
-  - 'Testing concurrent OAuth flows with different client configurations'
-  - 'Proper cleanup with `mockOAuth.close()` in `afterAll`'
+  - Constructing `MockOAuthServer` with a `TestTokenFactory` and starting it with `.start()`
+  - Reading server info from `mockOAuth.info.baseUrl` / `mockOAuth.info.jwksUrl` after start
+  - Issuing tokens via the same `TestTokenFactory` so the mock JWKS can verify them
+  - Cleaning up with `mockOAuth.stop()` in `afterAll`
 ---
 
-# Testing OAuth Authorization Code Flow
+# Testing with the Mock OAuth Server
 
-Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.
+Use `MockOAuthServer` to simulate an OAuth/OIDC identity provider. The server publishes a JWKS endpoint backed by your `TestTokenFactory`, so any token created by that factory is valid against the mock IDP.
 
 ## Code
 
 ```typescript
 // src/__tests__/oauth-flow.e2e.spec.ts
-import { MockOAuthServer } from '@frontmcp/testing';
+// Real API:
+//   libs/testing/src/auth/mock-oauth-server.ts:159 — `new MockOAuthServer(tokenFactory, options)` + `.start()` / `.stop()`
+//   libs/testing/src/auth/token-factory.ts:97 — `TestTokenFactory.createTestToken(opts)`
+import { MockOAuthServer, TestTokenFactory } from '@frontmcp/testing';
 
-describe('OAuth Flow', () => {
+describe('Mock OAuth Server', () => {
+  let tokenFactory: TestTokenFactory;
   let mockOAuth: MockOAuthServer;
 
   beforeAll(async () => {
-    mockOAuth = await MockOAuthServer.create({
+    tokenFactory = new TestTokenFactory({
       issuer: 'https://test-idp.example.com',
-      port: 9999,
+      audience: 'my-api',
     });
+
+    mockOAuth = new MockOAuthServer(tokenFactory, {
+      autoApprove: true,
+      testUser: { sub: 'user-123', email: 'test@example.com' },
+      clientId: 'test-client',
+      validRedirectUris: ['http://localhost:3001/callback'],
+    });
+
+    await mockOAuth.start();
   });
 
   afterAll(async () => {
-    await mockOAuth.close();
+    await mockOAuth.stop();
   });
 
-  it('should complete OAuth authorization code flow', async () => {
-    const { authorizationUrl } = await mockOAuth.startFlow({
-      clientId: 'test-client',
-      redirectUri: 'http://localhost:3001/callback',
-      scopes: ['openid', 'profile'],
-    });
-    expect(authorizationUrl).toContain('code=');
+  it('exposes a JWKS endpoint with at least one key', async () => {
+    const res = await fetch(mockOAuth.info.jwksUrl);
+    const jwks = (await res.json()) as { keys: Array<{ kid: string }> };
+
+    expect(res.status).toBe(200);
+    expect(jwks.keys.length).toBeGreaterThan(0);
   });
 
-  it('should support multiple concurrent flows', async () => {
-    const flow1 = await mockOAuth.startFlow({
-      clientId: 'client-a',
-      redirectUri: 'http://localhost:3001/callback',
-      scopes: ['openid'],
+  it('issues tokens via the same factory the mock server trusts', async () => {
+    const token = await tokenFactory.createTestToken({
+      sub: 'user-123',
+      scopes: ['openid', 'profile'],
     });
 
-    const flow2 = await mockOAuth.startFlow({
-      clientId: 'client-b',
-      redirectUri: 'http://localhost:3002/callback',
-      scopes: ['openid', 'email'],
-    });
+    expect(typeof token).toBe('string');
+    expect(token.split('.')).toHaveLength(3);
+  });
 
-    expect(flow1.authorizationUrl).toContain('code=');
-    expect(flow2.authorizationUrl).toContain('code=');
-    expect(flow1.authorizationUrl).not.toBe(flow2.authorizationUrl);
+  it('reports server info after start', () => {
+    expect(mockOAuth.info.baseUrl).toMatch(/^http:\/\/localhost:\d+$/);
+    expect(mockOAuth.info.jwksUrl).toBe(`${mockOAuth.info.baseUrl}/.well-known/jwks.json`);
   });
 });
 ```
 
 ## What This Demonstrates
 
-- Setting up `MockOAuthServer` with a mock issuer URL and port
-- Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes
-- Verifying the authorization URL contains an authorization code
-- Testing concurrent OAuth flows with different client configurations
-- Proper cleanup with `mockOAuth.close()` in `afterAll`
+- Constructing `MockOAuthServer` with a `TestTokenFactory` and starting it with `.start()`
+- Reading server info from `mockOAuth.info.baseUrl` / `mockOAuth.info.jwksUrl` after start
+- Issuing tokens via the same `TestTokenFactory` so the mock JWKS can verify them
+- Cleaning up with `mockOAuth.stop()` in `afterAll`
 
 ## Related
 

package/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md

@@ -3,12 +3,12 @@ name: role-based-access-test
 reference: test-auth
 level: intermediate
 description: 'Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.'
-tags: [testing, auth, role, based, access]
+tags: [testing, auth, role-based-access]
 features:
-  - 'Creating tokens with different `roles` arrays to simulate admin and user access'
+  - 'Putting roles inside `claims` (the `CreateTokenOptions` shape has no top-level `roles` field)'
   - 'Testing that admin-only tools accept admin tokens and reject user tokens'
   - 'Verifying that user-level tools remain accessible to users with the correct role'
-  - 'Each test creates and closes its own client for proper isolation'
+  - 'Each test creates and disconnects its own client for proper isolation'
 ---
 
 # Testing Role-Based Access Control
@@ -19,15 +19,22 @@ Verify that tools enforce role-based access by testing admin and user tokens aga
 
 ```typescript
 // src/__tests__/rbac.e2e.spec.ts
+// Real API:
+//   libs/testing/src/server/test-server.ts:101 — `TestServer.start({ command, port })`
+//   libs/testing/src/auth/token-factory.ts:97 — `TestTokenFactory.createTestToken({ sub, scopes, claims })`
+//   libs/testing/src/client/mcp-test-client.builder.ts — `McpTestClient.create(...).withToken(...).buildAndConnect()`
+//   libs/testing/src/client/mcp-test-client.ts:306 — namespaced client API: `client.tools.call(name, args)`
 import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
-import Server from '../src/main';
 
 describe('Role-Based Access', () => {
   let server: TestServer;
   let tokenFactory: TestTokenFactory;
 
   beforeAll(async () => {
-    server = await TestServer.create(Server);
+    server = await TestServer.start({
+      command: 'npx tsx src/main.ts',
+      port: 3011,
+    });
     tokenFactory = new TestTokenFactory({
       issuer: 'https://test-idp.example.com',
       audience: 'my-api',
@@ -35,53 +42,69 @@ describe('Role-Based Access', () => {
   });
 
   afterAll(async () => {
-    await server.dispose();
+    await server.stop();
   });
 
-  it('should allow admin access to admin-only tool', async () => {
-    const adminToken = await tokenFactory.createToken({
+  async function clientWithToken(token: string): Promise<McpTestClient> {
+    return McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withToken(token)
+      .buildAndConnect();
+  }
+
+  it('allows admin access to an admin-only tool', async () => {
+    const adminToken = await tokenFactory.createTestToken({
       sub: 'admin-1',
-      roles: ['admin'],
+      claims: { roles: ['admin'] },
     });
 
-    const client = await server.connect({ authToken: adminToken });
-    const result = await client.callTool('admin_only_tool', {});
-    expect(result).toBeSuccessful();
-    await client.close();
+    const client = await clientWithToken(adminToken);
+    try {
+      const result = await client.tools.call('admin_only_tool', {});
+      expect(result).toBeSuccessful();
+    } finally {
+      await client.disconnect();
+    }
   });
 
-  it('should deny user access to admin-only tool', async () => {
-    const userToken = await tokenFactory.createToken({
+  it('denies user access to an admin-only tool', async () => {
+    const userToken = await tokenFactory.createTestToken({
       sub: 'user-1',
-      roles: ['user'],
+      claims: { roles: ['user'] },
     });
 
-    const client = await server.connect({ authToken: userToken });
-    const result = await client.callTool('admin_only_tool', {});
-    expect(result.isError).toBe(true);
-    await client.close();
+    const client = await clientWithToken(userToken);
+    try {
+      const result = await client.tools.call('admin_only_tool', {});
+      expect(result).toBeError();
+    } finally {
+      await client.disconnect();
+    }
   });
 
-  it('should allow user access to user-level tool', async () => {
-    const userToken = await tokenFactory.createToken({
+  it('allows user access to a user-level tool', async () => {
+    const userToken = await tokenFactory.createTestToken({
       sub: 'user-2',
-      roles: ['user'],
+      claims: { roles: ['user'] },
     });
 
-    const client = await server.connect({ authToken: userToken });
-    const result = await client.callTool('user_tool', { data: 'hello' });
-    expect(result).toBeSuccessful();
-    await client.close();
+    const client = await clientWithToken(userToken);
+    try {
+      const result = await client.tools.call('user_tool', { data: 'hello' });
+      expect(result).toBeSuccessful();
+    } finally {
+      await client.disconnect();
+    }
   });
 });
 ```
 
 ## What This Demonstrates
 
-- Creating tokens with different `roles` arrays to simulate admin and user access
+- Putting roles inside `claims` (the `CreateTokenOptions` shape has no top-level `roles` field)
 - Testing that admin-only tools accept admin tokens and reject user tokens
 - Verifying that user-level tools remain accessible to users with the correct role
-- Each test creates and closes its own client for proper isolation
+- Each test creates and disconnects its own client for proper isolation
 
 ## Related
 

package/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md

@@ -3,12 +3,12 @@ name: token-factory-test
 reference: test-auth
 level: basic
 description: 'Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.'
-tags: [testing, auth, token, factory]
+tags: [testing, auth, token-factory]
 features:
   - 'Creating a `TestTokenFactory` with issuer and audience configuration'
-  - 'Generating test tokens with specific subjects and scopes via `createToken()`'
-  - 'Passing tokens to `server.connect({ authToken })` for authenticated client connections'
-  - 'Verifying that unauthenticated requests are rejected with `isError`'
+  - 'Generating test tokens with specific subjects and scopes via `createTestToken()`'
+  - 'Building authenticated clients with `McpTestClient.create(...).withToken(token)`'
+  - 'Using `.withPublicMode()` to suppress the anonymous token request and test unauthenticated rejection'
 ---
 
 # Testing Authentication with TestTokenFactory
@@ -19,15 +19,21 @@ Use `TestTokenFactory` to create tokens and verify authenticated and unauthentic
 
 ```typescript
 // src/__tests__/auth.e2e.spec.ts
+// Real API:
+//   libs/testing/src/server/test-server.ts:101 — `TestServer.start({ command, port })`
+//   libs/testing/src/auth/token-factory.ts:97 — `TestTokenFactory.createTestToken({ sub, scopes, claims })`
+//   libs/testing/src/client/mcp-test-client.builder.ts — `withToken`, `withPublicMode`, `buildAndConnect`
 import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
-import Server from '../src/main';
 
 describe('Authenticated Server', () => {
   let server: TestServer;
   let tokenFactory: TestTokenFactory;
 
   beforeAll(async () => {
-    server = await TestServer.create(Server);
+    server = await TestServer.start({
+      command: 'npx tsx src/main.ts',
+      port: 3012,
+    });
     tokenFactory = new TestTokenFactory({
       issuer: 'https://test-idp.example.com',
       audience: 'my-api',
@@ -35,26 +41,37 @@ describe('Authenticated Server', () => {
   });
 
   afterAll(async () => {
-    await server.dispose();
+    await server.stop();
   });
 
-  it('should reject unauthenticated requests', async () => {
-    const client = await server.connect();
-    const result = await client.callTool('protected_tool', {});
-    expect(result.isError).toBe(true);
-    await client.close();
+  it('rejects unauthenticated requests', async () => {
+    // withPublicMode() = no Authorization header, no anonymous-token request.
+    const client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withPublicMode()
+      .buildAndConnect();
+
+    const result = await client.tools.call('protected_tool', {});
+    expect(result).toBeError();
+
+    await client.disconnect();
   });
 
-  it('should accept valid token', async () => {
-    const token = await tokenFactory.createToken({
+  it('accepts a valid token', async () => {
+    const token = await tokenFactory.createTestToken({
       sub: 'user-123',
       scopes: ['read', 'write'],
     });
 
-    const client = await server.connect({ authToken: token });
-    const result = await client.callTool('protected_tool', { data: 'test' });
+    const client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withToken(token)
+      .buildAndConnect();
+
+    const result = await client.tools.call('protected_tool', { data: 'test' });
     expect(result).toBeSuccessful();
-    await client.close();
+
+    await client.disconnect();
   });
 });
 ```
@@ -62,9 +79,9 @@ describe('Authenticated Server', () => {
 ## What This Demonstrates
 
 - Creating a `TestTokenFactory` with issuer and audience configuration
-- Generating test tokens with specific subjects and scopes via `createToken()`
-- Passing tokens to `server.connect({ authToken })` for authenticated client connections
-- Verifying that unauthenticated requests are rejected with `isError`
+- Generating test tokens with specific subjects and scopes via `createTestToken()`
+- Building authenticated clients with `McpTestClient.create(...).withToken(token)`
+- Using `.withPublicMode()` to suppress the anonymous token request and test unauthenticated rejection
 
 ## Related
 

package/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md

@@ -3,11 +3,11 @@ name: basic-create-test
 reference: test-direct-client
 level: basic
 description: 'Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.'
-tags: [testing, sdk, transport, direct-client, direct, client]
+tags: [testing, sdk, direct-client]
 features:
-  - 'Using `create()` to spin up an in-memory server with no HTTP transport'
-  - 'Defining tools inline with the functional `tool()` API and Zod schemas'
-  - 'Calling tools directly via `server.callTool()` and checking text content'
+  - 'Using `create()` to spin up an in-memory `DirectMcpServer` with no HTTP transport'
+  - 'Defining tools as classes with the `@Tool` decorator and Zod schemas'
+  - 'Calling tools directly via `server.callTool()` and checking the structured output'
   - 'Proper cleanup with `server.dispose()` in each test'
 ---
 
@@ -19,17 +19,25 @@ Test tools in-memory without any HTTP overhead using the `create()` function fro
 
 ```typescript
 // src/__tests__/direct-client.spec.ts
-import { create, tool, z } from '@frontmcp/sdk';
+// Real API:
+//   libs/sdk/src/direct/create.ts — `create(config)` returns a DirectMcpServer
+//   libs/sdk/src/index.ts — exports `Tool`, `ToolContext`, `z` (no `tool()` factory)
+import { create, Tool, ToolContext, z } from '@frontmcp/sdk';
 
-const AddTool = tool({
+@Tool({
   name: 'add',
   description: 'Add numbers',
   inputSchema: { a: z.number(), b: z.number() },
   outputSchema: { sum: z.number() },
-})((input) => ({ sum: input.a + input.b }));
+})
+class AddTool extends ToolContext {
+  async execute(input: { a: number; b: number }) {
+    return { sum: input.a + input.b };
+  }
+}
 
 describe('Direct Client Testing', () => {
-  it('should call tools via create()', async () => {
+  it('calls a tool via create()', async () => {
     const server = await create({
       info: { name: 'test', version: '1.0.0' },
       tools: [AddTool],
@@ -37,12 +45,14 @@ describe('Direct Client Testing', () => {
     });
 
     const result = await server.callTool('add', { a: 2, b: 3 });
-    expect(result.content[0].text).toContain('5');
+    // The framework wraps the tool's `{ sum: 5 }` return into a CallToolResult
+    // with `structuredContent` set to the typed output.
+    expect(result.structuredContent).toEqual({ sum: 5 });
 
     await server.dispose();
   });
 
-  it('should handle multiple tool calls', async () => {
+  it('handles multiple tool calls', async () => {
     const server = await create({
       info: { name: 'test', version: '1.0.0' },
       tools: [AddTool],
@@ -50,10 +60,10 @@ describe('Direct Client Testing', () => {
     });
 
     const r1 = await server.callTool('add', { a: 10, b: 20 });
-    expect(r1.content[0].text).toContain('30');
+    expect(r1.structuredContent).toEqual({ sum: 30 });
 
     const r2 = await server.callTool('add', { a: -5, b: 5 });
-    expect(r2.content[0].text).toContain('0');
+    expect(r2.structuredContent).toEqual({ sum: 0 });
 
     await server.dispose();
   });
@@ -62,9 +72,9 @@ describe('Direct Client Testing', () => {
 
 ## What This Demonstrates
 
-- Using `create()` to spin up an in-memory server with no HTTP transport
-- Defining tools inline with the functional `tool()` API and Zod schemas
-- Calling tools directly via `server.callTool()` and checking text content
+- Using `create()` to spin up an in-memory `DirectMcpServer` with no HTTP transport
+- Defining tools as classes with the `@Tool` decorator and Zod schemas
+- Calling tools directly via `server.callTool()` and checking the structured output
 - Proper cleanup with `server.dispose()` in each test
 
 ## Related