@frontmcp/skills 1.1.2 → 1.2.0

package/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md

@@ -3,11 +3,11 @@ name: openai-claude-format-test
 reference: test-direct-client
 level: intermediate
 description: 'Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`.'
-tags: [testing, openai, anthropic, direct-client, direct, client]
+tags: [testing, openai, anthropic, direct-client]
 features:
-  - 'Using `connectOpenAI()` with `serve: false` to get an in-memory client without starting an HTTP server'
+  - 'Using `connectOpenAI(ServerConfig)` to get an in-memory `DirectClient` (no HTTP server is started)'
   - "Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`"
-  - 'Using dynamic import for `connectClaude` to test Claude tool format: `{ name, description, input_schema }`'
+  - 'Using `connectClaude(ServerConfig)` to verify Claude format: `{ name, description, input_schema }`'
   - 'Proper cleanup with `client.close()` after each test'
 ---
 
@@ -19,22 +19,33 @@ Verify that tools are returned in the correct format for OpenAI and Claude clien
 
 ```typescript
 // src/__tests__/client-formats.spec.ts
-import { connectOpenAI, tool, z } from '@frontmcp/sdk';
+// Real API:
+//   libs/sdk/src/direct/connect.ts — `connectOpenAI(config, options?)` (no `serve` field)
+//   libs/sdk/src/direct/connect.ts — `connectClaude(config, options?)`
+//   libs/sdk/src/index.ts — exports `Tool`, `ToolContext`, `App`, `FrontMcp`, `z`
+import { App, connectClaude, connectOpenAI, 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('OpenAI format', () => {
-  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 } }]
@@ -47,13 +58,8 @@ describe('OpenAI format', () => {
 });
 
 describe('Claude format', () => {
-  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 }]
@@ -67,9 +73,9 @@ describe('Claude format', () => {
 
 ## What This Demonstrates
 
-- Using `connectOpenAI()` with `serve: false` to get an in-memory client without starting an HTTP server
+- Using `connectOpenAI(ServerConfig)` to get an in-memory `DirectClient` (no HTTP server is started)
 - Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`
-- Using dynamic import for `connectClaude` to test Claude tool format: `{ name, description, input_schema }`
+- Using `connectClaude(ServerConfig)` to verify Claude format: `{ name, description, input_schema }`
 - Proper cleanup with `client.close()` after each test
 
 ## Related

package/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md

@@ -5,10 +5,10 @@ level: basic
 description: 'Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.'
 tags: [testing, e2e, handler]
 features:
-  - 'Using `TestServer.create()` to start a server from its module export'
-  - 'Connecting a client via `server.connect()` for automatic base URL wiring'
-  - 'Proper lifecycle management with `beforeAll` / `afterAll` for setup and teardown'
-  - 'Using the `toContainTool` custom matcher from `@frontmcp/testing`'
+  - 'Using `TestServer.start({ command, port })` to spawn the server as a child process'
+  - 'Building a client with `McpTestClient.create(...).withTransport(...).buildAndConnect()`'
+  - 'Calling the namespaced public API: `client.tools.list()`, `client.resources.list()`, `client.prompts.get(...)`'
+  - 'Cleaning up with `client.disconnect()` and `server.stop()`'
 ---
 
 # Basic E2E Test with McpTestClient
