@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-testing/references/test-auth.md

@@ -5,16 +5,26 @@ description: Test authenticated MCP servers with TestTokenFactory, MockOAuthServ
 
 # Testing with Authentication
 
+Real API references:
+
+- `TestTokenFactory.createTestToken(opts)` — `libs/testing/src/auth/token-factory.ts:97` (plus `createAdminToken`, `createUserToken`, `createAnonymousToken`, `createExpiredToken`, `createTokenWithInvalidSignature`).
+- `new MockOAuthServer(tokenFactory, options)` + `.start()` / `.stop()` — `libs/testing/src/auth/mock-oauth-server.ts:159`.
+- `TestServer.start({ command, port })` — `libs/testing/src/server/test-server.ts:101`. Get a client with `McpTestClient.create({ baseUrl }).withToken(token).buildAndConnect()`.
+- Roles, email, and other claims go inside `claims`, not as top-level fields. `CreateTokenOptions` only declares `sub`, `iss`, `aud`, `scopes`, `exp`, `claims`.
+
 ```typescript
-import { McpTestClient, TestServer, TestTokenFactory, MockOAuthServer } from '@frontmcp/testing';
-import Server from '../src/main';
+// auth.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
 
 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: 3010,
+    });
     tokenFactory = new TestTokenFactory({
       issuer: 'https://test-idp.example.com',
       audience: 'my-api',
@@ -22,82 +32,115 @@ 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 () => {
+    const client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withPublicMode() // do not request an anonymous token; send no Authorization header
+      .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();
   });
 
-  it('should enforce role-based access', async () => {
-    const adminToken = await tokenFactory.createToken({
+  it('enforces role-based access', async () => {
+    const adminToken = await tokenFactory.createTestToken({
       sub: 'admin-1',
-      roles: ['admin'],
+      claims: { roles: ['admin'] },
     });
-    const userToken = await tokenFactory.createToken({
+    const userToken = await tokenFactory.createTestToken({
       sub: 'user-1',
-      roles: ['user'],
+      claims: { roles: ['user'] },
     });
 
-    const adminClient = await server.connect({ authToken: adminToken });
-    const adminResult = await adminClient.callTool('admin_only_tool', {});
+    const adminClient = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withToken(adminToken)
+      .buildAndConnect();
+    const adminResult = await adminClient.tools.call('admin_only_tool', {});
     expect(adminResult).toBeSuccessful();
 
-    const userClient = await server.connect({ authToken: userToken });
-    const userResult = await userClient.callTool('admin_only_tool', {});
-    expect(userResult.isError).toBe(true);
+    const userClient = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .withToken(userToken)
+      .buildAndConnect();
+    const userResult = await userClient.tools.call('admin_only_tool', {});
+    expect(userResult).toBeError();
 
-    await adminClient.close();
-    await userClient.close();
+    await adminClient.disconnect();
+    await userClient.disconnect();
   });
 });
+```
+
+## Mock OAuth / OIDC server
+
+`MockOAuthServer` serves JWKS, OAuth metadata, authorization, token, and userinfo endpoints. Construct it with a `TestTokenFactory`, call `.start()` to bind a port, and configure your MCP server to point at the returned `info.issuer` / `info.jwksUrl`.
 
