@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md

@@ -0,0 +1,84 @@
+---
+name: tool-with-di-and-errors
+reference: create-tool
+level: intermediate
+description: 'A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.'
+tags: [development, database, tool, di, errors]
+features:
+  - 'Defining a typed DI token with `Token<T>` and resolving it via `this.get()`'
+  - 'Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses'
+  - 'Letting infrastructure errors (database failures) propagate naturally to the framework'
+  - 'Registering both the provider and tool in the same `@App`'
+---
+
+# Tool with Dependency Injection and Error Handling
+
+A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface DatabaseService {
+  query(sql: string, params: unknown[]): Promise<unknown[]>;
+}
+
+export const DATABASE: Token<DatabaseService> = Symbol('database');
+```
+
+```typescript
+// src/apps/main/tools/delete-record.tool.ts
+import { Tool, ToolContext, ResourceNotFoundError } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DATABASE } from '../tokens';
+
+@Tool({
+  name: 'delete_record',
+  description: 'Delete a record by ID',
+  inputSchema: {
+    id: z.string().uuid().describe('Record UUID'),
+  },
+  outputSchema: {
+    message: z.string(),
+  },
+})
+class DeleteRecordTool extends ToolContext {
+  async execute(input: { id: string }): Promise<{ message: string }> {
+    const db = this.get(DATABASE);
+    const rows = await db.query('SELECT * FROM records WHERE id = $1', [input.id]);
+
+    if (rows.length === 0) {
+      this.fail(new ResourceNotFoundError(`Record ${input.id}`));
+    }
+
+    await db.query('DELETE FROM records WHERE id = $1', [input.id]);
+    return { message: `Record ${input.id} deleted successfully` };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [DatabaseProvider],
+  tools: [DeleteRecordTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Defining a typed DI token with `Token<T>` and resolving it via `this.get()`
+- Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses
+- Letting infrastructure errors (database failures) propagate naturally to the framework
+- Registering both the provider and tool in the same `@App`
+
+## Related
+
+- See `create-tool` for all context methods and error handling patterns
+- See `create-provider` for how to implement the `DatabaseProvider` class

package/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md

@@ -0,0 +1,93 @@
+---
+name: tool-with-rate-limiting-and-progress
+reference: create-tool
+level: advanced
+description: 'A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.'
+tags: [development, throttle, tool, rate, limiting, progress]
+features:
+  - 'Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection'
+  - 'Sending progress updates to the client with `this.respondProgress(value, total)`'
+  - 'Using `this.mark(stage)` for execution stage tracking and debugging'
+  - 'Sending log-level notifications with `this.notify(message, level)`'
+  - 'Setting tool `annotations` to communicate behavioral hints to clients'
+---
+
+# Tool with Rate Limiting, Progress, and Annotations
+
+A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.
+
+## Code
+
+```typescript
+// src/apps/main/tools/batch-process.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'batch_process',
+  description: 'Process a batch of items with progress tracking',
+  inputSchema: {
+    items: z.array(z.string()).min(1).describe('Items to process'),
+  },
+  outputSchema: {
+    processed: z.number(),
+    results: z.array(z.string()),
+  },
+  annotations: {
+    title: 'Batch Processor',
+    readOnlyHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  rateLimit: { maxRequests: 10, windowMs: 60_000 },
+  concurrency: { maxConcurrent: 2 },
+  timeout: { executeMs: 30_000 },
+})
+class BatchProcessTool extends ToolContext {
+  async execute(input: { items: string[] }): Promise<{ processed: number; results: string[] }> {
+    this.mark('validation');
+    if (input.items.some((item) => item.trim() === '')) {
+      this.fail(new Error('Items must not be empty strings'));
+    }
+
+    this.mark('processing');
+    const results: string[] = [];
+    for (let i = 0; i < input.items.length; i++) {
+      await this.respondProgress(i + 1, input.items.length);
+      const result = await this.processItem(input.items[i]);
+      results.push(result);
+    }
+
+    this.mark('complete');
+    await this.notify(`Processed ${results.length} items`, 'info');
+    return { processed: results.length, results };
+  }
+
+  private async processItem(item: string): Promise<string> {
+    return `processed:${item}`;
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  tools: [BatchProcessTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection
+- Sending progress updates to the client with `this.respondProgress(value, total)`
+- Using `this.mark(stage)` for execution stage tracking and debugging
+- Sending log-level notifications with `this.notify(message, level)`
+- Setting tool `annotations` to communicate behavioral hints to clients
+
+## Related
+
+- See `create-tool` for all annotation fields, elicitation, and auth provider patterns

package/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md

@@ -0,0 +1,94 @@
+---
+name: destructive-delete-tool
+reference: create-tool-annotations
+level: intermediate
+description: 'Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.'
+tags: [development, elicitation, tool, annotations, destructive, delete]
+features:
+  - 'Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings'
+  - 'Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome'
+  - 'Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service'
+  - 'Setting `idempotentHint: false` on the email tool because each call sends a new email'
+  - 'How different annotation combinations express different behavioral contracts'
+---
+
+# Destructive Delete Tool with Annotations
+
+Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.
+
+## Code
+
+```typescript
+// src/tools/delete-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_user',
+  description: 'Permanently delete a user account and all associated data',
+  inputSchema: {
+    userId: z.string().describe('ID of the user to delete'),
+    confirm: z.boolean().describe('Must be true to confirm deletion'),
+  },
+  annotations: {
+    title: 'Delete User Account',
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+})
+class DeleteUserTool extends ToolContext {
+  async execute(input: { userId: string; confirm: boolean }) {
+    if (!input.confirm) {
+      return { deleted: false, reason: 'Confirmation required' };
+    }
+    const db = this.get(DatabaseToken);
+    await db.deleteUser(input.userId);
+    return { deleted: true, userId: input.userId };
+  }
+}
+```
+
+```typescript
+// src/tools/send-email.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'send_email',
+  description: 'Send an email to a recipient via external SMTP service',
+  inputSchema: {
+    to: z.string().email().describe('Recipient email address'),
+    subject: z.string().describe('Email subject'),
+    body: z.string().describe('Email body text'),
+  },
+  annotations: {
+    title: 'Send Email',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+})
+class SendEmailTool extends ToolContext {
+  async execute(input: { to: string; subject: string; body: string }) {
+    const mailer = this.get(MailerToken);
+    const result = await mailer.send(input.to, input.subject, input.body);
+    return { sent: true, messageId: result.id };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings
+- Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome
+- Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service
+- Setting `idempotentHint: false` on the email tool because each call sends a new email
+- How different annotation combinations express different behavioral contracts
+
+## Related
+
+- See `create-tool-annotations` for all annotation fields and their default values
+- See `decorators-guide` for the full `@Tool` decorator field reference

package/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md

@@ -0,0 +1,60 @@
+---
+name: readonly-query-tool
+reference: create-tool-annotations
+level: basic
+description: 'Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.'
+tags: [development, database, local, tool, annotations, readonly]
+features:
+  - 'Setting `readOnlyHint: true` to indicate the tool performs no mutations'
+  - 'Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten'
+  - 'Setting `idempotentHint: true` because repeated calls with the same input produce the same result'
+  - 'Setting `openWorldHint: false` because the tool only accesses local database data'
+  - 'Using `title` to provide a human-friendly display name for MCP client UIs'
+---
+
+# Read-Only Query Tool with Annotations
+
+Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.
+
+## 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),
+  },
+  annotations: {
+    title: 'Search Users',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+})
+class SearchUsersTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const db = this.get(DatabaseToken);
+    const users = await db.searchUsers(input.query, input.limit);
+    return { users };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Setting `readOnlyHint: true` to indicate the tool performs no mutations
+- Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten
+- Setting `idempotentHint: true` because repeated calls with the same input produce the same result
+- Setting `openWorldHint: false` because the tool only accesses local database data
+- Using `title` to provide a human-friendly display name for MCP client UIs
+
+## Related
+
+- See `create-tool-annotations` for the full fields reference and default values

package/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md

@@ -0,0 +1,104 @@
+---
+name: primitive-and-media-outputs
+reference: create-tool-output-schema-types
+level: intermediate
+description: 'Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.'
+tags: [development, output-schema, tool, output, schema, types]
+features:
+  - "Using `'string'` literal to return plain text output"
+  - "Using `'image'` literal to return base64 image data"
+  - "Using `['string', 'image']` array to return multi-content (text plus image) in a single response"
+  - "Other available primitives: `'number'`, `'boolean'`, `'date'`"
+  - "Other available media types: `'audio'`, `'resource'`, `'resource_link'`"
+---
+
+# Primitive Literal and Media Type Output Schemas
+
+Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.
+
+## Code
+
+```typescript
+// src/tools/summarize.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Primitive literal: returns plain text
+@Tool({
+  name: 'summarize_text',
+  description: 'Summarize a long text into a short paragraph',
+  inputSchema: {
+    text: z.string().describe('The text to summarize'),
+  },
+  outputSchema: 'string',
+})
+class SummarizeTextTool extends ToolContext {
+  async execute(input: { text: string }) {
+    const summary = await this.get(LlmService).summarize(input.text);
+    return summary;
+  }
+}
+```
+
+```typescript
+// src/tools/generate-chart.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Media type: returns base64 image data
+@Tool({
+  name: 'generate_chart',
+  description: 'Generate a chart image from data points',
+  inputSchema: {
+    data: z.array(z.object({ label: z.string(), value: z.number() })),
+    chartType: z.enum(['bar', 'line', 'pie']),
+  },
+  outputSchema: 'image',
+})
+class GenerateChartTool extends ToolContext {
+  async execute(input: { data: Array<{ label: string; value: number }>; chartType: string }) {
+    const chartService = this.get(ChartService);
+    const imageBase64 = await chartService.render(input.data, input.chartType);
+    return imageBase64;
+  }
+}
+```
+
+```typescript
+// src/tools/analyze-document.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Multi-content array: returns text + image
+@Tool({
+  name: 'analyze_document',
+  description: 'Analyze a document and return summary with visual highlights',
+  inputSchema: {
+    documentId: z.string().describe('Document ID to analyze'),
+  },
+  outputSchema: ['string', 'image'],
+})
+class AnalyzeDocumentTool extends ToolContext {
+  async execute(input: { documentId: string }) {
+    const doc = this.get(DocumentService);
+    const analysis = await doc.analyze(input.documentId);
+    return {
+      text: analysis.summary,
+      image: analysis.highlightImageBase64,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `'string'` literal to return plain text output
+- Using `'image'` literal to return base64 image data
+- Using `['string', 'image']` array to return multi-content (text plus image) in a single response
+- Other available primitives: `'number'`, `'boolean'`, `'date'`
+- Other available media types: `'audio'`, `'resource'`, `'resource_link'`
+
+## Related
+
+- See `create-tool-output-schema-types` for the complete list of supported output schema types
+- See `decorators-guide` for the full `@Tool` decorator field reference

package/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md

@@ -0,0 +1,63 @@
+---
+name: zod-raw-shape-output
+reference: create-tool-output-schema-types
+level: basic
+description: 'Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.'
+tags: [development, codecall, output-schema, tool, output, schema]
+features:
+  - 'Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output'
+  - 'The output is validated at runtime against the schema before being returned to the client'
+  - 'This is the recommended pattern for CodeCall compatibility and data leak prevention'
+  - 'The `execute()` return type is automatically inferred from the output schema'
+---
+
+# Zod Raw Shape Output Schema
+
+Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.
+
+## Code
+
+```typescript
+// src/tools/get-user-profile.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_user_profile',
+  description: 'Retrieve a user profile by ID',
+  inputSchema: {
+    userId: z.string().describe('The user ID to look up'),
+  },
+  outputSchema: {
+    name: z.string(),
+    email: z.string().email(),
+    age: z.number(),
+    roles: z.array(z.string()),
+    active: z.boolean(),
+  },
+})
+class GetUserProfileTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    const db = this.get(DatabaseToken);
+    const user = await db.findUser(input.userId);
+    return {
+      name: user.name,
+      email: user.email,
+      age: user.age,
+      roles: user.roles,
+      active: user.active,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output
+- The output is validated at runtime against the schema before being returned to the client
+- This is the recommended pattern for CodeCall compatibility and data leak prevention
+- The `execute()` return type is automatically inferred from the output schema
+
+## Related
+
+- See `create-tool-output-schema-types` for all supported output schema formats

package/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md

@@ -0,0 +1,103 @@
+---
+name: zod-schema-advanced-output
+reference: create-tool-output-schema-types
+level: advanced
+description: 'Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.'
+tags: [development, output-schema, tool, output, schema, types]
+features:
+  - 'Using `z.object()` for structured output with nested arrays and nullable fields'
+  - 'Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field'
+  - 'Full Zod schemas provide the same validation as raw shapes but support more complex types'
+  - 'Output is validated at runtime -- mismatched return values trigger validation errors'
+---
+
+# Advanced Zod Schema Output Types
+
+Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.
+
+## Code
+
+```typescript
+// src/tools/list-products.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// z.object() -- structured object output
+@Tool({
+  name: 'get_order_status',
+  description: 'Get the current status of an order',
+  inputSchema: {
+    orderId: z.string(),
+  },
+  outputSchema: z.object({
+    orderId: z.string(),
+    status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+    estimatedDelivery: z.string().nullable(),
+    items: z.array(
+      z.object({
+        name: z.string(),
+        quantity: z.number(),
+      }),
+    ),
+  }),
+})
+class GetOrderStatusTool extends ToolContext {
+  async execute(input: { orderId: string }) {
+    const order = await this.get(OrderService).getStatus(input.orderId);
+    return {
+      orderId: order.id,
+      status: order.status,
+      estimatedDelivery: order.estimatedDelivery,
+      items: order.items.map((i) => ({ name: i.name, quantity: i.quantity })),
+    };
+  }
+}
+```
+
+```typescript
+// src/tools/search-catalog.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// z.discriminatedUnion() -- different shapes based on a type field
+const ProductResult = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('physical'),
+    name: z.string(),
+    weight: z.number(),
+    dimensions: z.object({ width: z.number(), height: z.number(), depth: z.number() }),
+  }),
+  z.object({
+    type: z.literal('digital'),
+    name: z.string(),
+    downloadUrl: z.string(),
+    fileSizeMb: z.number(),
+  }),
+]);
+
+@Tool({
+  name: 'get_product',
+  description: 'Retrieve product details by ID',
+  inputSchema: {
+    productId: z.string(),
+  },
+  outputSchema: ProductResult,
+})
+class GetProductTool extends ToolContext {
+  async execute(input: { productId: string }) {
+    const product = await this.get(CatalogService).findById(input.productId);
+    return product;
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `z.object()` for structured output with nested arrays and nullable fields
+- Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field
+- Full Zod schemas provide the same validation as raw shapes but support more complex types
+- Output is validated at runtime -- mismatched return values trigger validation errors
+
+## Related
+
+- See `create-tool-output-schema-types` for all supported output schema formats including primitives and media types

package/catalog/frontmcp-development/examples/create-workflow/basic-deploy-pipeline.md

@@ -0,0 +1,91 @@
+---
+name: basic-deploy-pipeline
+reference: create-workflow
+level: basic
+description: 'A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.'
+tags: [development, workflow, pipeline]
+features:
+  - 'Defining a workflow with `@Workflow` decorator and sequential `steps`'
+  - 'Using `dependsOn` to establish step execution order'
+  - 'Passing dynamic input from a previous step using the callback form `(steps) => ({...})`'
+  - 'Registering both jobs and workflows in `@App` with jobs enabled'
+---
+
+# Basic Deploy Pipeline Workflow
+
+A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.
+
+## Code
+
+```typescript
+// src/workflows/deploy-pipeline.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'deploy-pipeline',
+  description: 'Build, test, and deploy a service',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production', optimize: true },
+    },
+    {
+      id: 'test',
+      jobName: 'run-tests',
+      input: { suite: 'all', coverage: true },
+      dependsOn: ['build'],
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'production',
+      }),
+      dependsOn: ['test'],
+    },
+  ],
+})
+class DeployPipeline {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'pipeline-app',
+  jobs: [BuildProjectJob, RunTestsJob, DeployToEnvJob],
+  workflows: [DeployPipeline],
+})
+class PipelineApp {}
+
+@FrontMcp({
+  info: { name: 'pipeline-server', version: '1.0.0' },
+  apps: [PipelineApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:jobs:',
+      },
+    },
+  },
+})
+class PipelineServer {}
+```
+
+## What This Demonstrates
+
+- Defining a workflow with `@Workflow` decorator and sequential `steps`
+- Using `dependsOn` to establish step execution order
+- Passing dynamic input from a previous step using the callback form `(steps) => ({...})`
+- Registering both jobs and workflows in `@App` with jobs enabled
+
+## Related
+
+- See `create-workflow` for the full API reference including triggers, conditions, and error handling