@@ -19,36 +19,45 @@ Set up a basic E2E test that starts a server, connects a client, and verifies to
 
 ```typescript
 // src/__tests__/server.e2e.spec.ts
+// Real API:
+//   libs/testing/src/server/test-server.ts:101 — `TestServer.start({ command, port })`
+//   libs/testing/src/client/mcp-test-client.builder.ts — `McpTestClient.create(...).buildAndConnect()`
+//   libs/testing/src/client/mcp-test-client.ts:306-402 — `client.tools.list/call`, `client.resources.list/read`, `client.prompts.list/get`, `client.disconnect`
 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: 3021,
+    });
+
+    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 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 list prompts', 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);
   });
@@ -57,10 +66,10 @@ describe('Server E2E', () => {
 
 ## What This Demonstrates
 
-- Using `TestServer.create()` to start a server from its module export
-- Connecting a client via `server.connect()` for automatic base URL wiring
-- Proper lifecycle management with `beforeAll` / `afterAll` for setup and teardown
-- Using the `toContainTool` custom matcher from `@frontmcp/testing`
+- Using `TestServer.start({ command, port })` to spawn the server as a child process
+- Building a client with `McpTestClient.create(...).withTransport(...).buildAndConnect()`
+- Calling the namespaced public API: `client.tools.list()`, `client.resources.list()`, `client.prompts.get(...)`
+- Cleaning up with `client.disconnect()` and `server.stop()`
 
 ## Related
 

package/catalog/frontmcp-testing/examples/test-e2e-handler/manual-client-with-transport.md

@@ -6,7 +6,7 @@ description: 'Use `McpTestClient.create()` with explicit transport settings for
 tags: [testing, session, transport, e2e, handler, manual]
 features:
   - 'Using `TestServer.start()` with an explicit command and port for process-based server startup'
-  - "Building a client with `McpTestClient.create().withTransport('modern').buildAndConnect()` for streamable HTTP + strict sessions"
+  - "Building a client with `McpTestClient.create().withTransport('streamable-http').buildAndConnect()`"
   - 'Using `server.info.baseUrl` to wire the client to the correct address'
   - 'Separate `disconnect()` / `stop()` calls for client and server teardown'
   - 'The `toBeError()` and `toHaveTextContent()` custom matchers'
@@ -32,7 +32,9 @@ describe('Advanced E2E with Transport Config', () => {
       port: 3004,
     });
 
-    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).withTransport('modern').buildAndConnect();
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
+      .withTransport('streamable-http')
+      .buildAndConnect();
   });
 
   afterAll(async () => {
@@ -61,7 +63,7 @@ describe('Advanced E2E with Transport Config', () => {
 ## What This Demonstrates
 
 - Using `TestServer.start()` with an explicit command and port for process-based server startup
-- Building a client with `McpTestClient.create().withTransport('modern').buildAndConnect()` for streamable HTTP + strict sessions
+- Building a client with `McpTestClient.create().withTransport('streamable-http').buildAndConnect()`
 - Using `server.info.baseUrl` to wire the client to the correct address
 - Separate `disconnect()` / `stop()` calls for client and server teardown
 - The `toBeError()` and `toHaveTextContent()` custom matchers

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

@@ -3,12 +3,12 @@ name: tool-call-and-error-e2e
 reference: test-e2e-handler
 level: intermediate
 description: 'Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol.'
-tags: [testing, e2e, handler, tool, call, error]
+tags: [testing, e2e, handler, tool-call, error]
 features:
-  - 'Calling tools via `client.callTool()` and asserting success with `toBeSuccessful()`'
-  - 'Verifying text content in tool results with `result.content[0].text`'
-  - 'Checking `result.isError` for invalid input and nonexistent tool calls'
-  - 'Testing edge cases like zero values and missing optional parameters'
+  - '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'
+  - 'Testing edge cases like zero values'
 ---
 
 # E2E Testing Tool Calls and Error Responses
@@ -19,53 +19,62 @@ Test successful tool calls and verify that invalid inputs produce proper error r
 
 ```typescript
 // src/__tests__/tool-calls.e2e.spec.ts
+// Real API:
+//   libs/testing/src/server/test-server.ts:101 — `TestServer.start({ command, port })`
+//   libs/testing/src/client/mcp-test-client.ts:306 — `client.tools.call(name, args)` (public namespaced API)
+//   libs/testing/src/assertions/* — `toBeSuccessful`, `toBeError`, `toHaveTextContent`
 import { McpTestClient, TestServer } from '@frontmcp/testing';
-import Server from '../src/main';
 
 describe('Tool Call 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: 3022,
+    });
+
+    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 call a tool and get a successful 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 isError 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 return error for nonexistent tool', async () => {
-    const result = await client.callTool('nonexistent_tool', {});
-    expect(result.isError).toBe(true);
+  it('returns an error for a nonexistent tool', async () => {
+    const result = await client.tools.call('nonexistent_tool', {});
+    expect(result).toBeError();
   });
 
