@frontmcp/skills 1.1.2 → 1.2.0

package/catalog/frontmcp-development/references/create-provider.md

@@ -13,7 +13,7 @@ Providers are singleton services — database pools, API clients, config objects
 
 - Multiple tools, resources, or agents need a shared database connection pool
 - API clients or external service connections must be singleton (not recreated per request)
-- You need lifecycle management with `onInit()` at startup and `onDestroy()` at shutdown
+- You need async one-time setup before any tool runs (use `AsyncProvider({ useFactory })`)
 
 ### Recommended
 
@@ -27,7 +27,7 @@ Providers are singleton services — database pools, API clients, config objects
 - You need to build an executable action for AI clients (see `create-tool`)
 - You need autonomous LLM-driven orchestration (see `create-agent`)
 
-> **Decision:** Use this skill when you need a shared, singleton service with lifecycle management that tools, resources, and agents access via `this.get(token)`.
+> **Decision:** Use this skill when you need a shared, singleton service that tools, resources, and agents access via `this.get(token)`. `@Provider` does **not** support `onInit`/`onDestroy` lifecycle hooks — use the constructor for sync setup, `AsyncProvider({ useFactory })` for async setup, and an explicit method (e.g., `close()`) plus the framework's shutdown path for cleanup.
 
 ## Step 1: Define a Token
 
@@ -47,31 +47,61 @@ const DB_TOKEN: Token<DatabaseService> = Symbol('DatabaseService');
 
 ## Step 2: Create the Provider
 
+`@Provider` is a class decorator. There are two patterns depending on whether
+your provider needs async setup:
+
+**Pattern A — sync setup (no async I/O at boot):** decorate the class, do the
+work in the constructor.
+
 ```typescript
 import { Provider } from '@frontmcp/sdk';
-import { createPool, Pool } from 'your-db-driver';
 
-@Provider({ name: 'DatabaseProvider' })
-class DatabaseProvider implements DatabaseService {
-  private pool!: Pool;
+@Provider({ name: 'ConfigProvider' })
+class ConfigProvider {
+  // Constructor runs synchronously the first time the class is resolved;
+  // a thrown error here aborts startup (fail-fast).
+  readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
+  readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
+}
+```
 
-  async onInit() {
-    // Called once when server starts
-    this.pool = await createPool({
-      connectionString: process.env.DATABASE_URL,
-      max: 20,
-    });
-  }
+**Pattern B — async setup (e.g., open a connection pool):** use `AsyncProvider`
+factory. The framework `await`s `useFactory` before any tool can resolve the
+token, so the pool is guaranteed to be open by the time `this.get(...)` returns.
+
+```typescript
+import { createPool, type Pool } from 'your-db-driver';
+
+import { AsyncProvider, ProviderScope } from '@frontmcp/sdk';
+
+class DatabasePool implements DatabaseService {
+  constructor(private readonly pool: Pool) {}
 
   async query(sql: string, params?: unknown[]) {
     return this.pool.query(sql, params);
   }
 
-  async onDestroy() {
-    // Called when server shuts down
+  async close() {
+    // `@Provider` has no `onDestroy` hook. Expose explicit cleanup as a
+    // method and call it from the host (e.g., before `server.dispose()`)
+    // when the provider owns network/file handles that need to drain.
     await this.pool.end();
   }
 }
+
+export const databaseProvider = AsyncProvider({
+  provide: DB_TOKEN,
+  name: 'DatabaseProvider',
+  scope: ProviderScope.GLOBAL,
+  inject: () => [] as const,
+  useFactory: async (): Promise<DatabaseService> => {
+    const pool = await createPool({
+      connectionString: process.env.DATABASE_URL,
+      max: 20,
+    });
+    return new DatabasePool(pool);
+  },
+});
 ```
 
 ## Step 3: Register in @App or @FrontMcp
