@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-prompt/dynamic-rag-prompt.md

@@ -0,0 +1,92 @@
+---
+name: dynamic-rag-prompt
+reference: create-prompt
+level: advanced
+description: 'A prompt that queries a knowledge base via DI to build context-aware messages at runtime.'
+tags: [development, prompt, dynamic, rag]
+features:
+  - 'Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts'
+  - 'Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access'
+  - 'Using `this.mark(stage)` for execution stage tracking in complex prompt generation'
+  - 'Building dynamic message content from external data sources at runtime'
+---
+
+# Dynamic RAG Prompt with Dependency Injection
+
+A prompt that queries a knowledge base via DI to build context-aware messages at runtime.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface KnowledgeBase {
+  search(query: string, limit: number): Promise<Array<{ title: string; content: string }>>;
+}
+
+export const KNOWLEDGE_BASE: Token<KnowledgeBase> = Symbol('knowledge-base');
+```
+
+```typescript
+// src/apps/main/prompts/rag-query.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+import { KNOWLEDGE_BASE } from '../tokens';
+
+@Prompt({
+  name: 'rag-query',
+  description: 'Answer a question using knowledge base context',
+  arguments: [
+    { name: 'question', description: 'The question to answer', required: true },
+    { name: 'maxSources', description: 'Maximum number of sources to include', required: false },
+  ],
+})
+class RagQueryPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    this.mark('search');
+    const kb = this.get(KNOWLEDGE_BASE);
+    const maxSources = parseInt(args.maxSources ?? '3', 10);
+    const sources = await kb.search(args.question, maxSources);
+
+    this.mark('compose');
+    const contextBlock = sources.map((s, i) => `### Source ${i + 1}: ${s.title}\n${s.content}`).join('\n\n');
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Answer the following question using only the provided sources. If the sources do not contain enough information, say so clearly.\n\n**Question:** ${args.question}\n\n---\n\n${contextBlock}`,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [KnowledgeBaseProvider],
+  prompts: [RagQueryPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts
+- Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access
+- Using `this.mark(stage)` for execution stage tracking in complex prompt generation
+- Building dynamic message content from external data sources at runtime
+
+## Related
+
+- See `create-prompt` for resource embedding, function-style builders, and error handling with `this.fail()`
+- See `create-provider` for implementing the `KnowledgeBaseProvider`

package/catalog/frontmcp-development/examples/create-prompt/multi-turn-debug-session.md

@@ -0,0 +1,86 @@
+---
+name: multi-turn-debug-session
+reference: create-prompt
+level: intermediate
+description: 'A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.'
+tags: [development, session, prompt, multi, turn, debug]
+features:
+  - 'Using `assistant` role messages to prime expected response patterns and guide LLM behavior'
+  - 'Alternating `user` and `assistant` roles to create a structured multi-turn conversation'
+  - 'Optional arguments that conditionally add content to the prompt'
+  - 'The assistant message establishes a systematic debugging approach the LLM will follow'
+---
+
+# Multi-Turn Debug Session Prompt
+
+A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.
+
+## Code
+
+```typescript
+// src/apps/main/prompts/debug-session.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+@Prompt({
+  name: 'debug-session',
+  description: 'Start a structured debugging session',
+  arguments: [
+    { name: 'error', description: 'The error message or stack trace', required: true },
+    { name: 'context', description: 'Additional context about what was happening', required: false },
+  ],
+})
+class DebugSessionPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const contextNote = args.context ? `\n\nAdditional context: ${args.context}` : '';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `I encountered an error and need help debugging it.\n\nError:\n\`\`\`\n${args.error}\n\`\`\`${contextNote}`,
+          },
+        },
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: "I'll help you debug this. Let me analyze the error systematically.\n\n**Step 1: Error Classification**\nLet me first identify what type of error this is and its likely root cause.\n\n",
+          },
+        },
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Please continue with your analysis and suggest specific fixes.',
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  prompts: [DebugSessionPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `assistant` role messages to prime expected response patterns and guide LLM behavior
+- Alternating `user` and `assistant` roles to create a structured multi-turn conversation
+- Optional arguments that conditionally add content to the prompt
+- The assistant message establishes a systematic debugging approach the LLM will follow
+
+## Related
+
+- See `create-prompt` for dynamic prompt generation with DI, resource embedding, and error handling

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

@@ -0,0 +1,113 @@
+---
+name: basic-database-provider
+reference: create-provider
+level: basic
+description: 'A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks.'
+tags: [development, database, provider]
+features:
+  - 'Defining a typed token with `Token<T>` using a `Symbol` for DI identification'
+  - 'Using `@Provider` decorator with `onInit()` for async startup and `onDestroy()` for cleanup'
+  - 'Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety'
+  - 'Registering the provider in the `providers` array so tools can resolve it'
+---
+
+# Basic Database Provider with Lifecycle
+
+A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface DatabaseService {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>;
+  close(): Promise<void>;
+}
+
+export const DB_TOKEN: Token<DatabaseService> = Symbol('DatabaseService');
+```
+
+```typescript
+// src/apps/main/providers/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import { createPool, Pool } from 'your-db-driver';
+
+@Provider({ name: 'DatabaseProvider' })
+class DatabaseProvider implements DatabaseService {
+  private pool!: Pool;
+
+  async onInit() {
+    this.pool = await createPool({
+      connectionString: process.env.DATABASE_URL,
+      max: 20,
+    });
+  }
+
+  async query(sql: string, params?: unknown[]) {
+    return this.pool.query(sql, params);
+  }
+
+  async close() {
+    await this.pool.end();
+  }
+
+  async onDestroy() {
+    await this.pool.end();
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/query-users.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DB_TOKEN } from '../tokens';
+
+@Tool({
+  name: 'query_users',
+  description: 'Query users from the database',
+  inputSchema: {
+    filter: z.string().optional(),
+    limit: z.number().default(10),
+  },
+  outputSchema: {
+    users: z.array(z.object({ id: z.string(), name: z.string(), email: z.string() })),
+  },
+})
+class QueryUsersTool extends ToolContext {
+  async execute(input: { filter?: string; limit: number }) {
+    const db = this.get(DB_TOKEN);
+    const users = await db.query('SELECT id, name, email FROM users WHERE name LIKE $1 LIMIT $2', [
+      `%${input.filter ?? ''}%`,
+      input.limit,
+    ]);
+    return { users };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [DatabaseProvider],
+  tools: [QueryUsersTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Defining a typed token with `Token<T>` using a `Symbol` for DI identification
+- Using `@Provider` decorator with `onInit()` for async startup and `onDestroy()` for cleanup
+- Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety
+- Registering the provider in the `providers` array so tools can resolve it
+
+## Related
+
+- See `create-provider` for configuration providers, HTTP API clients, and cache providers
+- See `create-tool` for more patterns using DI in tool execution

package/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md

@@ -0,0 +1,107 @@
+---
+name: config-and-api-providers
+reference: create-provider
+level: intermediate
+description: 'A configuration provider with readonly environment settings and an HTTP API client provider.'
+tags: [development, provider, config, api, providers]
+features:
+  - 'A configuration provider using `readonly` properties from environment variables (no lifecycle needed)'
+  - 'An API client provider using `onInit()` for async setup of credentials'
+  - 'Registering providers at `@FrontMcp` level for server-wide sharing across all apps'
+  - 'Separating token definitions from provider implementations for clean dependency boundaries'
+---
+
+# Configuration and API Client Providers
+
+A configuration provider with readonly environment settings and an HTTP API client provider.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface AppConfig {
+  apiBaseUrl: string;
+  maxRetries: number;
+  debug: boolean;
+}
+
+export const CONFIG_TOKEN: Token<AppConfig> = Symbol('AppConfig');
+
+export interface ApiClient {
+  get(path: string): Promise<unknown>;
+  post(path: string, body: unknown): Promise<unknown>;
+}
+
+export const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
+```
+
+```typescript
+// src/apps/main/providers/config.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { AppConfig } from '../tokens';
+
+@Provider({ name: 'ConfigProvider' })
+class ConfigProvider implements AppConfig {
+  readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
+  readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
+  readonly debug = process.env.DEBUG === 'true';
+}
+```
+
+```typescript
+// src/apps/main/providers/api-client.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { ApiClient } from '../tokens';
+
+@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!;
+  }
+
+  async get(path: string) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    return res.json();
+  }
+
+  async post(path: string, body: unknown) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return res.json();
+  }
+}
+```
+
+```typescript
+// src/index.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MainApp],
+  providers: [ConfigProvider, ApiClientProvider], // Server-scoped: shared across all apps
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- A configuration provider using `readonly` properties from environment variables (no lifecycle needed)
+- An API client provider using `onInit()` for async setup of credentials
+- Registering providers at `@FrontMcp` level for server-wide sharing across all apps
+- Separating token definitions from provider implementations for clean dependency boundaries
+
+## Related
+
+- See `create-provider` for cache providers, lifecycle details, and the `tryGet()` safe access pattern

package/catalog/frontmcp-development/examples/create-resource/basic-static-resource.md

@@ -0,0 +1,72 @@
+---
+name: basic-static-resource
+reference: create-resource
+level: basic
+description: 'A static resource that exposes application configuration at a fixed URI.'
+tags: [development, resource, static]
+features:
+  - 'Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)'
+  - 'Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`'
+  - 'Setting `mimeType` to indicate the content type of the resource'
+  - 'Registering the resource in the `resources` array of `@App`'
+---
+
+# Basic Static Resource
+
+A static resource that exposes application configuration at a fixed URI.
+
+## Code
+
+```typescript
+// src/apps/main/resources/app-config.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'app-config',
+  uri: 'config://app/settings',
+  description: 'Current application configuration',
+  mimeType: 'application/json',
+})
+class AppConfigResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const config = {
+      version: '2.1.0',
+      environment: 'production',
+      features: { darkMode: true, notifications: true },
+    };
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(config, null, 2),
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  resources: [AppConfigResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)
+- Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`
+- Setting `mimeType` to indicate the content type of the resource
+- Registering the resource in the `resources` array of `@App`
+
+## Related
+
+- See `create-resource` for resource templates, binary content, and function-style builders

package/catalog/frontmcp-development/examples/create-resource/binary-and-multi-content.md

@@ -0,0 +1,111 @@
+---
+name: binary-and-multi-content
+reference: create-resource
+level: advanced
+description: 'A resource serving binary blob data and a resource returning multiple content items.'
+tags: [development, cli, resource, binary, multi, content]
+features:
+  - 'Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets'
+  - 'Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly'
+  - 'Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)'
+  - 'Each content item has its own `uri`, `mimeType`, and `text` or `blob` field'
+---
+
+# Binary Content and Multi-Content Resource
+
+A resource serving binary blob data and a resource returning multiple content items.
+
+## Code
+
+```typescript
+// src/apps/main/resources/app-logo.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'app-logo',
+  uri: 'assets://logo.png',
+  description: 'Application logo image',
+  mimeType: 'image/png',
+})
+class AppLogoResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const { readFileBuffer } = await import('@frontmcp/utils');
+    const buffer = await readFileBuffer('/assets/logo.png');
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'image/png',
+          blob: buffer.toString('base64'),
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/resources/dashboard.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'dashboard-data',
+  uri: 'dashboard://overview',
+  description: 'Dashboard overview with metrics and chart data',
+  mimeType: 'application/json',
+})
+class DashboardResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const metrics = await this.loadMetrics();
+    const chartData = await this.loadChartData();
+
+    return {
+      contents: [
+        {
+          uri: `${uri}#metrics`,
+          mimeType: 'application/json',
+          text: JSON.stringify(metrics),
+        },
+        {
+          uri: `${uri}#charts`,
+          mimeType: 'application/json',
+          text: JSON.stringify(chartData),
+        },
+      ],
+    };
+  }
+
+  private async loadMetrics() {
+    return { users: 1500, revenue: 42000 };
+  }
+
+  private async loadChartData() {
+    return { labels: ['Jan', 'Feb'], values: [100, 200] };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  resources: [AppLogoResource, DashboardResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets
+- Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly
+- Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)
+- Each content item has its own `uri`, `mimeType`, and `text` or `blob` field
+
+## Related
+
+- See `create-resource` for function-style builders, simplified return values, and ESM/remote loading

package/catalog/frontmcp-development/examples/create-resource/parameterized-template.md

@@ -0,0 +1,84 @@
+---
+name: parameterized-template
+reference: create-resource
+level: intermediate
+description: 'A resource template with typed URI parameters and argument autocompletion.'
+tags: [development, resource, parameterized, template]
+features:
+  - 'Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders'
+  - 'Typing the `ResourceContext` generic parameter for compile-time parameter checking'
+  - 'Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion'
+  - 'Accessing DI providers via `this.get()` in both `execute()` and completer methods'
+---
+
+# Parameterized Resource Template
+
+A resource template with typed URI parameters and argument autocompletion.
+
+## Code
+
+```typescript
+// src/apps/main/resources/user-profile.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import type { ResourceCompletionResult } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+import type { Token } from '@frontmcp/di';
+
+interface UserService {
+  findById(id: string): Promise<{ id: string; name: string; email: string }>;
+  search(partial: string): Promise<Array<{ id: string; name: string }>>;
+}
+
+const USER_SERVICE: Token<UserService> = Symbol('UserService');
+
+@ResourceTemplate({
+  name: 'user-profile',
+  uriTemplate: 'users://{userId}/profile',
+  description: 'User profile by ID',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }): Promise<ReadResourceResult> {
+    const user = await this.get(USER_SERVICE).findById(params.userId);
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(user),
+        },
+      ],
+    };
+  }
+
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(USER_SERVICE).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [UserServiceProvider],
+  resources: [UserProfileResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders
+- Typing the `ResourceContext` generic parameter for compile-time parameter checking
+- Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion
+- Accessing DI providers via `this.get()` in both `execute()` and completer methods
+
+## Related
+
+- See `create-resource` for binary blob content, multiple content items, and function-style builders
+- See `create-provider` for implementing the `UserServiceProvider`