-  it('should handle tool with optional parameters', async () => {
-    const result = await client.callTool('add_numbers', { a: 10, b: 0 });
+  it('handles edge case: zero values', async () => {
+    const result = await client.tools.call('add_numbers', { a: 10, b: 0 });
     expect(result).toBeSuccessful();
-    expect(result.content[0].text).toContain('10');
+    expect(result).toHaveTextContent('10');
   });
 });
 ```
 
 ## What This Demonstrates
 
-- Calling tools via `client.callTool()` and asserting success with `toBeSuccessful()`
-- Verifying text content in tool results with `result.content[0].text`
-- Checking `result.isError` for invalid input and nonexistent tool calls
-- Testing edge cases like zero values and missing optional parameters
+- 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
+- Testing edge cases like zero values
 
 ## Related
 

package/catalog/frontmcp-testing/examples/test-tool-unit/basic-tool-test.md

@@ -5,7 +5,7 @@ level: basic
 description: "Test a simple tool's `execute()` method with mock context and verify the output."
 tags: [testing, tool, unit]
 features:
-  - 'Creating a mock `ToolContext` with all required methods (`get`, `tryGet`, `fail`, `mark`, `notify`, `respondProgress`)'
+  - 'Mocking the real `ExecutionContextBase` API surface (`get`, `tryGet`, `scope`, `fail`, `mark`, `fetch`) plus `notify` from `ToolContext`'
   - 'Assigning the mock context to the tool instance via `Object.assign`'
   - 'Testing multiple input scenarios including edge cases (negatives, zero)'
 ---
@@ -18,7 +18,11 @@ Test a simple tool's `execute()` method with mock context and verify the output.
 
 ```typescript
 // src/tools/__tests__/add.tool.spec.ts
+// Real API: libs/sdk/src/common/interfaces/execution-context.interface.ts
+//   ExecutionContextBase exposes: get, tryGet, scope, fail, mark, fetch
+//   ToolContext additionally exposes: notify (use only when the tool calls this.notify(...))
 import { ToolContext } from '@frontmcp/sdk';
