@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-plugin/basic-plugin-with-provider.md

@@ -0,0 +1,69 @@
+---
+name: basic-plugin-with-provider
+reference: create-plugin
+level: basic
+description: 'A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.'
+tags: [development, plugin, provider]
+features:
+  - 'Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class'
+  - 'Listing providers in both `providers` (for DI registration) and `exports` (for external access)'
+  - 'Registering a plugin in the `plugins` array of `@FrontMcp`'
+---
+
+# Basic Plugin with a Provider
+
+A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.
+
+## Code
+
+```typescript
+// src/plugins/audit-log/providers/audit-logger.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider()
+export class AuditLogger {
+  async logToolCall(toolName: string, userId: string, input: unknown): Promise<void> {
+    console.log(`[AUDIT] ${userId} called ${toolName}`, input);
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { AuditLogger } from './providers/audit-logger.provider';
+
+@Plugin({
+  name: 'audit-log',
+  description: 'Logs tool executions for audit compliance',
+  providers: [AuditLogger],
+  exports: [AuditLogger],
+})
+export default class AuditLogPlugin {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import AuditLogPlugin from './plugins/audit-log/audit-log.plugin';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [AuditLogPlugin],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class
+- Listing providers in both `providers` (for DI registration) and `exports` (for external access)
+- Registering a plugin in the `plugins` array of `@FrontMcp`
+
+## Related
+
+- See `create-plugin` for context extensions, DynamicPlugin, and metadata augmentation

package/catalog/frontmcp-development/examples/create-plugin/configurable-dynamic-plugin.md

@@ -0,0 +1,178 @@
+---
+name: configurable-dynamic-plugin
+reference: create-plugin
+level: advanced
+description: 'A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.'
+tags: [development, plugin, configurable, dynamic]
+features:
+  - 'Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins'
+  - 'Implementing `static dynamicProviders()` to create providers from the input options'
+  - 'Using `TInput` with optional fields and applying defaults in the constructor'
+  - 'Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`'
+  - 'Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage'
+  - 'Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array'
+---
+
+# Configurable Plugin with DynamicPlugin and Metadata Extension
+
+A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.
+
+## Code
+
+```typescript
+// src/plugins/my-plugin/my-plugin.types.ts
+export interface MyPluginOptions {
+  endpoint: string;
+  refreshIntervalMs: number;
+}
+
+export type MyPluginOptionsInput = Omit<MyPluginOptions, 'refreshIntervalMs'> & {
+  refreshIntervalMs?: number;
+};
+
+// Extend the @Tool decorator metadata with a custom field
+declare global {
+  interface ExtendFrontMcpToolMetadata {
+    audit?: {
+      enabled: boolean;
+      level: 'info' | 'warn' | 'critical';
+    };
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.symbols.ts
+import type { Token } from '@frontmcp/sdk';
+import type { MyService } from './providers/my-service.provider';
+
+export const MyServiceToken: Token<MyService> = Symbol('MyService');
+```
+
+```typescript
+// src/plugins/my-plugin/providers/my-service.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { MyPluginOptions } from '../my-plugin.types';
+
+@Provider()
+export class MyService {
+  private readonly endpoint: string;
+  private readonly refreshIntervalMs: number;
+
+  constructor(options: MyPluginOptions) {
+    this.endpoint = options.endpoint;
+    this.refreshIntervalMs = options.refreshIntervalMs;
+  }
+
+  async query(params: Record<string, unknown>): Promise<unknown> {
+    const res = await globalThis.fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+    });
+    return res.json();
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.context-extension.ts
+import type { MyService } from './providers/my-service.provider';
+
+declare module '@frontmcp/sdk' {
+  interface ExecutionContextBase {
+    readonly myService: MyService;
+  }
+  interface PromptContext {
+    readonly myService: MyService;
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.plugin.ts
+import { Plugin, DynamicPlugin, ProviderType } from '@frontmcp/sdk';
+import { MyService } from './providers/my-service.provider';
+import { MyServiceToken } from './my-plugin.symbols';
+import type { MyPluginOptions, MyPluginOptionsInput } from './my-plugin.types';
+import './my-plugin.context-extension';
+
+@Plugin({
+  name: 'my-plugin',
+  description: 'A configurable plugin with context extensions',
+  contextExtensions: [
+    {
+      property: 'myService',
+      token: MyServiceToken,
+      errorMessage: 'MyPlugin is not installed.',
+    },
+  ],
+})
+export default class MyPlugin extends DynamicPlugin<MyPluginOptions, MyPluginOptionsInput> {
+  options: MyPluginOptions;
+
+  constructor(options: MyPluginOptionsInput = { endpoint: '' }) {
+    super();
+    this.options = { refreshIntervalMs: 30_000, ...options };
+  }
+
+  static override dynamicProviders(options: MyPluginOptionsInput): ProviderType[] {
+    return [
+      {
+        provide: MyServiceToken,
+        useFactory: () =>
+          new MyService({
+            refreshIntervalMs: 30_000,
+            ...options,
+          }),
+      },
+    ];
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import MyPlugin from './plugins/my-plugin/my-plugin.plugin';
+
+// Tool using the extended metadata field and context extension
+@Tool({
+  name: 'delete_user',
+  audit: { enabled: true, level: 'critical' }, // Custom metadata from ExtendFrontMcpToolMetadata
+})
+class DeleteUserTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    const result = await this.myService.query({ action: 'delete', userId: input.userId });
+    return result;
+  }
+}
+
+@App({ name: 'MyApp', tools: [DeleteUserTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    MyPlugin.init({
+      endpoint: 'https://api.example.com',
+      refreshIntervalMs: 60_000,
+    }),
+  ],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins
+- Implementing `static dynamicProviders()` to create providers from the input options
+- Using `TInput` with optional fields and applying defaults in the constructor
+- Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`
+- Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage
+- Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array
+
+## Related
+
+- See `create-plugin` for the full list of extensible metadata interfaces and the recommended folder structure

