@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-workflow/parallel-validation-pipeline.md

@@ -0,0 +1,90 @@
+---
+name: parallel-validation-pipeline
+reference: create-workflow
+level: intermediate
+description: 'A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.'
+tags: [development, workflow, parallel, validation, pipeline]
+features:
+  - 'Running steps in parallel by omitting `dependsOn` (no mutual dependencies)'
+  - 'Using `maxConcurrency` to limit how many steps run at the same time'
+  - 'Conditional steps with `condition` that check `.state` of previous steps'
+  - 'Fan-out/fan-in pattern: parallel validation steps converge into a merge step'
+  - 'Branching: separate success and failure notification paths'
+---
+
+# Parallel Validation Pipeline with Conditional Steps
+
+A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.
+
+## Code
+
+```typescript
+// src/workflows/data-validation.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'data-validation-pipeline',
+  description: 'Validate data from multiple sources in parallel, then merge',
+  maxConcurrency: 3,
+  steps: [
+    // These three steps have no dependencies -- they run in parallel
+    {
+      id: 'validate-users',
+      jobName: 'validate-dataset',
+      input: { dataset: 'users', rules: ['no-nulls', 'email-format'] },
+    },
+    {
+      id: 'validate-orders',
+      jobName: 'validate-dataset',
+      input: { dataset: 'orders', rules: ['no-nulls', 'positive-amounts'] },
+    },
+    {
+      id: 'validate-products',
+      jobName: 'validate-dataset',
+      input: { dataset: 'products', rules: ['no-nulls', 'unique-sku'] },
+    },
+    // This step depends on all three -- runs after all complete
+    {
+      id: 'merge-results',
+      jobName: 'merge-validations',
+      dependsOn: ['validate-users', 'validate-orders', 'validate-products'],
+      condition: (steps) =>
+        steps.get('validate-users').state === 'completed' &&
+        steps.get('validate-orders').state === 'completed' &&
+        steps.get('validate-products').state === 'completed',
+      input: (steps) => ({
+        userReport: steps.get('validate-users').outputs,
+        orderReport: steps.get('validate-orders').outputs,
+        productReport: steps.get('validate-products').outputs,
+      }),
+    },
+    // Notify on any failure
+    {
+      id: 'notify-failure',
+      jobName: 'send-notification',
+      dependsOn: ['validate-users', 'validate-orders', 'validate-products'],
+      condition: (steps) =>
+        steps.get('validate-users').state === 'failed' ||
+        steps.get('validate-orders').state === 'failed' ||
+        steps.get('validate-products').state === 'failed',
+      input: {
+        channel: '#alerts',
+        message: 'Data validation pipeline encountered failures',
+      },
+    },
+  ],
+})
+class DataValidationPipeline {}
+```
+
+## What This Demonstrates
+
+- Running steps in parallel by omitting `dependsOn` (no mutual dependencies)
+- Using `maxConcurrency` to limit how many steps run at the same time
+- Conditional steps with `condition` that check `.state` of previous steps
+- Fan-out/fan-in pattern: parallel validation steps converge into a merge step
+- Branching: separate success and failure notification paths
+
+## Related
+
+- See `create-workflow` for the full DAG execution model, diamond dependencies, and `continueOnError`

package/catalog/frontmcp-development/examples/create-workflow/webhook-triggered-workflow.md

