@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/{setup/setup-sqlite/SKILL.md → frontmcp-setup/references/setup-sqlite.md}

@@ -1,66 +1,26 @@
----
-name: setup-sqlite
-description: Configure SQLite for local development and single-instance deployments. Use when setting up local storage, CLI tools, unix-socket daemons, or WAL mode.
-category: setup
-tags: [setup, sqlite, storage, local]
-targets: [node]
-bundle: [minimal, full]
-hasResources: false
-storageDefault:
-  node: sqlite
-allowed-tools: Bash Write Edit Read Grep
-parameters:
-  - name: walMode
-    type: boolean
-    description: Enable WAL (Write-Ahead Logging) mode for better read concurrency
-    default: true
-  - name: dbPath
-    type: string
-    description: File path for the SQLite database
-    default: '~/.frontmcp/data/sessions.sqlite'
-  - name: encryption
-    type: boolean
-    description: Enable AES-256-GCM at-rest encryption for stored values
-    default: false
-examples:
-  - scenario: Set up SQLite storage for a CLI tool
-    parameters:
-      walMode: true
-      dbPath: '~/.frontmcp/data/sessions.sqlite'
-      encryption: false
-  - scenario: Configure SQLite for a unix-socket daemon with encryption
-    parameters:
-      walMode: true
-      dbPath: '/var/lib/frontmcp/daemon.sqlite'
-      encryption: true
-compatibility: 'Node.js 18+. Requires better-sqlite3 native bindings (build tools needed). Linux, macOS, Windows (x64/arm64). Not recommended for multi-instance, serverless, or horizontally scaled deployments.'
-install:
-  destinations: [project-local]
-  mergeStrategy: overwrite
-  dependencies: [setup-project]
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/sqlite-setup
----
-
 # Configure SQLite for Local and Single-Instance Deployments
 
-## When to use this skill
+## When to Use This Skill
+
+### Must Use
+
+- Your FrontMCP server runs as a single instance with local persistent storage (CLI tools, unix-socket daemons)
+- You need session or key-value storage for local development without running external services
+- Your deployment target is a single-process Node.js server on a machine with a local filesystem
 
-Use this skill when your FrontMCP server runs as a single instance and does not need distributed storage. SQLite is the right choice for:
+### Recommended
 
-- CLI tools and local-only MCP servers
-- Single-instance daemons communicating over stdio or unix socket
+- You are building a CLI tool or local-only MCP server that will never be horizontally scaled
 - Local development when running a Redis container is unnecessary overhead
-- Projects that will never run multiple instances behind a load balancer
+- Projects that store session data, credentials, or counters on a single host
 
-Do NOT use SQLite when:
+### Skip When
 
-- Deploying to serverless (Vercel, Lambda, Cloudflare) -- there is no persistent local filesystem
-- Running multiple server instances (SQLite does not support distributed access)
-- You need pub/sub for resource subscriptions (use Redis instead)
-- Horizontal scaling is required now or in the near future
+- Deploying to serverless (Vercel, Lambda, Cloudflare) where there is no persistent local filesystem -- use `setup-redis` instead
+- Running multiple server instances behind a load balancer -- use `setup-redis` instead
+- You need pub/sub for resource subscriptions or real-time event distribution -- use `setup-redis` instead
 
-For multi-instance or serverless deployments, use the `setup-redis` skill instead.
+> **Decision:** Use SQLite for single-instance local storage; switch to `setup-redis` for multi-instance or serverless deployments.
 
 ## Step 1 -- Install the Native Dependency
 
