@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,115 @@
+---
+name: unit-test-tool-resource-prompt
+reference: setup-testing
+level: intermediate
+description: 'Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.'
+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 prompt `execute()` output matches the MCP `GetPromptResult` shape'
+  - 'Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions'
+---
+
+# Unit Testing Tools, Resources, and Prompts
+
+Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.
+
+## Code
+
+```typescript
+// src/tools/__tests__/my-tool.spec.ts
+import { MyTool } from '../my-tool';
+
+describe('MyTool', () => {
+  let tool: MyTool;
+
+  beforeEach(() => {
+    tool = new MyTool();
+  });
+
+  it('should return formatted result for valid input', async () => {
+    const mockContext = {
+      scope: {
+        get: jest.fn(),
+        tryGet: jest.fn(),
+      },
+      fail: jest.fn(),
+      mark: jest.fn(),
+      fetch: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    const result = await tool.execute({ query: 'test input' });
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: expect.stringContaining('test input') }],
+    });
+  });
+
+  it('should throw for invalid input', async () => {
+    const mockContext = {
+      scope: { get: jest.fn(), tryGet: jest.fn() },
+      fail: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    await expect(tool.execute({ query: '' })).rejects.toThrow();
+  });
+});
+```
+
+```typescript
+// src/resources/__tests__/my-resource.spec.ts
+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' });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: expect.stringMatching(/^resource:\/\//),
+          mimeType: 'application/json',
+          text: expect.any(String),
+        },
+      ],
+    });
+  });
+});
+```
+
+```typescript
+// src/prompts/__tests__/my-prompt.spec.ts
+import { MyPrompt } from '../my-prompt';
+
+describe('MyPrompt', () => {
+  it('should return a valid GetPromptResult', async () => {
+    const prompt = new MyPrompt();
+    const result = await prompt.execute({ topic: 'testing' });
+
+    expect(result).toEqual({
+      messages: expect.arrayContaining([
+        expect.objectContaining({
+          role: 'user',
+          content: expect.objectContaining({ type: 'text' }),
+        }),
+      ]),
+    });
+  });
+});
+```
+
+## 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 prompt `execute()` output matches the MCP `GetPromptResult` shape
+- Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
+- See `test-tool-unit` for detailed tool unit testing patterns

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

@@ -0,0 +1,78 @@
+---
+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]
+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`'
+---
+
+# Testing OAuth Authorization Code Flow
+
+Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.
+
+## Code
+
+```typescript
+// src/__tests__/oauth-flow.e2e.spec.ts
+import { MockOAuthServer } from '@frontmcp/testing';
+
+describe('OAuth Flow', () => {
+  let mockOAuth: MockOAuthServer;
+
+  beforeAll(async () => {
+    mockOAuth = await MockOAuthServer.create({
+      issuer: 'https://test-idp.example.com',
+      port: 9999,
+    });
+  });
+
+  afterAll(async () => {
+    await mockOAuth.close();
+  });
+
+  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('should support multiple concurrent flows', async () => {
+    const flow1 = await mockOAuth.startFlow({
+      clientId: 'client-a',
+      redirectUri: 'http://localhost:3001/callback',
+      scopes: ['openid'],
+    });
+
+    const flow2 = await mockOAuth.startFlow({
+      clientId: 'client-b',
+      redirectUri: 'http://localhost:3002/callback',
+      scopes: ['openid', 'email'],
+    });
+
+    expect(flow1.authorizationUrl).toContain('code=');
+    expect(flow2.authorizationUrl).toContain('code=');
+    expect(flow1.authorizationUrl).not.toBe(flow2.authorizationUrl);
+  });
+});
+```
+
+## 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`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

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

@@ -0,0 +1,88 @@
+---
+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]
+features:
+  - 'Creating tokens with different `roles` arrays to simulate admin and user access'
+  - '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'
+---
+
+# Testing Role-Based Access Control
+
+Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.
+
+## Code
+
+```typescript
+// src/__tests__/rbac.e2e.spec.ts
+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);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  it('should allow admin access to admin-only tool', async () => {
+    const adminToken = await tokenFactory.createToken({
+      sub: 'admin-1',
+      roles: ['admin'],
+    });
+
+    const client = await server.connect({ authToken: adminToken });
+    const result = await client.callTool('admin_only_tool', {});
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+
+  it('should deny user access to admin-only tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-1',
+      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();
+  });
+
+  it('should allow user access to user-level tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-2',
+      roles: ['user'],
+    });
+
+    const client = await server.connect({ authToken: userToken });
+    const result = await client.callTool('user_tool', { data: 'hello' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating tokens with different `roles` arrays to simulate admin and user access
+- 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
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

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

@@ -0,0 +1,71 @@
+---
+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]
+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`'
+---
+
+# Testing Authentication with TestTokenFactory
+
+Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.
+
+## Code
+
+```typescript
+// src/__tests__/auth.e2e.spec.ts
+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);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  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('should accept valid token', async () => {
+    const token = await tokenFactory.createToken({
+      sub: 'user-123',
+      scopes: ['read', 'write'],
+    });
+
+    const client = await server.connect({ authToken: token });
+    const result = await client.callTool('protected_tool', { data: 'test' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## 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`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

