@frontmcp/skills 1.3.0 → 1.4.0

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

@@ -1,101 +0,0 @@
----
-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, z } from '@frontmcp/sdk';
-
-// 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, z } from '@frontmcp/sdk';
-
-// 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, z } from '@frontmcp/sdk';
-
-// 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

@@ -1,62 +0,0 @@
----
-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, z } from '@frontmcp/sdk';
-
-@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

@@ -1,101 +0,0 @@
----
-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, z } from '@frontmcp/sdk';
-
-// 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, z } from '@frontmcp/sdk';
-
-// 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/references/create-tool-annotations.md

@@ -1,48 +0,0 @@
----
-name: create-tool-annotations
-description: Reference for MCP tool annotation hints like readOnly, destructive, and idempotent
----
-
-# Tool Annotations Reference
-
-Annotations provide hints to MCP clients about tool behavior:
-
-```typescript
-@Tool({
-  name: 'my_tool',
-  inputSchema: { ... },
-  annotations: {
-    title: 'My Tool',              // Human-readable display name
-    readOnlyHint: true,            // Tool only reads data, no side effects
-    destructiveHint: false,        // Tool does NOT destroy/delete data
-    idempotentHint: true,          // Safe to call multiple times with same input
-    openWorldHint: false,          // Tool does NOT interact with external world
-  },
-})
-```
-
-## Fields
-
-| Field             | Type      | Default | Description                        |
-| ----------------- | --------- | ------- | ---------------------------------- |
-| `title`           | `string`  | —       | Human-friendly display name        |
-| `readOnlyHint`    | `boolean` | `false` | Tool only reads, no mutations      |
-| `destructiveHint` | `boolean` | `true`  | Tool may delete/overwrite data     |
-| `idempotentHint`  | `boolean` | `false` | Repeated calls produce same result |
-| `openWorldHint`   | `boolean` | `true`  | Tool may access external services  |
-
-## Usage Guidance
-
-- Set `readOnlyHint: true` for query/lookup tools
-- Set `destructiveHint: true` for delete/overwrite operations (triggers client warnings)
-- Set `idempotentHint: true` for safe-to-retry tools
-- Set `openWorldHint: false` for tools that only access local data
-
-## Examples
-
-| Example                                                                                     | Level        | Description                                                                                                                     |
-| ------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| [`destructive-delete-tool`](../examples/create-tool-annotations/destructive-delete-tool.md) | Intermediate | Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.                          |
-| [`readonly-query-tool`](../examples/create-tool-annotations/readonly-query-tool.md)         | Basic        | Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry. |
-
-> See all examples in [`examples/create-tool-annotations/`](../examples/create-tool-annotations/)

package/catalog/frontmcp-development/references/create-tool-output-schema-types.md

@@ -1,71 +0,0 @@
----
-name: create-tool-output-schema-types
-description: Reference for all supported outputSchema types including Zod shapes and JSON Schema
----
-
-# Output Schema Types Reference
-
-All supported `outputSchema` types for `@Tool`:
-
-## Zod Raw Shapes (Recommended)
-
-```typescript
-outputSchema: {
-  name: z.string(),
-  count: z.number(),
-  items: z.array(z.string()),
-}
-```
-
-Produces structured JSON output. **Best practice for CodeCall compatibility and data leak prevention.**
-
-## Zod Schemas
-
-```typescript
-outputSchema: z.object({ result: z.number() })
-outputSchema: z.array(z.string())
-outputSchema: z.union([z.string(), z.number()])
-outputSchema: z.discriminatedUnion('type', [...])
-```
-
-## Primitive Literals
-
-```typescript
-outputSchema: 'string'; // Returns plain text
-outputSchema: 'number'; // Returns a number
-outputSchema: 'boolean'; // Returns true/false
-outputSchema: 'date'; // Returns an ISO date string
-```
-
-## Media Types
-
-```typescript
-outputSchema: 'image'; // Returns base64 image data
-outputSchema: 'audio'; // Returns base64 audio data
-outputSchema: 'resource'; // Returns a resource content
-outputSchema: 'resource_link'; // Returns a resource URI link
-```
-
-## Multi-Content Arrays
-
-```typescript
-outputSchema: ['string', 'image']; // Returns text + image content
-```
-
-## No OutputSchema (Not Recommended)
-
-When `outputSchema` is omitted, the tool returns unvalidated content. This:
-
-- Risks leaking internal fields to the client
-- Prevents CodeCall from inferring return types
-- Loses compile-time type checking on `Out` generic
-
-## Examples
-
-| Example                                                                                                     | Level        | Description                                                                                                                                                    |
-| ----------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`primitive-and-media-outputs`](../examples/create-tool-output-schema-types/primitive-and-media-outputs.md) | Intermediate | Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.              |
-| [`zod-raw-shape-output`](../examples/create-tool-output-schema-types/zod-raw-shape-output.md)               | Basic        | Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.                                        |
-| [`zod-schema-advanced-output`](../examples/create-tool-output-schema-types/zod-schema-advanced-output.md)   | Advanced     | Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`. |
-
-> See all examples in [`examples/create-tool-output-schema-types/`](../examples/create-tool-output-schema-types/)