@@ -175,7 +135,7 @@ The encryption uses HKDF-SHA256 for key derivation and AES-256-GCM for value enc
     walMode: true,
   },
   transport: {
-    protocol: 'streamable-http',
+    protocol: 'modern', // 'modern' preset enables streamable HTTP + strict sessions
   },
   http: {
     unixSocket: '/tmp/frontmcp.sock',
@@ -206,7 +166,7 @@ WAL (Write-Ahead Logging) mode is enabled by default (`walMode: true`) and is st
 
 WAL mode creates two additional files alongside the database:
 
-```
+```text
 sessions.sqlite       # main database
 sessions.sqlite-wal   # write-ahead log
 sessions.sqlite-shm   # shared memory index
@@ -275,7 +235,7 @@ frontmcp dev
 
 Check the logs for SQLite initialization:
 
-```
+```text
 [SessionStoreFactory] Creating SQLite session store
 ```
 
@@ -334,26 +294,54 @@ The change in `src/main.ts`:
 })
 ```
 
-## Troubleshooting
+## Common Patterns
 
-| Symptom                               | Likely Cause                               | Fix                                                                        |
-| ------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'` | Native module not installed                | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                     |
-| `Could not locate the bindings file`  | Native compilation failed                  | Ensure build tools are installed, delete `node_modules` and reinstall      |
-| `SQLITE_BUSY` errors                  | Multiple processes accessing the same file | Use WAL mode or ensure only one process writes to the database             |
-| `SQLITE_READONLY`                     | File permissions                           | Check write permissions on the database file and its parent directory      |
-| Database file on NFS with WAL errors  | WAL requires local filesystem              | Move the database to a local disk or disable WAL mode                      |
-| Encrypted data unreadable             | Wrong or missing encryption secret         | The secret must be identical across restarts; if lost, delete the database |
+| Pattern                        | Correct                                            | Incorrect                                  | Why                                                                                                           |
+| ------------------------------ | -------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Database path                  | `path: '~/.frontmcp/data/sessions.sqlite'`         | `path: './sessions.sqlite'`                | Tilde-prefixed or absolute paths are stable across working directories; relative paths break when CWD changes |
+| Encryption secret source       | `secret: process.env['SQLITE_ENCRYPTION_SECRET']!` | `secret: 'hardcoded-secret-value'`         | Secrets must come from environment variables, never committed to source code                                  |
+| WAL mode default               | `walMode: true` (or omit, defaults to `true`)      | `walMode: false` without a specific reason | WAL provides better read concurrency with no downside on local filesystems                                    |
+| Native dependency installation | `yarn add @frontmcp/storage-sqlite better-sqlite3` | `yarn add better-sqlite3` alone            | Both packages are required; the storage package wraps the native bindings with FrontMCP session store logic   |
+| TTL cleanup interval           | `ttlCleanupIntervalMs: 60000` (default)            | `ttlCleanupIntervalMs: 500`                | Overly aggressive cleanup wastes CPU; the default 60s is appropriate for most workloads                       |
 
 ## Verification Checklist
 
-Before reporting completion, verify:
+### Dependencies
+
+- [ ] `@frontmcp/storage-sqlite` and `better-sqlite3` are in `dependencies`
+- [ ] `@types/better-sqlite3` is in `devDependencies`
+- [ ] `node -e "require('better-sqlite3')"` runs without errors
+
+### Configuration
+
+- [ ] The `sqlite` block is present in the `@FrontMcp` decorator config with a valid `path` string
+- [ ] The database path parent directory exists and is writable
+- [ ] WAL mode is enabled (default) unless there is a specific filesystem limitation
+
+### Environment and Security
+
+- [ ] Environment variables are in `.env` and `.env` is gitignored
+- [ ] If encryption is enabled: `SQLITE_ENCRYPTION_SECRET` is set and is at least 32 characters
+- [ ] No secrets are hardcoded in source files
+
+### Runtime
+
+- [ ] The server starts without SQLite errors (`frontmcp dev`)
+- [ ] The database file is created at the configured path
+- [ ] If WAL mode is enabled: `.sqlite-wal` and `.sqlite-shm` files appear alongside the database
+
+## Troubleshooting
+
+| Problem                                 | Cause                                                           | Solution                                                                                                                  |
+| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
+| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`) or ensure only one process writes to the database                                       |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
+
+## Reference
 
-1. `@frontmcp/storage-sqlite` and `better-sqlite3` are in `dependencies`
-2. `@types/better-sqlite3` is in `devDependencies`
-3. `node -e "require('better-sqlite3')"` runs without errors
-4. The `sqlite` block is present in the `@FrontMcp` decorator config with a valid `path` string
-5. The database path parent directory exists and is writable
-6. Environment variables are in `.env` and `.env` is gitignored
-7. The server starts without SQLite errors (`frontmcp dev`)
-8. If encryption is enabled: `SQLITE_ENCRYPTION_SECRET` is set and is at least 32 characters
+- **Docs:** [SQLite Setup Guide](https://docs.agentfront.dev/frontmcp/deployment/sqlite-setup)
+- **Related skills:** `setup-redis`, `setup-project`, `nx-workflow`

package/catalog/frontmcp-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: frontmcp-testing
+description: "Domain router for testing MCP servers \u2014 unit tests, E2E tests, coverage, and quality assurance. Use when starting any testing task for a FrontMCP application."
+tags: [router, testing, jest, e2e, coverage, quality, guide]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/testing/overview
+---
+
+# FrontMCP Testing Router
+
+Entry point for testing FrontMCP applications. This skill helps you navigate testing strategies across component types and find the right patterns for unit, integration, and E2E tests.
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up testing infrastructure for a new FrontMCP project
+- Deciding how to test a specific component type (tool, resource, prompt, agent)
+- Planning a testing strategy that covers unit, E2E, and coverage requirements
+
+### Recommended
+
+- Looking up testing patterns for a component type you haven't tested before
+- Understanding the relationship between unit tests, E2E tests, and coverage thresholds
+- Troubleshooting test failures or coverage gaps
+
+### Skip When
+
+- You need detailed Jest configuration and test harness setup (go directly to `setup-testing`)
+- You need to build components, not test them (see `frontmcp-development`)
+- You need to deploy, not test (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill for testing strategy and routing. Use `setup-testing` for hands-on Jest configuration and test writing.
+
+## 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            | `setup-testing` + `configure-auth` | E2E with OAuth tokens, session validation                 |
+| Test deployment builds                  | `setup-testing` + `deploy-to-*`    | Smoke tests against built output                          |
+
+## Testing Strategy by Component Type
+
+| Component | Unit Test Focus                                          | E2E Test Focus                     | Key Assertions                                 |
+| --------- | -------------------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
+| Tool      | Input validation, execute logic, error paths, DI mocking | `tools/call` via MCP client        | Output matches schema, errors return MCP codes |
+| Resource  | URI resolution, read content, template param handling    | `resources/read` via MCP client    | Content type correct, URI patterns resolve     |
+| Prompt    | Argument validation, message generation, multi-turn      | `prompts/get` via MCP client       | Messages match expected structure              |
+| Agent     | LLM config, tool selection, handoff logic                | Agent loop via MCP client          | Tools called in order, result synthesized      |
+| Provider  | Lifecycle hooks, factory output, singleton behavior      | Indirectly via tool/resource tests | Instance reuse, cleanup on scope disposal      |
+| Job       | Progress tracking, retry logic, attempt counting         | Job execution via test harness     | Progress events emitted, retries respected     |
+
+## Cross-Cutting Testing Patterns
+
+| Pattern            | Rule                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                           |
+| 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                     |
+| Error testing      | Assert `instanceof` specific error class AND MCP error code                           |
+| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors |
+
+## Common Patterns
+
+| Pattern            | Correct                                                       | Incorrect                                    | Why                                                                   |
+| ------------------ | ------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
+| Test file location | `fetch-weather.tool.spec.ts` next to source                   | `__tests__/fetch-weather.test.ts`            | Co-location with `.spec.ts` extension matches FrontMCP conventions    |
+| DI mocking         | Replace token with mock via `scope.register(TOKEN, mockImpl)` | `jest.mock('../provider')` module mock       | DI mocking is cleaner, type-safe, and tests the real integration path |
+| Error assertions   | `expect(err).toBeInstanceOf(ResourceNotFoundError)`           | `expect(err.message).toContain('not found')` | Class checks are stable; message strings are fragile                  |
+| E2E transport      | Use `@frontmcp/testing` MCP client with real server           | HTTP requests with `fetch`                   | The test client handles protocol details (session, framing)           |
+| Coverage gaps      | Investigate uncovered branches, add targeted tests            | Add `istanbul ignore` comments               | Coverage gaps often hide real bugs; ignoring them defeats the purpose |
+
+## Verification Checklist
+
+### Infrastructure
+
+- [ ] Jest configured with `@frontmcp/testing` preset
+- [ ] Coverage thresholds set to 95% in jest.config
+- [ ] Test files use `.spec.ts` extension throughout
+
+### Unit Tests
+
+- [ ] Each tool has unit tests covering happy path, validation errors, and DI failures
+- [ ] Each resource has unit tests covering URI resolution and read content
+- [ ] Provider lifecycle (init, dispose) tested where applicable
+
+### E2E Tests
+
+- [ ] At least one E2E test exercises full MCP protocol flow (connect, list, call, disconnect)
+- [ ] Authenticated E2E tests use proper test tokens (not mocked auth)
+- [ ] E2E tests clean up state after execution
+
+### CI Integration
+
+- [ ] Tests run in CI pipeline on every PR
+- [ ] Coverage report published and enforced
+- [ ] Failing tests block merge
+
+## Troubleshooting
+
+| Problem                            | Cause                                                   | Solution                                                                               |
+| ---------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Jest not finding test files        | Wrong file extension (`.test.ts` instead of `.spec.ts`) | Rename to `.spec.ts`; check `testMatch` in jest.config                                 |
+| Coverage below 95%                 | Untested error paths or conditional branches            | Run `jest --coverage` and inspect uncovered lines in the report                        |
+| E2E test timeout                   | Server startup too slow or port conflict                | Increase Jest timeout; use random port allocation                                      |
+| DI resolution fails in tests       | Provider not registered in test scope                   | Register mock providers before creating the test context                               |
+| Istanbul shows 0% on async methods | TypeScript source-map mismatch with Istanbul            | Known issue with some TS compilation settings; verify coverage with actual test output |
+
+## Reference
+
+- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
+- Related skills: `setup-testing`, `create-tool`, `create-resource`, `create-prompt`, `configure-auth`

package/catalog/{testing/setup-testing/SKILL.md → frontmcp-testing/references/setup-testing.md}

@@ -1,53 +1,29 @@
----
-name: setup-testing
-description: Configure and run unit and E2E tests for FrontMCP applications. Use when writing tests, setting up Jest, configuring coverage, or testing tools and resources.
-tags:
-  - testing
-  - jest
-  - e2e
-  - quality
-bundle:
-  - recommended
-  - full
-visibility: both
-priority: 5
-parameters:
-  - name: test-type
-    description: Type of test to set up (unit, e2e, or both)
-    type: string
-    required: false
-    default: both
-  - name: coverage-threshold
-    description: Minimum coverage percentage required
-    type: number
-    required: false
-    default: 95
-examples:
-  - scenario: Set up unit tests for a tool with Jest
-    parameters:
-      test-type: unit
-    expected-outcome: Tool execute method is tested with mocked context, assertions verify output schema
-  - scenario: Set up E2E tests against a running MCP server
-    parameters:
-      test-type: e2e
-    expected-outcome: McpTestClient connects to server, calls tools, and verifies responses with MCP matchers
-  - scenario: Configure full test suite with 95% coverage enforcement
-    parameters:
-      test-type: both
-      coverage-threshold: 95
-    expected-outcome: Jest runs unit and E2E tests with coverage thresholds enforced in CI
-license: MIT
-compatibility: Requires Node.js 18+, Jest 29+, and @frontmcp/testing for E2E tests
-metadata:
-  category: testing
-  difficulty: beginner
-  docs: https://docs.agentfront.dev/frontmcp/testing/overview
----
-
 # Set Up Testing for FrontMCP Applications
 
 This skill covers testing FrontMCP applications at three levels: unit tests for individual tools/resources/prompts, E2E tests exercising the full MCP protocol, and manual testing with `frontmcp dev`.
 
+## When to Use This Skill
+
+### Must Use
+
+- Writing the first unit test for a new tool, resource, or prompt class
+- Setting up Jest configuration and coverage thresholds for a FrontMCP library
+- Creating E2E tests that exercise the full MCP protocol via `McpTestClient`
+
+### Recommended
+
+- Adding coverage enforcement to CI for an existing library that lacks thresholds
+- Writing authenticated E2E tests with `TestTokenFactory` and `MockOAuthServer`
+- Migrating existing `.test.ts` files to the required `.spec.ts` naming convention
+
+### Skip When
+
+- Building a new tool class from scratch (see `create-tool`)
+- Creating resources or prompts before you have anything to test (see `create-resource`, `create-prompt`)
+- Debugging deployment issues unrelated to test configuration (see `deploy-to-node`, `deploy-to-vercel`)
+
+> **Decision:** Use this skill when you need to configure, write, or run Jest tests for FrontMCP tools, resources, or prompts.
+
 ## Testing Standards
 
 FrontMCP requires:
@@ -65,7 +41,7 @@ FrontMCP requires:
 
 Place test files next to the source file or in a `__tests__` directory:
 
-```
+```text
 src/
   tools/
     my-tool.ts
@@ -350,7 +326,7 @@ describe('Advanced E2E', () => {
     });
 
     client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
-      .withTransport('streamable-http')
+      .withTransport('modern') // 'modern' preset enables streamable HTTP + strict sessions
       .buildAndConnect();
   });
 
@@ -514,26 +490,61 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 | Playwright browser tests | UI tests with Playwright                          | `.pw.spec.ts`   |
 | Constructor validation   | Unit test verifying throws on invalid input       | `.spec.ts`      |
 
-## Common Mistakes
+## Common Patterns
+
+| Pattern          | Correct                                                  | Incorrect                                        | Why                                                                            |
+| ---------------- | -------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| Test file naming | `my-tool.spec.ts`, `my-tool.e2e.spec.ts`                 | `my-tool.test.ts`, `my-tool.test.tsx`            | Nx and Jest configs only recognize `.spec.ts` convention                       |
+| Test description | `'should return formatted output for valid input'`       | `'PT-001: test formatted output'`                | Descriptive names; no ID prefixes                                              |
+| Mock types       | `const ctx = { scope: { get: jest.fn() } } as unknown`   | `const ctx: any = { scope: { get: jest.fn() } }` | Strict TypeScript; avoid `any` in mocks                                        |
+| Error assertion  | `expect(err).toBeInstanceOf(ResourceNotFoundError)`      | `expect(() => ...).toThrow()`                    | Verify the exact error class and MCP error code, not just that something threw |
+| Constructor test | Always test `new MyService({})` throws on invalid config | Skip constructor validation                      | Catches misconfiguration early; required for 95% branch coverage               |
+| E2E test imports | `import { test, expect } from '@frontmcp/testing'`       | `import { expect } from '@jest/globals'`         | `@frontmcp/testing` provides MCP-specific matchers like `toContainTool()`      |
+| Coverage check   | `nx test my-lib --coverage` before push                  | Push without coverage check                      | CI enforces 95% thresholds; catch failures locally first                       |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Jest config exists with `coverageThreshold` set to 95% for all metrics
+- [ ] `tsconfig.spec.json` exists and extends the base tsconfig
+- [ ] `@frontmcp/testing` is installed as a dev dependency for E2E tests
+- [ ] Test files use `.spec.ts` (unit), `.e2e.spec.ts` (E2E), or `.perf.spec.ts` (perf) extension
+
+### 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 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
+
+### E2E Tests
+
+- [ ] Fixture-based tests use `test.use({ server, port })` for server lifecycle
+- [ ] Tools appear in `tools/list` response via `toContainTool()` matcher
+- [ ] Tool calls return expected results via `toBeSuccessful()` matcher
+- [ ] Authenticated tests use `TestTokenFactory` and verify rejection without token
+
+### CI Integration
+
+- [ ] `nx test <lib> --coverage` passes locally with 95%+ on all metrics
+- [ ] Unused imports are cleaned via `node scripts/fix-unused-imports.mjs`
+- [ ] No TypeScript warnings in test files
+
+## Troubleshooting
 
-- **Using `.test.ts` file extension** -- all test files must use `.spec.ts`. The Nx and Jest configurations expect this convention.
-- **Testing implementation details** -- test inputs and outputs, not internal method calls. Tools should be tested through their `execute` interface.
-- **Skipping constructor validation tests** -- always test that constructors throw on invalid input.
-- **Skipping error `instanceof` checks** -- verify that thrown errors are instances of the correct error class, not just that an error was thrown.
-- **Using test ID prefixes** -- do not use prefixes like "PT-001" in test names. Use descriptive names like "should return formatted output for valid input".
-- **Falling below 95% coverage** -- the CI pipeline enforces coverage thresholds. Run `nx test <lib> --coverage` locally before pushing.
-- **Using `any` in test mocks** -- use `unknown` or properly typed mocks. Follow the strict TypeScript guidelines.
+| Problem                                      | Cause                                                   | Solution                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Jest cannot find test files                  | Files use `.test.ts` instead of `.spec.ts`              | Rename to `.spec.ts`; Nx test runner only picks up `.spec.ts` by default                              |
+| Coverage below 95% threshold                 | Untested branches or constructor paths                  | Run `nx test <lib> --coverage` and check the HTML report for uncovered lines                          |
+| E2E test times out on `TestServer.start()`   | Server entrypoint fails to start or wrong port          | Verify `server` path and `port` in `test.use()`; check server logs for startup errors                 |
+| `toContainTool` matcher not found            | Using `expect` from Jest instead of `@frontmcp/testing` | Import `expect` from `@frontmcp/testing` to get MCP-specific matchers                                 |
+| `McpTestClient.create()` connection refused  | Test server not running or wrong `baseUrl`              | Ensure `TestServer.start()` completes before creating client; verify port matches                     |
+| Istanbul shows 0% coverage for async methods | TypeScript compilation source-map mismatch              | Known issue with `ts-jest` and certain async patterns; check `tsconfig.spec.json` source-map settings |
+| Auth E2E test returns 401 unexpectedly       | Token not set or expired                                | Call `mcp.setAuthToken(token)` before the tool call; use `auth.createToken()` with valid claims       |
 
 ## Reference
 
-- Testing package: [`@frontmcp/testing`](https://docs.agentfront.dev/frontmcp/testing/overview)
-- Test client: `McpTestClient` — import from `@frontmcp/testing`
-- Test client builder: `McpTestClient.builder()` — fluent API for test setup
-- MCP matchers: `toContainTool()`, `toBeSuccessful()` — import from `@frontmcp/testing`
-- Test fixtures: `createTestFixture()` — import from `@frontmcp/testing`
-- Test server: `TestServer` — import from `@frontmcp/testing`
-- Performance testing: `perfTest()`, `MetricsCollector` — import from `@frontmcp/testing`
-- Auth testing: `TestTokenFactory`, `MockOAuthServer` — import from `@frontmcp/testing`
-- Interceptors: `TestInterceptor` — import from `@frontmcp/testing`
-- HTTP mocking: `HttpMock` — import from `@frontmcp/testing`
-- [Source code on GitHub](https://github.com/agentfront/frontmcp/tree/main/libs/testing)
+- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
+- Related skills: `create-tool`, `create-resource`, `create-prompt`, `setup-project`, `nx-workflow`

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-tool-unit.md

@@ -1,6 +1,7 @@
 # Unit Testing a Tool
 
 ```typescript
+import { z } from 'zod';
 import { ToolContext } from '@frontmcp/sdk';
 import { AddTool } from '../tools/add.tool';