package/catalog/frontmcp-development/examples/create-plugin/plugin-with-context-extension.md

@@ -0,0 +1,107 @@
+---
+name: plugin-with-context-extension
+reference: create-plugin
+level: intermediate
+description: 'A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.'
+tags: [development, sdk, plugin, context, extension]
+features:
+  - "Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file"
+  - "Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase`"
+  - 'Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`'
+  - 'Side-effect import of the context extension file in both the plugin and the barrel export'
+  - 'Accessing the extended property (`this.auditLog`) in tool execution contexts'
+---
+
+# Plugin with Context Extension
+
+A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.
+
+## Code
+
+```typescript
+// src/plugins/audit-log/audit-log.symbols.ts
+import type { Token } from '@frontmcp/sdk';
+import type { AuditLogger } from './providers/audit-logger.provider';
+
+export const AuditLoggerToken: Token<AuditLogger> = Symbol('AuditLogger');
+```
+
+```typescript
+// src/plugins/audit-log/providers/audit-logger.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider()
+export class AuditLogger {
+  async logToolCall(toolName: string, userId: string, input: unknown): Promise<void> {
+    console.log(`[AUDIT] ${userId} called ${toolName}`, input);
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.context-extension.ts
+import type { AuditLogger } from './providers/audit-logger.provider';
+
+declare module '@frontmcp/sdk' {
+  interface ExecutionContextBase {
+    /** Audit logger provided by AuditLogPlugin */
+    readonly auditLog: AuditLogger;
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { AuditLogger } from './providers/audit-logger.provider';
+import { AuditLoggerToken } from './audit-log.symbols';
+import './audit-log.context-extension'; // Side-effect import for type augmentation
+
+@Plugin({
+  name: 'audit-log',
+  description: 'Logs tool executions for audit compliance',
+  providers: [{ provide: AuditLoggerToken, useClass: AuditLogger }],
+  exports: [AuditLoggerToken],
+  contextExtensions: [
+    {
+      property: 'auditLog',
+      token: AuditLoggerToken,
+      errorMessage: 'AuditLogPlugin is not installed. Add it to your @FrontMcp plugins array.',
+    },
+  ],
+})
+export default class AuditLogPlugin {}
+```
+
+```typescript
+// src/plugins/audit-log/index.ts
+import './audit-log.context-extension'; // Side-effect import for type augmentation
+export { default as AuditLogPlugin } from './audit-log.plugin';
+export { AuditLoggerToken } from './audit-log.symbols';
+```
+
+```typescript
+// src/tools/delete-record.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+@Tool({ name: 'delete_record' })
+class DeleteRecordTool extends ToolContext {
+  async execute(input: { recordId: string }) {
+    // this.auditLog is available because AuditLogPlugin is installed
+    await this.auditLog.logToolCall('delete_record', this.scope.userId, input);
+    return { deleted: true };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file
+- Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase`
+- Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`
+- Side-effect import of the context extension file in both the plugin and the barrel export
+- Accessing the extended property (`this.auditLog`) in tool execution contexts
+
+## Related
+
+- See `create-plugin` for the full context extension pattern, metadata extensions, and DynamicPlugin

package/catalog/frontmcp-development/examples/create-plugin-hooks/basic-logging-plugin.md

@@ -0,0 +1,69 @@
+---
+name: basic-logging-plugin
+reference: create-plugin-hooks
+level: basic
+description: 'Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.'
+tags: [development, plugin-hooks, plugin, hooks, logging]
+features:
+  - "Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly"
+  - 'Destructuring `Will` and `Did` decorators from the hook object'
+  - 'Setting `priority: 100` on `@Will` to ensure the logging hook runs early'
+  - 'Registering a plugin in the `plugins` array of `@App`'
+---
+
+# Basic Logging Plugin with @Will and @Did
+
+Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.
+
+## Code
+
+```typescript
+// src/plugins/logging.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Will, Did } = ToolHook;
+
+@Plugin({ name: 'logging-plugin' })
+export class LoggingPlugin {
+  @Will('execute', { priority: 100 })
+  logBefore(ctx) {
+    console.log(`[LOG] Tool "${ctx.toolName}" called with`, ctx.input);
+  }
+
+  @Did('execute')
+  logAfter(ctx) {
+    console.log(`[LOG] Tool "${ctx.toolName}" completed in ${ctx.elapsed()}ms`);
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { LoggingPlugin } from './plugins/logging.plugin';
+
+@App({
+  name: 'my-app',
+  plugins: [LoggingPlugin],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly
+- Destructuring `Will` and `Did` decorators from the hook object
+- Setting `priority: 100` on `@Will` to ensure the logging hook runs early
+- Registering a plugin in the `plugins` array of `@App`
+
+## Related
+
+- See `create-plugin-hooks` for the full hook decorator API reference
+- See `official-plugins` for ready-made plugins that include logging capabilities

package/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md

@@ -0,0 +1,80 @@
+---
+name: caching-with-around
+reference: create-plugin-hooks
+level: intermediate
+description: 'Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.'
+tags: [development, cache, plugin-hooks, plugin, hooks, caching]
+features:
+  - 'Using `@Around` to wrap the `execute` stage with before-and-after logic'
+  - 'Calling `await next()` to invoke the original stage and capture its result'
+  - 'Short-circuiting execution by returning cached data without calling `next()`'
+  - 'Building a cache key from `ctx.toolName` and `ctx.input`'
+---
+
+# Caching Plugin with @Around Hook
+
+Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.
+
+## Code
+
+```typescript
+// src/plugins/cache.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Around } = ToolHook;
+
+@Plugin({ name: 'cache-plugin' })
+export class CachePlugin {
+  private cache = new Map<string, { data: unknown; expiry: number }>();
+
+  @Around('execute', { priority: 90 })
+  async cacheResults(ctx, next) {
+    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const cached = this.cache.get(key);
+
+    if (cached && cached.expiry > Date.now()) {
+      return cached.data;
+    }
+
+    const result = await next();
+
+    this.cache.set(key, {
+      data: result,
+      expiry: Date.now() + 60_000,
+    });
+
+    return result;
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { CachePlugin } from './plugins/cache.plugin';
+
+@App({
+  name: 'my-app',
+  plugins: [CachePlugin],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'cached-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Using `@Around` to wrap the `execute` stage with before-and-after logic
+- Calling `await next()` to invoke the original stage and capture its result
+- Short-circuiting execution by returning cached data without calling `next()`
+- Building a cache key from `ctx.toolName` and `ctx.input`
+
+## Related
+
+- See `create-plugin-hooks` for all hook decorator types and their timing
+- See `official-plugins` for the production-ready `CachePlugin` from `@frontmcp/plugin-cache`

package/catalog/frontmcp-development/examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md

@@ -0,0 +1,100 @@
+---
+name: tool-level-hooks-and-stage-replacement
+reference: create-plugin-hooks
+level: advanced
+description: 'Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock.'
+tags: [development, plugin-hooks, plugin, hooks, tool, level]
+features:
+  - "Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool"
+  - 'Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met'
+  - 'Using `this.mark()` to record lifecycle checkpoints during hook execution'
+  - 'Using `@Stage` with a `filter` predicate to replace the `execute` stage only for a specific tool name'
+  - 'The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)'
+---
+
+# Tool-Level Hooks and Stage Replacement
+
+Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock.
+
+## Code
+
+```typescript
+// src/tools/process-order.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const { Will, Did } = ToolHook;
+
+@Tool({
+  name: 'process_order',
+  description: 'Process a customer order',
+  inputSchema: {
+    orderId: z.string(),
+    amount: z.number(),
+  },
+  outputSchema: { status: z.string(), receipt: z.string() },
+})
+class ProcessOrderTool extends ToolContext {
+  @Will('execute', { priority: 10 })
+  async beforeExecute() {
+    const db = this.get(DB_TOKEN);
+    const order = await db.findOrder(this.input.orderId);
+    if (!order) {
+      this.fail(new Error(`Order ${this.input.orderId} not found`));
+    }
+    if (order.status === 'completed') {
+      this.fail(new Error('Order already processed'));
+    }
+    this.mark('validated');
+  }
+
+  async execute(input: { orderId: string; amount: number }) {
+    const payment = this.get(PAYMENT_TOKEN);
+    const receipt = await payment.charge(input.orderId, input.amount);
+    return { status: 'completed', receipt: receipt.id };
+  }
+
+  @Did('execute')
+  async afterExecute() {
+    const analytics = this.tryGet(ANALYTICS_TOKEN);
+    if (analytics) {
+      await analytics.track('order_processed', {
+        orderId: this.input.orderId,
+        amount: this.input.amount,
+      });
+    }
+  }
+}
+```
+
+```typescript
+// src/plugins/mock.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Stage } = ToolHook;
+
+@Plugin({ name: 'mock-plugin' })
+export class MockPlugin {
+  @Stage('execute', {
+    filter: (ctx) => ctx.toolName === 'fetch_weather',
+  })
+  mockWeather(ctx) {
+    return { content: [{ type: 'text', text: '72F and sunny' }] };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool
+- Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met
+- Using `this.mark()` to record lifecycle checkpoints during hook execution
+- Using `@Stage` with a `filter` predicate to replace the `execute` stage only for a specific tool name
+- The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)
+
+## Related
+
+- See `create-plugin-hooks` for the full list of hookable stages in the `call-tool` flow
+- See `decorators-guide` for the complete decorator hierarchy including `@Tool` and `@Plugin`

package/catalog/frontmcp-development/examples/create-prompt/basic-prompt.md

@@ -0,0 +1,72 @@
+---
+name: basic-prompt
+reference: create-prompt
+level: basic
+description: 'A simple prompt that generates a structured code review message from user-provided arguments.'
+tags: [development, prompt, create-prompt]
+features:
+  - 'Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`'
+  - 'Declaring prompt `arguments` with `required: true` for mandatory parameters'
+  - 'Framework validates required arguments before `execute()` runs'
+  - 'Registering the prompt in the `prompts` array of `@App`'
+---
+
+# Basic Prompt with Arguments
+
+A simple prompt that generates a structured code review message from user-provided arguments.
+
+## Code
+
+```typescript
+// src/apps/main/prompts/code-review.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+@Prompt({
+  name: 'code-review',
+  description: 'Generate a structured code review for the given code',
+  arguments: [
+    { name: 'code', description: 'The code to review', required: true },
+    { name: 'language', description: 'Programming language', required: false },
+  ],
+})
+class CodeReviewPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const language = args.language ?? 'unknown language';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Please review the following ${language} code. Focus on correctness, performance, and maintainability.\n\n\`\`\`${language}\n${args.code}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  prompts: [CodeReviewPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`
+- Declaring prompt `arguments` with `required: true` for mandatory parameters
+- Framework validates required arguments before `execute()` runs
+- Registering the prompt in the `prompts` array of `@App`
+
+## Related
+
+- See `create-prompt` for multi-turn conversations, resource embedding, and function-style builders