package/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md

@@ -0,0 +1,58 @@
+---
+name: browser-bundle-validation
+reference: test-browser-build
+level: basic
+description: 'Verify that the browser build produces a valid bundle without Node.js-only module references.'
+tags: [testing, browser, node, bundle, validation]
+features:
+  - 'Checking that the browser build output directory contains `.js` files'
+  - 'Scanning the bundle for Node.js-only `require()` calls that would break in browsers'
+  - 'Using dynamic `import()` to verify the bundle is loadable'
+  - 'Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output'
+---
+
+# Validating Browser Build Output
+
+Verify that the browser build produces a valid bundle without Node.js-only module references.
+
+## Code
+
+```typescript
+// src/__tests__/browser-build.spec.ts
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DIST_DIR = path.resolve(__dirname, '../dist/browser');
+
+describe('Browser Build', () => {
+  it('should produce browser-compatible bundle', () => {
+    const files = fs.readdirSync(DIST_DIR);
+    expect(files.some((f) => f.endsWith('.js'))).toBe(true);
+  });
+
+  it('should not contain Node.js-only modules', () => {
+    const bundle = fs.readFileSync(path.join(DIST_DIR, 'index.js'), 'utf-8');
+    // These should be polyfilled or excluded
+    expect(bundle).not.toContain("require('fs')");
+    expect(bundle).not.toContain("require('child_process')");
+    expect(bundle).not.toContain("require('net')");
+    expect(bundle).not.toContain("require('cluster')");
+  });
+
+  it('should export expected functions', async () => {
+    const mod = await import(path.join(DIST_DIR, 'index.js'));
+    expect(mod).toBeDefined();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Checking that the browser build output directory contains `.js` files
+- Scanning the bundle for Node.js-only `require()` calls that would break in browsers
+- Using dynamic `import()` to verify the bundle is loadable
+- Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference

package/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md

@@ -0,0 +1,69 @@
+---
+name: playwright-browser-test
+reference: test-browser-build
+level: advanced
+description: 'Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.'
+tags: [testing, browser, playwright, e2e]
+features:
+  - "Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing"
+  - 'Waiting for DOM elements with `waitForSelector` before asserting tool list counts'
+  - 'Filling form inputs and clicking buttons to simulate tool calls in the browser'
+  - 'Asserting tool results via `textContent` on result elements'
+  - 'Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions'
+---
+
+# Testing Browser MCP Client with Playwright
+
+Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.
+
+## Code
+
+```typescript
+// src/__tests__/browser-client.pw.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('browser MCP client loads tools', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  // Wait for tools to load from MCP server
+  await page.waitForSelector('[data-testid="tool-list"]');
+
+  const tools = await page.locator('[data-testid="tool-item"]').count();
+  expect(tools).toBeGreaterThan(0);
+});
+
+test('browser client can call a tool', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', '5');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const result = await page.textContent('[data-testid="result"]');
+  expect(result).toContain('8');
+});
+
+test('browser client shows error for invalid input', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', 'abc');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const error = await page.textContent('[data-testid="error-message"]');
+  expect(error).toBeTruthy();
+});
+```
+
+## What This Demonstrates
+
+- Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing
+- Waiting for DOM elements with `waitForSelector` before asserting tool list counts
+- Filling form inputs and clicking buttons to simulate tool calls in the browser
+- Asserting tool results via `textContent` on result elements
+- Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference
+- See `test-e2e-handler` for server-side E2E testing patterns

package/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md

@@ -0,0 +1,77 @@
+---
+name: binary-startup-test
+reference: test-cli-binary
+level: basic
+description: 'Verify that a compiled CLI binary starts correctly and responds to health checks.'
+tags: [testing, cli, binary, startup]
+features:
+  - 'Using `execSync` to test that `--help` flag exits with code 0 and prints usage info'
+  - 'Spawning the binary as a child process with `PORT=0` for dynamic port assignment'
+  - 'Waiting for the "listening" log message before sending requests'
+  - 'Testing the `/health` endpoint for server readiness'
+  - 'Cleaning up the child process with `child.kill()`'
+---
+
+# Testing CLI Binary Startup and Health Check
+
+Verify that a compiled CLI binary starts correctly and responds to health checks.
+
+## Code
+
+```typescript
+// src/__tests__/cli-binary.spec.ts
+import { spawn, execSync } from 'child_process';
+import * as path from 'path';
+
+const BINARY = path.resolve(__dirname, '../dist/my-server');
+
+describe('CLI Binary', () => {
+  it('should exit with code 0 on --help', () => {
+    const output = execSync(`${BINARY} --help`, { encoding: 'utf-8' });
+    expect(output).toContain('Usage');
+  });
+
+  it('should start and respond to health check', async () => {
+    const child = spawn(BINARY, [], {
+      env: { ...process.env, PORT: '0' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Wait for server to start and parse the actual port from stdout
+    const port = await new Promise<string>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('Server did not start within 10s')), 10_000);
+      child.stdout.on('data', (data: Buffer) => {
+        const match = data.toString().match(/listening.*?:(\d+)/i);
+        if (match) {
+          clearTimeout(timeout);
+          resolve(match[1]);
+        }
+      });
+      child.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    try {
+      // Test health endpoint on the dynamically assigned port
+      const res = await fetch(`http://localhost:${port}/health`);
+      expect(res.ok).toBe(true);
+    } finally {
+      child.kill();
+    }
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `execSync` to test that `--help` flag exits with code 0 and prints usage info
+- Spawning the binary as a child process with `PORT=0` for dynamic port assignment
+- Waiting for the "listening" log message before sending requests
+- Testing the `/health` endpoint for server readiness
+- Cleaning up the child process with `child.kill()`
+
+## Related
+
+- See `test-cli-binary` for the full CLI binary testing reference

package/catalog/frontmcp-testing/examples/test-cli-binary/js-bundle-import-test.md

@@ -0,0 +1,56 @@
+---
+name: js-bundle-import-test
+reference: test-cli-binary
+level: intermediate
+description: 'Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.'
+tags: [testing, cli, binary, js, bundle, import]
+features:
+  - 'Using dynamic `import()` to test that the built JS bundle is importable'
+  - 'Verifying the bundle has a default export (server class or factory)'
+  - 'Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments'
+  - 'Pointing to the `dist/` output directory where `frontmcp build` places artifacts'
+---
+
+# Testing JS Bundle Importability
+
+Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.
+
+## Code
+
+```typescript
+// src/__tests__/js-bundle.spec.ts
+import * as path from 'path';
+
+const DIST_DIR = path.resolve(__dirname, '../dist');
+
+describe('JS Bundle', () => {
+  it('should be importable as a CJS module', async () => {
+    const mod = await import(path.join(DIST_DIR, 'my-server.cjs.js'));
+    expect(mod).toBeDefined();
+  });
+
+  it('should export a default server module', async () => {
+    const mod = await import(path.join(DIST_DIR, 'my-server.cjs.js'));
+    // The default export should be the server class or factory
+    expect(mod.default || mod).toBeDefined();
+  });
+
+  it('should not throw on require', () => {
+    expect(() => {
+      require(path.join(DIST_DIR, 'my-server.cjs.js'));
+    }).not.toThrow();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using dynamic `import()` to test that the built JS bundle is importable
+- Verifying the bundle has a default export (server class or factory)
+- Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments
+- Pointing to the `dist/` output directory where `frontmcp build` places artifacts
+
+## Related
+
+- See `test-cli-binary` for the full CLI binary testing reference
+- See `test-browser-build` for browser-specific build testing

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

@@ -0,0 +1,74 @@
+---
+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]
+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'
+  - 'Proper cleanup with `server.dispose()` in each test'
+---
+
+# Basic In-Memory Testing with create()
+
+Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.
+
+## Code
+
+```typescript
+// src/__tests__/direct-client.spec.ts
+import { create } from '@frontmcp/sdk';
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddTool = tool({
+  name: 'add',
+  description: 'Add numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: { sum: z.number() },
+})((input) => ({ sum: input.a + input.b }));
+
+describe('Direct Client Testing', () => {
+  it('should call tools via create()', async () => {
+    const server = await create({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      cacheKey: 'test-direct',
+    });
+
+    const result = await server.callTool('add', { a: 2, b: 3 });
+    expect(result.content[0].text).toContain('5');
+
+    await server.dispose();
+  });
+
+  it('should handle multiple tool calls', async () => {
+    const server = await create({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      cacheKey: 'test-direct-multi',
+    });
+
+    const r1 = await server.callTool('add', { a: 10, b: 20 });
+    expect(r1.content[0].text).toContain('30');
+
+    const r2 = await server.callTool('add', { a: -5, b: 5 });
+    expect(r2.content[0].text).toContain('0');
+
+    await server.dispose();
+  });
+});
+```
+
+## 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
+- Proper cleanup with `server.dispose()` in each test
+
+## Related
+
+- See `test-direct-client` for the full direct client testing reference