+
 import { AddTool } from '../add.tool';
 
 describe('AddTool', () => {
@@ -30,12 +34,13 @@ describe('AddTool', () => {
     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;
 
     Object.assign(tool, ctx);
@@ -60,7 +65,7 @@ describe('AddTool', () => {
 
 ## What This Demonstrates
 
-- Creating a mock `ToolContext` with all required methods (`get`, `tryGet`, `fail`, `mark`, `notify`, `respondProgress`)
+- Mocking the real `ExecutionContextBase` API surface (`get`, `tryGet`, `scope`, `fail`, `mark`, `fetch`) plus `notify` from `ToolContext`
 - Assigning the mock context to the tool instance via `Object.assign`
 - Testing multiple input scenarios including edge cases (negatives, zero)
 

package/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md

@@ -51,15 +51,18 @@ describe('AddTool schema validation', () => {
 
   it('should coerce valid input and produce correct output', async () => {
     const tool = new AddTool();
+    // Mock the real ExecutionContextBase + ToolContext surface.
+    // 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;
     Object.assign(tool, ctx);
 

package/catalog/frontmcp-testing/examples/test-tool-unit/tool-error-handling-test.md

@@ -19,8 +19,8 @@ Test that a tool throws the correct MCP error classes with proper error codes an
 
 ```typescript
 // src/tools/__tests__/lookup.tool.spec.ts
-import { ToolContext } from '@frontmcp/sdk';
-import { ResourceNotFoundError, MCP_ERROR_CODES } from '@frontmcp/sdk';
+import { MCP_ERROR_CODES, ResourceNotFoundError, ToolContext } from '@frontmcp/sdk';
+
 import { LookupTool } from '../lookup.tool';
 
 describe('LookupTool error handling', () => {
@@ -29,15 +29,18 @@ describe('LookupTool error handling', () => {
   beforeEach(() => {
     tool = new LookupTool();
 
+    // Mock the real ExecutionContextBase + ToolContext surface.
+    // 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;
 
     Object.assign(tool, ctx);

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

@@ -120,7 +120,7 @@ describe('MyTool', () => {
 
 ### Testing a Resource
 
-Resources extend `ResourceContext` and implement `read()`. Verify the output matches the MCP `ReadResourceResult` shape.
+Resources extend `ResourceContext` and implement `execute(uri, params)`. Verify the output matches the MCP `ReadResourceResult` shape.
 
 ```typescript
 // my-resource.spec.ts
@@ -129,7 +129,7 @@ import { MyResource } from '../my-resource';
 describe('MyResource', () => {
   it('should return resource contents', 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: [
@@ -174,7 +174,7 @@ describe('MyPrompt', () => {
 Always verify error classes with `instanceof` checks and error codes:
 
 ```typescript
-import { ResourceNotFoundError, MCP_ERROR_CODES } from '@frontmcp/sdk';
+import { MCP_ERROR_CODES, ResourceNotFoundError } from '@frontmcp/sdk';
 
 describe('ResourceNotFoundError', () => {
   it('should be instanceof ResourceNotFoundError', () => {
@@ -217,48 +217,41 @@ The `@frontmcp/testing` library provides a full E2E testing framework with a tes
 
 ```typescript
 import {
-  // Primary API (fixture-based)
-  test,
+  AuthHeaders,
+  BaselineStore,
+  DefaultInterceptorChain,
+  // Interceptors & mocking
+  DefaultMockRegistry,
   expect,
-
+  httpMock,
+  httpResponse,
+  interceptors,
+  LeakDetector,
+  // Assertions & matchers
+  McpAssertions,
+  // Low-level client
+  McpClient,
+  mcpMatchers,
+  McpStdioClientTransport,
   // Manual client API
   McpTestClient,
   McpTestClientBuilder,
-
-  // Server management
-  TestServer,
-
-  // Auth testing
-  TestTokenFactory,
-  AuthHeaders,
-  TestUsers,
-  MockOAuthServer,
+  MetricsCollector,
   MockAPIServer,
   MockCimdServer,
-
-  // Assertions & matchers
-  McpAssertions,
-  mcpMatchers,
-
-  // Interceptors & mocking
-  DefaultMockRegistry,
-  DefaultInterceptorChain,
+  MockOAuthServer,
   mockResponse,
-  interceptors,
-  httpMock,
-  httpResponse,
-
   // Performance testing
   perfTest,
-  MetricsCollector,
-  LeakDetector,
-  BaselineStore,
   RegressionDetector,
   ReportGenerator,
-
-  // Low-level client
-  McpClient,
-  McpStdioClientTransport,
+  // Primary API (fixture-based)
+  test,
+  // Server management
+  TestServer,
+  // Auth testing
+  TestTokenFactory,
+  TestUsers,
 } from '@frontmcp/testing';
 ```
 
@@ -274,7 +267,7 @@ The fixture API manages server lifecycle automatically:
 
 ```typescript
 // my-server.e2e.spec.ts
-import { test, expect } from '@frontmcp/testing';
+import { expect, test } from '@frontmcp/testing';
 
 test.use({
   server: './src/main.ts',
@@ -316,10 +309,13 @@ test('prompts return well-formed messages', async ({ mcp }) => {
 
 For more control, use `McpTestClient` and `TestServer` directly:
 
-> **Note:** `npx tsx src/main.ts` is correct **only inside E2E tests** (the test framework uses it internally via `resolveServerCommand`). For development and running the server outside of tests, always use `frontmcp dev` (or your package.json `dev` script). Never run `npx tsx src/main.ts` directly for development.
+> **Note:** `TestServer.start({ command })` accepts any command that boots your server — your `dev` npm script, the built artifact (e.g. `node dist/main.js`), or `npx tsx src/main.ts` for unbuilt sources. The example below uses `npx tsx`; substitute whatever you use to start the server in development.
 
 ```typescript
 // advanced.e2e.spec.ts
+// Real API: libs/testing/src/server/test-server.ts:101 (TestServer.start),
+// libs/testing/src/client/mcp-test-client.builder.ts (McpTestClient.create),
+// libs/testing/src/client/mcp-test-client.types.ts:55 (TestTransportType = 'sse' | 'streamable-http')
 import { McpTestClient, TestServer } from '@frontmcp/testing';
 
 describe('Advanced E2E', () => {
@@ -333,7 +329,7 @@ describe('Advanced E2E', () => {
     });
 
     client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
-      .withTransport('modern') // 'modern' preset enables streamable HTTP + strict sessions
+      .withTransport('streamable-http')
       .buildAndConnect();
   });
 
@@ -357,7 +353,7 @@ describe('Advanced E2E', () => {
 ### Testing with Authentication
 
 ```typescript
-import { test, expect, TestTokenFactory } from '@frontmcp/testing';
+import { expect, test } from '@frontmcp/testing';
 
 test.use({
   server: './src/main.ts',
@@ -521,7 +517,7 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 ### Unit Tests
 
 - [ ] Each tool's `execute()` method is tested with valid and invalid inputs
-- [ ] Each resource's `read()` method is tested and output matches `ReadResourceResult` shape
+- [ ] Each resource's `execute(uri, params)` method is tested and output matches `ReadResourceResult` shape
 - [ ] Each prompt's `execute()` method is tested and output matches `GetPromptResult` shape
 - [ ] Constructor validation tests verify throws on invalid config
 - [ ] Error classes are verified with `instanceof` checks and `mcpErrorCode` assertions