@@ -0,0 +1,136 @@
+---
+name: webhook-triggered-workflow
+reference: create-workflow
+level: advanced
+description: 'A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.'
+tags: [development, workflow, webhook, triggered]
+features:
+  - "Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`"
+  - 'Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures'
+  - 'Conditional branching: separate success and failure notification steps based on prior step state'
+  - 'Workflow-level `permissions` for access control'
+  - 'The `workflow()` function builder as a lighter alternative to the class pattern'
+---
+
+# Webhook-Triggered Workflow with Error Resilience
+
+A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.
+
+## Code
+
+```typescript
+// src/workflows/github-deploy.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'github-deploy',
+  description: 'Deploy on GitHub push events',
+  trigger: 'webhook',
+  webhook: {
+    path: '/webhooks/github-deploy',
+    secret: process.env.WEBHOOK_SECRET,
+    methods: ['POST'],
+  },
+  timeout: 900000, // 15 minutes
+  maxConcurrency: 3,
+  permissions: {
+    actions: ['create', 'read', 'execute', 'list'],
+    roles: ['admin', 'ci-bot'],
+  },
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { branch: 'main' },
+    },
+    {
+      id: 'lint',
+      jobName: 'run-linter',
+      dependsOn: ['build'],
+      continueOnError: true, // lint failures are non-blocking
+      input: (steps) => ({
+        workDir: steps.get('build').outputs.workDir,
+      }),
+    },
+    {
+      id: 'test',
+      jobName: 'run-unit-tests',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        workDir: steps.get('build').outputs.workDir,
+        coverage: true,
+      }),
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-artifact',
+      dependsOn: ['lint', 'test'],
+      condition: (steps) => steps.get('test').state === 'completed' && steps.get('test').outputs.passed === true,
+      input: (steps) => ({
+        artifactUrl: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+    {
+      id: 'notify-success',
+      jobName: 'notify-team',
+      dependsOn: ['deploy'],
+      condition: (steps) => steps.get('deploy').state === 'completed',
+      input: (steps) => ({
+        channel: '#deployments',
+        message: `Deployed to ${steps.get('deploy').outputs.url}`,
+      }),
+    },
+    {
+      id: 'notify-failure',
+      jobName: 'notify-team',
+      dependsOn: ['test'],
+      condition: (steps) => steps.get('test').state === 'failed',
+      input: {
+        channel: '#alerts',
+        message: 'CI pipeline failed -- check test results',
+      },
+    },
+  ],
+})
+class GithubDeploy {}
+```
+
+```typescript
+// src/workflows/quick-deploy.workflow.ts
+import { workflow } from '@frontmcp/sdk';
+
+// Function-style workflow for simpler cases
+const QuickDeploy = workflow({
+  name: 'quick-deploy',
+  description: 'Simplified deployment workflow',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production' },
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+  ],
+});
+```
+
+## What This Demonstrates
+
+- Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`
+- Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures
+- Conditional branching: separate success and failure notification steps based on prior step state
+- Workflow-level `permissions` for access control
+- The `workflow()` function builder as a lighter alternative to the class pattern
+
+## Related
+
+- See `create-workflow` for the full trigger types (manual, webhook, event), error handling, and registration

package/catalog/frontmcp-development/examples/decorators-guide/agent-skill-job-workflow.md

@@ -0,0 +1,145 @@
+---
+name: agent-skill-job-workflow
+reference: decorators-guide
+level: advanced
+description: 'Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.'
+tags: [development, decorators, agent, skill, job, workflow]
+features:
+  - '`@Agent` with LLM config, input schema, and delegated tools for autonomous task execution'
+  - '`@Skill` with inline instructions and tool references for reusable knowledge packages'
+  - '`@Job` with retry policy, timeout, and typed input/output for background processing'
+  - '`@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution'
+  - 'Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`'
+  - 'All advanced decorators registered in a single `@App` module'
+---
+
+# Agents, Skills, Jobs, and Workflows
+
+Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.
+
+## Code
+
+```typescript
+// src/agents/research.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'research_agent',
+  description: 'Researches topics and produces summaries',
+  llm: { model: 'claude-sonnet-4-20250514', provider: 'anthropic' },
+  inputSchema: {
+    topic: z.string().describe('Topic to research'),
+  },
+  tools: [WebSearchTool, SummarizeTool],
+})
+class ResearchAgent extends AgentContext {
+  async execute(input: { topic: string }) {
+    return this.run(`Research and summarize: ${input.topic}`);
+  }
+}
+```
+
+```typescript
+// src/skills/code-migration.skill.ts
+import { Skill } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'code_migration',
+  description: 'Guides migration of code between frameworks',
+  instructions: `
+    1. Analyze the source codebase structure
+    2. Identify framework-specific patterns
+    3. Generate migration plan
+    4. Apply transformations using the provided tools
+  `,
+  tools: [AnalyzeTool, TransformTool, ValidateTool],
+  visibility: 'both',
+})
+class CodeMigrationSkill {}
+```
+
+```typescript
+// src/jobs/sync-data.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'sync_data',
+  description: 'Synchronize data from external sources',
+  inputSchema: z.object({ source: z.string().describe('Data source to sync') }),
+  outputSchema: z.object({ synced: z.number() }),
+  retry: { maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2, maxBackoffMs: 60_000 },
+  timeout: 300_000,
+})
+class SyncDataJob extends JobContext {
+  async execute(input: { source: string }) {
+    const count = await this.get(SyncService).runFullSync(input.source);
+    return { synced: count };
+  }
+}
+```
+
+```typescript
+// src/workflows/deploy-pipeline.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'deploy_pipeline',
+  description: 'Full deployment pipeline',
+  trigger: 'webhook',
+  webhookConfig: {
+    path: '/hooks/deploy',
+    secret: process.env.WEBHOOK_SECRET!,
+    methods: ['POST'],
+  },
+  timeout: 600_000,
+  steps: [
+    { id: 'build', jobName: 'build_app', input: { env: 'production' } },
+    { id: 'test', jobName: 'run_tests', dependsOn: ['build'] },
+    {
+      id: 'deploy',
+      jobName: 'deploy_app',
+      dependsOn: ['test'],
+      condition: (steps) => steps.test.success,
+    },
+  ],
+})
+class DeployPipeline {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'platform',
+  agents: [ResearchAgent],
+  skills: [CodeMigrationSkill],
+  jobs: [SyncDataJob],
+  workflows: [DeployPipeline],
+})
+class PlatformApp {}
+
+@FrontMcp({
+  info: { name: 'advanced-server', version: '1.0.0' },
+  apps: [PlatformApp],
+  jobs: { enabled: true },
+  skillsConfig: { enabled: true },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- `@Agent` with LLM config, input schema, and delegated tools for autonomous task execution
+- `@Skill` with inline instructions and tool references for reusable knowledge packages
+- `@Job` with retry policy, timeout, and typed input/output for background processing
+- `@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution
+- Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`
+- All advanced decorators registered in a single `@App` module
+
+## Related
+
+- See `decorators-guide` for the complete decorator hierarchy and all field definitions
+- See `create-plugin-hooks` for attaching lifecycle hooks to any flow

package/catalog/frontmcp-development/examples/decorators-guide/basic-server-with-app-and-tools.md

@@ -0,0 +1,124 @@
+---
+name: basic-server-with-app-and-tools
+reference: decorators-guide
+level: basic
+description: 'Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.'
+tags: [development, decorators, app, tools]
+features:
+  - 'The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy'
+  - 'Tool classes extend `ToolContext` and implement `execute()`'
+  - 'Resource classes extend `ResourceContext` and implement `read()`'
+  - 'Prompt classes extend `PromptContext` and implement `execute()`'
+  - 'Apps group related tools, resources, and prompts into logical modules'
+---
+
+# Basic Server with @FrontMcp, @App, and @Tool
+
+Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.
+
+## Code
+
+```typescript
+// src/tools/search-users.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search_users',
+  description: 'Search for users by name or email',
+  inputSchema: {
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10),
+  },
+})
+class SearchUsersTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const users = await this.get(UserService).search(input.query, input.limit);
+    return { users };
+  }
+}
+```
+
+```typescript
+// src/resources/app-config.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  name: 'app_config',
+  uri: 'config://app/settings',
+  description: 'Current application settings',
+  mimeType: 'application/json',
+})
+class AppConfigResource extends ResourceContext {
+  async read() {
+    const config = await this.get(ConfigService).getAll();
+    return { contents: [{ uri: this.uri, text: JSON.stringify(config) }] };
+  }
+}
+```
+
+```typescript
+// src/prompts/code-review.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+
+@Prompt({
+  name: 'code_review',
+  description: 'Generate a code review for the given code',
+  arguments: [
+    { name: 'code', description: 'The code to review', required: true },
+    { name: 'language', description: 'Programming language' },
+  ],
+})
+class CodeReviewPrompt extends PromptContext {
+  async execute(args: { code: string; language?: string }) {
+    return {
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `Review this ${args.language ?? ''} code:\n\n${args.code}`,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { SearchUsersTool } from './tools/search-users.tool';
+import { AppConfigResource } from './resources/app-config.resource';
+import { CodeReviewPrompt } from './prompts/code-review.prompt';
+
+@App({
+  name: 'analytics',
+  tools: [SearchUsersTool],
+  resources: [AppConfigResource],
+  prompts: [CodeReviewPrompt],
+})
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [AnalyticsApp],
+  transport: 'modern',
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy
+- Tool classes extend `ToolContext` and implement `execute()`
+- Resource classes extend `ResourceContext` and implement `read()`
+- Prompt classes extend `PromptContext` and implement `execute()`
+- Apps group related tools, resources, and prompts into logical modules
+
+## Related
+
+- See `decorators-guide` for the full decorator reference including all field options
+- See `create-tool` for step-by-step tool creation patterns

package/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md

@@ -0,0 +1,149 @@
+---
+name: multi-app-with-plugins-and-providers
+reference: decorators-guide
+level: intermediate
+description: 'Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.'
+tags: [development, database, multi-app, decorators, multi, app]
+features:
+  - 'Organizing a server into multiple `@App` modules (`analytics` and `admin`)'
+  - 'Using `@Provider` with `useFactory` to register a database client for dependency injection'
+  - 'Accessing injected dependencies via `this.get(DatabaseToken)` in tools and resources'
+  - 'Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources'
+  - 'Registering a `@Plugin` at the server level so it applies across all apps'
+  - 'Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`'
+---
+
+# Multi-App Server with Plugins and Providers
+
+Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.
+
+## Code
+
+```typescript
+// src/providers/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+export const DatabaseToken = Symbol('Database');
+
+@Provider({
+  name: 'database',
+  provide: DatabaseToken,
+  useFactory: () => new DatabaseClient(process.env.DB_URL),
+})
+class DatabaseProvider {}
+```
+
+```typescript
+// src/plugins/audit.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'audit-log',
+  providers: [AuditLogProvider],
+  contextExtensions: [installAuditExtension],
+})
+class AuditPlugin {}
+```
+
+```typescript
+// src/tools/query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'run_query',
+  description: 'Run an analytics query',
+  inputSchema: {
+    sql: z.string().describe('SQL query to execute'),
+  },
+})
+class QueryTool extends ToolContext {
+  async execute(input: { sql: string }) {
+    const db = this.get(DatabaseToken);
+    const results = await db.query(input.sql);
+    return { rows: results };
+  }
+}
+```
+
+```typescript
+// src/tools/report.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'generate_report',
+  description: 'Generate a formatted report from a dataset',
+  inputSchema: {
+    datasetId: z.string(),
+    format: z.enum(['csv', 'json', 'pdf']),
+  },
+})
+class ReportTool extends ToolContext {
+  async execute(input: { datasetId: string; format: string }) {
+    const db = this.get(DatabaseToken);
+    const data = await db.getDataset(input.datasetId);
+    return { report: `Report in ${input.format} format`, rows: data.length };
+  }
+}
+```
+
+```typescript
+// src/resources/dashboard.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+
+@ResourceTemplate({
+  name: 'dashboard',
+  uriTemplate: 'dashboards://{dashboardId}',
+  description: 'Dashboard data by ID',
+  mimeType: 'application/json',
+})
+class DashboardResource extends ResourceContext {
+  async read(uri: string, params: { dashboardId: string }) {
+    const db = this.get(DatabaseToken);
+    const data = await db.getDashboard(params.dashboardId);
+    return { contents: [{ uri, text: JSON.stringify(data) }] };
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'analytics',
+  tools: [QueryTool, ReportTool],
+  resources: [DashboardResource],
+  providers: [DatabaseProvider],
+})
+class AnalyticsApp {}
+
+@App({
+  name: 'admin',
+  tools: [ManageUsersTool],
+})
+class AdminApp {}
+
+@FrontMcp({
+  info: { name: 'multi-app-server', version: '1.0.0' },
+  apps: [AnalyticsApp, AdminApp],
+  plugins: [AuditPlugin],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Organizing a server into multiple `@App` modules (`analytics` and `admin`)
+- Using `@Provider` with `useFactory` to register a database client for dependency injection
+- Accessing injected dependencies via `this.get(DatabaseToken)` in tools and resources
+- Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources
+- Registering a `@Plugin` at the server level so it applies across all apps
+- Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`
+
+## Related
+
+- See `decorators-guide` for the complete list of all decorator fields and their types
+- See `create-plugin-hooks` for adding lifecycle hooks to plugins