@@ -79,7 +109,7 @@ class DatabaseProvider implements DatabaseService {
 ```typescript
 @App({
   name: 'MyApp',
-  providers: [DatabaseProvider], // App-scoped provider
+  providers: [databaseProvider], // App-scoped provider (factory)
   tools: [QueryTool, InsertTool],
 })
 class MyApp {}
@@ -88,7 +118,7 @@ class MyApp {}
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MyApp],
-  providers: [DatabaseProvider], // Server-scoped provider
+  providers: [databaseProvider], // Server-scoped provider
 })
 class Server {}
 ```
@@ -167,12 +197,18 @@ const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
 
 @Provider({ name: 'ApiClientProvider' })
 class ApiClientProvider implements ApiClient {
-  private baseUrl!: string;
-  private apiKey!: string;
-
-  async onInit() {
-    this.baseUrl = process.env.API_URL!;
-    this.apiKey = process.env.API_KEY!;
+  // No `onInit` hook — read env in the constructor and fail fast on missing values.
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor() {
+    const baseUrl = process.env.API_URL;
+    const apiKey = process.env.API_KEY;
+    if (!baseUrl || !apiKey) {
+      throw new Error('ApiClientProvider: API_URL and API_KEY must be set');
+    }
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
   }
 
   async get(path: string) {
@@ -206,12 +242,15 @@ class CacheProvider extends Map<string, unknown> {
 
 ## Provider Lifecycle
 
-| Method        | When Called             | Use For                          |
-| ------------- | ----------------------- | -------------------------------- |
-| `onInit()`    | Server startup (async)  | Open connections, load config    |
-| `onDestroy()` | Server shutdown (async) | Close connections, flush buffers |
+`@Provider` classes have **no** `onInit` / `onDestroy` lifecycle hooks. Choose the right setup pattern for your provider:
+
+| Setup need                                 | Pattern                                                               | Cleanup                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------- |
+| Sync — read env, build a Map, etc.         | `@Provider({ name })` + constructor (throw on missing config)         | None / GC (or expose a `close()` and call from host)    |
+| Async — open a pool, fetch a remote schema | `AsyncProvider({ provide, name, scope, useFactory })` factory binding | Expose `close()`/`stop()`; framework dispose runs first |
+| Singleton with no setup (e.g., a `Map`)    | `@Provider({ name })` on the class                                    | None                                                    |
 
-Providers are initialized in dependency order — if Provider A depends on Provider B, B initializes first.
+`AsyncProvider` factories are awaited in dependency order before any tool can resolve the bound token, so async setup completes before user code runs.
 
 ## Nx Generator
 
@@ -231,48 +270,49 @@ frontmcp dev
 
 ## Common Patterns
 
-| Pattern            | Correct                                                                | Incorrect                                     | Why                                                                               |
-| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
-| Token definition   | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)      | `const DB = 'database'` (string literal)      | Typed `Token<T>` enables compile-time type checking on `this.get()`               |
-| DI resolution      | `this.get(TOKEN)` with error handling                                  | `this.tryGet(TOKEN)!` with non-null assertion | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures |
-| Lifecycle          | Use `onInit()` for async setup, `onDestroy()` for cleanup              | Initializing connections in the constructor   | Constructor runs synchronously; `onInit()` supports async operations              |
-| Registration scope | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped | Registering same provider in multiple apps    | Server-scoped providers are shared; duplicating causes multiple instances         |
-| Config provider    | `readonly` properties from `process.env`                               | Mutable properties that change at runtime     | Providers are singletons; mutable state can cause race conditions                 |
+| Pattern            | Correct                                                                | Incorrect                                        | Why                                                                                         |
+| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Token definition   | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)      | `const DB = 'database'` (string literal)         | Typed `Token<T>` enables compile-time type checking on `this.get()`                         |
+| DI resolution      | `this.get(TOKEN)` with error handling                                  | `this.tryGet(TOKEN)!` with non-null assertion    | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures           |
+| Lifecycle          | `AsyncProvider({ useFactory })` for async setup; constructor for sync  | Using `onInit()` / `onDestroy()` lifecycle hooks | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution |
+| Registration scope | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped | Registering same provider in multiple apps       | Server-scoped providers are shared; duplicating causes multiple instances                   |
+| Config provider    | `readonly` properties from `process.env`                               | Mutable properties that change at runtime        | Providers are singletons; mutable state can cause race conditions                           |
 
 ## Verification Checklist
 
 ### Configuration
 
-- [ ] Provider class has `@Provider` decorator with `name`
+- [ ] Provider class has `@Provider` decorator with `name` (or factory uses `AsyncProvider`)
 - [ ] Token is defined with `Token<T>` using a `Symbol` and typed interface
-- [ ] Provider is registered in `providers` array of `@App` or `@FrontMcp`
-- [ ] `onInit()` handles async setup (DB connections, API clients)
-- [ ] `onDestroy()` cleans up resources (close connections, flush buffers)
+- [ ] Provider (class or `AsyncProvider` factory) is registered in `providers` array of `@App` or `@FrontMcp`
+- [ ] Sync setup happens in the constructor (throws fast on missing config)
+- [ ] Async setup uses `AsyncProvider({ useFactory })`; the framework awaits it before resolution
 
 ### Runtime
 
 - [ ] Server starts without provider initialization errors
 - [ ] `this.get(TOKEN)` resolves the provider in tools, resources, and agents
 - [ ] Provider is a singleton (same instance across all contexts)
-- [ ] Server shutdown calls `onDestroy()` and cleans up resources
+- [ ] Resource-owning providers expose an explicit `close()` / `stop()` method that the host calls before `server.dispose()`
 - [ ] Missing provider throws `DependencyNotFoundError` with a clear message
 
 ## Troubleshooting
 
-| Problem                              | Cause                                               | Solution                                                               |
-| ------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------- |
-| `DependencyNotFoundError` at runtime | Provider not registered in scope                    | Add provider to `providers` array in `@App` or `@FrontMcp`             |
-| Provider `onInit()` fails at startup | Missing environment variable or unreachable service | Check environment variables and service connectivity before starting   |
-| Multiple instances of same provider  | Registered in multiple apps instead of server level | Move to `@FrontMcp` `providers` for shared, server-scoped access       |
-| Type mismatch on `this.get(TOKEN)`   | Token typed with wrong interface                    | Ensure `Token<T>` generic matches the provider's implemented interface |
-| Provider not destroyed on shutdown   | Missing `onDestroy()` method                        | Implement `onDestroy()` to close connections and release resources     |
+| Problem                                | Cause                                                   | Solution                                                                                      |
+| -------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `DependencyNotFoundError` at runtime   | Provider not registered in scope                        | Add provider (class or `AsyncProvider` factory) to `providers` array in `@App` or `@FrontMcp` |
+| Provider constructor throws at startup | Missing environment variable or unreachable service     | Validate env in the constructor; restart with the missing config supplied                     |
+| `AsyncProvider` factory rejects        | Async setup error (DB unreachable, schema fetch failed) | The factory error aborts boot — fix the dependency or wrap with retry inside `useFactory`     |
+| Multiple instances of same provider    | Registered in multiple apps instead of server level     | Move to `@FrontMcp` `providers` for shared, server-scoped access                              |
+| Type mismatch on `this.get(TOKEN)`     | Token typed with wrong interface                        | Ensure `Token<T>` generic matches the provider's implemented interface                        |
+| Resources leak on shutdown             | No explicit cleanup method exposed                      | Add a `close()` / `stop()` method and call it from the host before `server.dispose()`         |
 
 ## Examples
 
-| Example                                                                               | Level        | Description                                                                                           |
-| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
-| [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks. |
-| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.          |
+| Example                                                                               | Level        | Description                                                                                                                                   |
+| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool, bound through `AsyncProvider({ useFactory })` so the pool is opened before any tool runs. |
+| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.                                                  |
 
 > See all examples in [`examples/create-provider/`](../examples/create-provider/)
 

package/catalog/frontmcp-development/references/create-resource.md

@@ -47,8 +47,8 @@ The `@Resource` decorator accepts:
 Create a class extending `ResourceContext` and implement `execute(uri, params)`. It must return a `ReadResourceResult`.
 
 ```typescript
-import { Resource, ResourceContext } from '@frontmcp/sdk';
 import { ReadResourceResult } from '@frontmcp/protocol';
+import { Resource, ResourceContext } from '@frontmcp/sdk';
 
 @Resource({
   name: 'app-config',
@@ -156,8 +156,8 @@ The `@ResourceTemplate` decorator accepts:
 Use `@ResourceTemplate` with `uriTemplate` instead of `uri`. Type the `ResourceContext` generic parameter to get typed `params`.
 
 ```typescript
-import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
 import { ReadResourceResult } from '@frontmcp/protocol';
+import { ResourceContext, ResourceTemplate } from '@frontmcp/sdk';
 
 @ResourceTemplate({
   name: 'user-profile',
@@ -400,7 +400,7 @@ class CachedDataResource extends ResourceContext<{ key: string }> {
 Add resource classes (or function-style resources) to the `resources` array in `@FrontMcp` or `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'my-app',

package/catalog/frontmcp-development/references/create-skill.md

@@ -380,7 +380,7 @@ class AdminProceduresSkill extends SkillContext {}
 Add skill classes (or function-style skills) to the `skills` array in `@FrontMcp` or `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'standards-app',
@@ -472,7 +472,7 @@ The class generator creates the skill file, spec file, and updates barrel export
 ## Complete Example: Project Onboarding Skill
 
 ```typescript
-import { Skill, SkillContext, FrontMcp, App, skill, skillDir } from '@frontmcp/sdk';
+import { App, FrontMcp, Skill, skill, SkillContext, skillDir } from '@frontmcp/sdk';
 
 // Class-based instruction-only skill
 @Skill({

package/catalog/frontmcp-development/references/create-tool.md

@@ -31,7 +31,7 @@ Tools are the primary way to expose executable actions to AI clients in the MCP
 
 ## Class-Based Pattern
 
-Create a class extending `ToolContext<In, Out>` and implement the `execute(input: In): Promise<Out>` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`.
+Create a class extending `ToolContext` and implement the `execute(input)` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`. Do **not** parameterize `ToolContext` with explicit generics — the input/output types are inferred automatically from the `@Tool` decorator.
 
 ```typescript
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
@@ -63,7 +63,7 @@ class GreetUserTool extends ToolContext {
 - `this.mark(stage)` -- set the active execution stage for debugging/tracking
 - `this.fetch(input, init?)` -- HTTP fetch with context propagation
 - `this.notify(message, level?)` -- send a log-level notification to the client
-- `this.respondProgress(value, total?)` -- send a progress notification to the client
+- `this.progress(progress, total?, message?)` -- send a progress notification to the client (returns `Promise<boolean>`)
 
 **Properties:**
 
@@ -116,7 +116,7 @@ The `execute()` parameter type must match the inferred output of `z.object(input
 
 1. **Output validation** -- Prevents data leaks by ensuring your tool only returns fields you explicitly declare. Without `outputSchema`, any data in the return value passes through unvalidated, risking accidental exposure of sensitive fields (internal IDs, tokens, PII).
 2. **CodeCall plugin compatibility** -- The CodeCall plugin uses `outputSchema` to understand what a tool returns, enabling correct VM-based orchestration and pass-by-reference. Tools without `outputSchema` degrade CodeCall's ability to chain results.
-3. **Type safety** -- The `Out` generic on `ToolContext<In, Out>` is inferred from `outputSchema`, giving you compile-time guarantees that `execute()` returns the correct shape.
+3. **Type safety** -- `ToolContext` infers the output type from `outputSchema` automatically (no explicit generics needed), giving you compile-time guarantees that `execute()` returns the correct shape.
 
 ```typescript
 @Tool({
@@ -159,7 +159,7 @@ class GetWeatherTool extends ToolContext {
 
 ### Typed Output Patterns
 
-The `Out` generic on `ToolContext<InSchema, OutSchema, In, Out>` is inferred from `outputSchema`. You can wire the generics explicitly for full type safety — no `as any` casts needed:
+`ToolContext` infers both input and output types from the `@Tool` decorator's `inputSchema` / `outputSchema`. Do not pass explicit generics — the inference is automatic and gives you full type safety with no `as any` casts:
 
 ```typescript
 const inputSchema = {
@@ -328,7 +328,7 @@ this.fail(new ResourceNotFoundError(`Record ${input.id}`));
 
 ## Progress and Notifications
 
-Use `this.notify(message, level?)` to send log-level notifications and `this.respondProgress(value, total?)` to send progress updates to the client.
+Use `this.notify(message, level?)` to send log-level notifications and `this.progress(progress, total?, message?)` to send progress updates to the client. `this.progress()` returns a `Promise<boolean>` indicating whether the notification was sent (`false` if no progress token was provided in the request).
 
 ```typescript
 @Tool({
@@ -346,7 +346,7 @@ class BatchProcessTool extends ToolContext {
     this.mark('processing');
     const results: string[] = [];
     for (let i = 0; i < input.items.length; i++) {
-      await this.respondProgress(i + 1, input.items.length);
+      await this.progress(i + 1, input.items.length, `Processing item ${i + 1}`);
       const result = await this.processItem(input.items[i]);
       results.push(result);
     }
@@ -421,7 +421,7 @@ const AddNumbers = tool({
 });
 ```
 
-The callback receives `(input, ctx)` where `ctx` provides access to the same context methods (`get`, `tryGet`, `fail`, `mark`, `fetch`, `notify`, `respondProgress`).
+The callback receives `(input, ctx)` where `ctx` provides access to the same context methods (`get`, `tryGet`, `fail`, `mark`, `fetch`, `notify`, `progress`).
 
 Register it the same way as a class tool: `tools: [AddNumbers]`.
 

package/catalog/frontmcp-development/references/create-workflow.md

@@ -44,7 +44,7 @@ Create a class decorated with `@Workflow`. The decorator requires `name` and `st
 | `webhook`        | `WebhookConfig`                    | No          | --                | Webhook configuration (when trigger is `'webhook'`)   |
 | `timeout`        | `number`                           | No          | `600000` (10 min) | Maximum total workflow execution time in milliseconds |
 | `maxConcurrency` | `number`                           | No          | `5`               | Maximum number of steps running in parallel           |
-| `permissions`    | `WorkflowPermissions`              | No          | --                | Access control configuration                          |
+| `permissions`    | `WorkflowPermission[]`             | No          | --                | Array of permission rules (one per action)            |
 
 ### WorkflowStep Fields
 
@@ -562,11 +562,7 @@ class BuildArtifactJob extends JobContext {
     url: z.string().url(),
   },
   retry: { maxAttempts: 3, backoffMs: 5000, backoffMultiplier: 2, maxBackoffMs: 30000 },
-  permissions: {
-    actions: ['execute'],
-    roles: ['admin', 'deployer'],
-    scopes: ['deploy:write'],
-  },
+  permissions: [{ action: 'execute', roles: ['admin', 'deployer'], scopes: ['deploy:write'] }],
 })
 class DeployArtifactJob extends JobContext {
   async execute(input: { artifactUrl: string; environment: string }) {
@@ -609,10 +605,12 @@ class NotifyTeamJob extends JobContext {
   },
   timeout: 900000, // 15 minutes
   maxConcurrency: 3,
-  permissions: {
-    actions: ['create', 'read', 'execute', 'list'],
-    roles: ['admin', 'ci-bot'],
-  },
+  permissions: [
+    { action: 'execute', roles: ['admin', 'ci-bot'] },
+    { action: 'create', roles: ['admin', 'ci-bot'] },
+    { action: 'read', roles: ['admin', 'ci-bot'] },
+    { action: 'list', roles: ['admin', 'ci-bot'] },
+  ],
   steps: [
     {
       id: 'checkout',