-describe('OAuth Flow', () => {
+```typescript
+// mock-oauth.e2e.spec.ts
+import { MockOAuthServer, TestTokenFactory } from '@frontmcp/testing';
+
+describe('Mock OAuth server', () => {
+  let tokenFactory: TestTokenFactory;
   let mockOAuth: MockOAuthServer;
 
   beforeAll(async () => {
-    mockOAuth = await MockOAuthServer.create({
-      issuer: 'https://test-idp.example.com',
-      port: 9999,
+    tokenFactory = new TestTokenFactory();
+    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 JWKS that verifies factory-issued tokens', async () => {
+    const jwks = await fetch(mockOAuth.info.jwksUrl).then((r) => r.json());
+    expect(jwks.keys.length).toBeGreaterThan(0);
+  });
+
+  it('issues tokens via the same factory', async () => {
+    const token = await tokenFactory.createTestToken({ sub: 'user-123' });
+    expect(token.split('.')).toHaveLength(3);
   });
 });
 ```
 
+To run the full authorization-code-with-PKCE flow against the mock server, drive the standard OAuth endpoints (`/oauth/authorize`, `/oauth/token`) directly with `fetch` — the mock server auto-approves when `autoApprove: true` and `testUser` are set.
+
 ## Examples
 
-| 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.            |
+| Example                                                                     | Level        | Description                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`oauth-flow-test`](../examples/test-auth/oauth-flow-test.md)               | Advanced     | 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. |
+| [`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.                                                                                                                 |
 
 > See all examples in [`examples/test-auth/`](../examples/test-auth/)

package/catalog/frontmcp-testing/references/test-browser-build.md

@@ -37,7 +37,7 @@ describe('Browser Build', () => {
 ## Testing with Playwright (.pw.spec.ts)
 
 ```typescript
-import { test, expect } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 test('browser MCP client loads tools', async ({ page }) => {
   await page.goto('http://localhost:3000');

package/catalog/frontmcp-testing/references/test-direct-client.md

@@ -5,20 +5,38 @@ description: In-memory testing with create() and connectOpenAI/connectClaude wit
 
 # Testing with Direct Client (No HTTP)
 
-Uses `connect()` or `create()` for in-memory testing without HTTP overhead.
+Use `create()` for an in-memory `DirectMcpServer` and `connectOpenAI()` / `connectClaude()` for an in-memory `DirectClient` with platform-specific tool formatting. None of these start an HTTP server — they wire client and server through an in-memory transport.
+
+Real API references:
+
+- `create(config)` — `libs/sdk/src/direct/create.ts`. Returns `DirectMcpServer` with `listTools`, `callTool`, `listResources`, `readResource`, `listPrompts`, `getPrompt`, `dispose`.
+- `connectOpenAI(config, options?)` / `connectClaude(config, options?)` — `libs/sdk/src/direct/connect.ts:159` / `:200`. Both take a `FrontMcpConfigInput` (decorated `@FrontMcp` class or config object) and return a `DirectClient`. There is no `serve` field; the in-memory transport is always used.
+- Tools are class-based using the `@Tool` decorator (`libs/sdk/src/index.ts` — there is no `tool()` factory function).
 
 ```typescript
-import { connectOpenAI, create, tool, z } from '@frontmcp/sdk';
+// direct-client.spec.ts
+import { App, connectOpenAI, create, FrontMcp, 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 };
+  }
+}
+
+@App({ name: 'test-app', tools: [AddTool] })
+class TestApp {}
+
+@FrontMcp({ info: { name: 'test', version: '1.0.0' }, apps: [TestApp] })
+class TestServerConfig {}
 
 describe('Direct Client Testing', () => {
-  it('should call tools via create()', async () => {
+  it('calls tools via create() with a flat config', async () => {
     const server = await create({
       info: { name: 'test', version: '1.0.0' },
       tools: [AddTool],
@@ -26,17 +44,14 @@ describe('Direct Client Testing', () => {
     });
 
     const result = await server.callTool('add', { a: 2, b: 3 });
-    expect(result.content[0].text).toContain('5');
+    // execute() returns { sum: 5 }; the framework wraps it as a CallToolResult.
+    expect(result.structuredContent).toEqual({ sum: 5 });
 
     await server.dispose();
   });
 
-  it('should return OpenAI-formatted tools', async () => {
-    const client = await connectOpenAI({
-      info: { name: 'test', version: '1.0.0' },
-      tools: [AddTool],
-      serve: false,
-    });
+  it('returns OpenAI-formatted tools', async () => {
+    const client = await connectOpenAI(TestServerConfig);
 
     const tools = await client.listTools();
     // OpenAI format: [{ type: 'function', function: { name, parameters } }]
@@ -46,13 +61,8 @@ describe('Direct Client Testing', () => {
     await client.close();
   });
 
-  it('should return Claude-formatted tools', async () => {
-    const { connectClaude } = await import('@frontmcp/sdk');
-    const client = await connectClaude({
-      info: { name: 'test', version: '1.0.0' },
-      tools: [AddTool],
-      serve: false,
-    });
+  it('returns Claude-formatted tools', async () => {
+    const client = await connectClaude(TestServerConfig);
 
     const tools = await client.listTools();
     // Claude format: [{ name, description, input_schema }]

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

@@ -5,50 +5,62 @@ description: Full MCP protocol E2E tests over HTTP with McpTestClient and TestSe
 
 # E2E Testing with McpTestClient (HTTP Handler)
 
-Tests the full MCP protocol over HTTP — validates tools, resources, prompts end-to-end.
+Tests the full MCP protocol over HTTP — validates tools, resources, prompts end-to-end. This is the manual alternative to the fixture API in `setup-testing` and is useful when you need fine-grained control over server lifecycle, transport, or auth.
+
+Real API references:
+
+- `TestServer.start({ command, port })` returns a `TestServer` instance with `info.baseUrl` and `stop()` — `libs/testing/src/server/test-server.ts:101`. There is no `TestServer.create(ServerClass)`.
+- Build a client with `await McpTestClient.create({ baseUrl }).withTransport('streamable-http').buildAndConnect()` — `libs/testing/src/client/mcp-test-client.builder.ts`.
+- The public client API is namespaced: `client.tools.list()`, `client.tools.call(name, args)`, `client.resources.list()`, `client.resources.read(uri)`, `client.prompts.list()`, `client.prompts.get(name, args)`, `client.disconnect()` — `libs/testing/src/client/mcp-test-client.ts:306-402`.
 
 ```typescript
+// server.e2e.spec.ts
 import { McpTestClient, TestServer } from '@frontmcp/testing';
-import Server from '../src/main';
 
 describe('Server E2E', () => {
   let client: McpTestClient;
   let server: TestServer;
 
   beforeAll(async () => {
-    server = await TestServer.create(Server);
-    client = await server.connect();
+    server = await TestServer.start({
+      command: 'npx tsx src/main.ts',
+      port: 3020,
+    });
+
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .buildAndConnect();
   });
 
   afterAll(async () => {
-    await client.close();
-    await server.dispose();
+    await client.disconnect();
+    await server.stop();
   });
 
-  it('should list all tools', async () => {
-    const { tools } = await client.listTools();
+  it('lists all tools', async () => {
+    const tools = await client.tools.list();
     expect(tools.length).toBeGreaterThan(0);
     expect(tools).toContainTool('add_numbers');
   });
 
-  it('should call a tool and get result', async () => {
-    const result = await client.callTool('add_numbers', { a: 5, b: 3 });
+  it('calls a tool and gets a successful result', async () => {
+    const result = await client.tools.call('add_numbers', { a: 5, b: 3 });
     expect(result).toBeSuccessful();
-    expect(result.content[0].text).toContain('8');
+    expect(result).toHaveTextContent('8');
   });
 
-  it('should return error for invalid input', async () => {
-    const result = await client.callTool('add_numbers', { a: 'bad' });
-    expect(result.isError).toBe(true);
+  it('returns an error for invalid input', async () => {
+    const result = await client.tools.call('add_numbers', { a: 'bad' });
+    expect(result).toBeError();
   });
 
-  it('should list resources', async () => {
-    const { resources } = await client.listResources();
-    expect(resources.length).toBeGreaterThanOrEqual(0);
+  it('lists resources', async () => {
+    const resources = await client.resources.list();
+    expect(Array.isArray(resources)).toBe(true);
   });
 
-  it('should get a prompt', async () => {
-    const result = await client.getPrompt('summarize', { topic: 'testing' });
+  it('gets a prompt', async () => {
+    const result = await client.prompts.get('summarize', { topic: 'testing' });
     expect(result.messages).toBeDefined();
     expect(result.messages.length).toBeGreaterThan(0);
   });

package/catalog/frontmcp-testing/references/test-tool-unit.md

@@ -12,16 +12,20 @@ import { AddTool } from '../tools/add.tool';
 
 describe('AddTool', () => {
   it('should add two numbers', async () => {
-    // Create mock context
+    // Mock the ExecutionContextBase API surface (`get`, `tryGet`, `scope`, `fail`,
+    // `mark`, `fetch`) plus `notify` from ToolContext. Add `notify` only when the
+    // tool actually calls `this.notify(...)`.
+    // Real API: libs/sdk/src/common/interfaces/execution-context.interface.ts
     const ctx = {
       get: jest.fn(),
       tryGet: jest.fn(),
+      scope: { get: jest.fn(), tryGet: jest.fn() },
       fail: jest.fn((err) => {
         throw err;
       }),
       mark: jest.fn(),
+      fetch: jest.fn(),
       notify: jest.fn(),
-      respondProgress: jest.fn(),
     } as unknown as ToolContext;
 
     const tool = new AddTool();