@frontmcp/skills 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/skills",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Curated skills catalog for FrontMCP projects",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",

package/src/manifest.d.ts

@@ -12,7 +12,21 @@ export type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';
 /**
  * Skill categories for organizing the catalog.
  */
-export type SkillCategory = 'setup' | 'deployment' | 'development' | 'config' | 'testing' | 'guides' | 'production' | 'extensibility' | 'observability';
+export type SkillCategory = 'setup' | 'deployment' | 'development' | 'development/create' | 'config' | 'testing' | 'guides' | 'production' | 'extensibility' | 'observability';
+/**
+ * Catalog layouts the validator understands.
+ *
+ * - `router` (default): the legacy shape used by skills like `frontmcp-development`
+ *   — a Scenario Routing Table SKILL.md plus `references/<topic>.md` files with
+ *   examples grouped in `examples/<topic>/<example>.md` subdirectories.
+ *
+ * - `component`: the new per-thing layout used by skills like `create-tool`
+ *   — flat `examples/<example>.md` (no per-reference grouping), an optional
+ *   `rules/` directory with short DO/DON'T files, and rich SKILL.md frontmatter
+ *   designed for Claude Code's auto-trigger heuristics (explicit `triggers:`,
+ *   `paths:` globs, `when_to_use`).
+ */
+export type SkillLayout = 'router' | 'component';
 /**
  * Bundle membership for curated scaffold presets.
  */
@@ -67,6 +81,38 @@ export interface SkillReferenceEntry {
     /** Example files for this reference, located in examples/<reference-name>/ */
     examples?: SkillReferenceExampleEntry[];
 }
+/**
+ * Top-level example entry used by `layout: 'component'` skills, where
+ * examples live flat under `examples/<example>.md` (not grouped under a
+ * parent reference). Shape mirrors {@link SkillReferenceExampleEntry} so
+ * downstream consumers can use a uniform metadata type.
+ */
+export interface SkillComponentExampleEntry {
+    /** Example name — matches filename without extension */
+    name: string;
+    /** Short description of what the example demonstrates */
+    description: string;
+    /** Complexity level */
+    level: SkillExampleLevel;
+    /** Searchable tags for the example */
+    tags: string[];
+    /** Concrete APIs or patterns the example demonstrates */
+    features: string[];
+}
+/**
+ * Top-level rule entry used by `layout: 'component'` skills. Rules are short
+ * DO / DON'T constraint files under `rules/<rule>.md`. The body explains the
+ * rule, gives good / bad examples, and (where possible) ends with a grep-based
+ * verification snippet.
+ */
+export interface SkillComponentRuleEntry {
+    /** Rule name — matches filename without extension */
+    name: string;
+    /** One-sentence statement of the rule */
+    constraint: string;
+    /** Enforcement strength — `required` for must-follow, `recommended` for nudges */
+    severity?: 'required' | 'recommended';
+}
 /**
  * A single entry in the skills catalog manifest.
  *
@@ -88,6 +134,29 @@ export interface SkillCatalogEntry {
     hasResources: boolean;
     /** Resolved reference metadata from references/ directory */
     references?: SkillReferenceEntry[];
+    /**
+     * Catalog layout — see {@link SkillLayout}. Defaults to `'router'` when
+     * absent for backward compatibility with the legacy frontmcp-* router
+     * skills.
+     */
+    layout?: SkillLayout;
+    /**
+     * Top-level example entries — only populated when `layout === 'component'`.
+     * Router-layout skills group examples under `references[].examples`
+     * instead.
+     */
+    examples?: SkillComponentExampleEntry[];
+    /**
+     * Top-level rule entries — only populated when `layout === 'component'`.
+     * Each rule corresponds to a file in `rules/<name>.md`.
+     */
+    rules?: SkillComponentRuleEntry[];
+    /**
+     * Priority hint surfaced to Claude Code's auto-discovery. Higher number =
+     * earlier in the ranking. Mirrors `metadata.priority` in SKILL.md
+     * frontmatter.
+     */
+    priority?: number;
     /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */
     storageDefault?: Record<string, string>;
     /** Tags for secondary filtering and search */
@@ -125,5 +194,7 @@ export declare const VALID_EXAMPLE_LEVELS: readonly SkillExampleLevel[];
 export declare const VALID_TARGETS: readonly SkillTarget[];
 /** Valid categories for manifest validation */
 export declare const VALID_CATEGORIES: readonly SkillCategory[];
+/** Valid layouts for manifest validation */
+export declare const VALID_LAYOUTS: readonly SkillLayout[];
 /** Valid bundles for manifest validation */
 export declare const VALID_BUNDLES: readonly SkillBundle[];

package/src/manifest.js

@@ -7,7 +7,7 @@
  * @module skills/manifest
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALID_BUNDLES = exports.VALID_CATEGORIES = exports.VALID_TARGETS = exports.VALID_EXAMPLE_LEVELS = void 0;
+exports.VALID_BUNDLES = exports.VALID_LAYOUTS = exports.VALID_CATEGORIES = exports.VALID_TARGETS = exports.VALID_EXAMPLE_LEVELS = void 0;
 /** Valid example levels for manifest validation */
 exports.VALID_EXAMPLE_LEVELS = ['basic', 'intermediate', 'advanced'];
 /** Valid deployment targets for manifest validation */
@@ -17,6 +17,7 @@ exports.VALID_CATEGORIES = [
     'setup',
     'deployment',
     'development',
+    'development/create',
     'config',
     'testing',
     'guides',
@@ -24,6 +25,8 @@ exports.VALID_CATEGORIES = [
     'extensibility',
     'observability',
 ];
+/** Valid layouts for manifest validation */
+exports.VALID_LAYOUTS = ['router', 'component'];
 /** Valid bundles for manifest validation */
 exports.VALID_BUNDLES = ['recommended', 'minimal', 'full'];
 //# sourceMappingURL=manifest.js.map

package/src/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAwIH,mDAAmD;AACtC,QAAA,oBAAoB,GAAiC,CAAC,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;AAExG,uDAAuD;AAC1C,QAAA,aAAa,GAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AAEvG,+CAA+C;AAClC,QAAA,gBAAgB,GAA6B;IACxD,OAAO;IACP,YAAY;IACZ,aAAa;IACb,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,YAAY;IACZ,eAAe;IACf,eAAe;CAChB,CAAC;AAEF,4CAA4C;AAC/B,QAAA,aAAa,GAA2B,CAAC,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC","sourcesContent":["/**\n * Skills catalog manifest types.\n *\n * Defines the contract between the catalog, scaffold tooling, and future installer.\n *\n * @module skills/manifest\n */\n\n/**\n * Supported deployment targets for skill filtering.\n */\nexport type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';\n\n/**\n * Skill categories for organizing the catalog.\n */\nexport type SkillCategory =\n  | 'setup'\n  | 'deployment'\n  | 'development'\n  | 'config'\n  | 'testing'\n  | 'guides'\n  | 'production'\n  | 'extensibility'\n  | 'observability';\n\n/**\n * Bundle membership for curated scaffold presets.\n */\nexport type SkillBundle = 'recommended' | 'minimal' | 'full';\n\n/**\n * Install destination types for future provider wiring.\n */\nexport type SkillDestination = 'project-local' | '.claude/skills' | 'codex' | 'gemini';\n\n/**\n * Merge strategy when installing a skill that already exists at the destination.\n */\nexport type SkillMergeStrategy = 'overwrite' | 'skip-existing';\n\n/**\n * Install configuration for a catalog skill.\n */\nexport interface SkillInstallConfig {\n  /** Where this skill can be installed */\n  destinations: SkillDestination[];\n  /** How to handle existing skills at the destination */\n  mergeStrategy: SkillMergeStrategy;\n  /** Other skills this depends on (by name) */\n  dependencies?: string[];\n}\n\n/**\n * Complexity level for a reference example.\n */\nexport type SkillExampleLevel = 'basic' | 'intermediate' | 'advanced';\n\n/**\n * Metadata for a single example file within a reference's examples/ directory.\n */\nexport interface SkillReferenceExampleEntry {\n  /** Example name — matches filename without extension */\n  name: string;\n  /** Short description of what the example demonstrates */\n  description: string;\n  /** Complexity level */\n  level: SkillExampleLevel;\n  /** Searchable tags for the example */\n  tags: string[];\n  /** Concrete APIs or patterns the example demonstrates */\n  features: string[];\n}\n\n/**\n * Metadata for a single reference file within a skill's references/ directory.\n * Extracted from YAML frontmatter or inferred from the markdown heading.\n */\nexport interface SkillReferenceEntry {\n  /** Reference name — matches filename without extension */\n  name: string;\n  /** Short description from frontmatter or first paragraph */\n  description: string;\n  /** Example files for this reference, located in examples/<reference-name>/ */\n  examples?: SkillReferenceExampleEntry[];\n}\n\n/**\n * A single entry in the skills catalog manifest.\n *\n * This is the core contract connecting SKILL.md files to scaffolding,\n * future installation, and provider-specific destinations.\n */\nexport interface SkillCatalogEntry {\n  /** Unique skill name — matches SKILL.md frontmatter `name` */\n  name: string;\n  /** Skill category for organization */\n  category: SkillCategory;\n  /** Short description */\n  description: string;\n  /** Path to the skill directory, relative to catalog/ */\n  path: string;\n  /** Deployment targets this skill applies to */\n  targets: SkillTarget[];\n  /** Whether the skill has scripts/, references/, or assets/ directories */\n  hasResources: boolean;\n  /** Resolved reference metadata from references/ directory */\n  references?: SkillReferenceEntry[];\n  /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */\n  storageDefault?: Record<string, string>;\n  /** Tags for secondary filtering and search */\n  tags: string[];\n  /** Bundle membership for scaffold presets */\n  bundle?: SkillBundle[];\n  /** Install configuration for future distribution (optional — not yet used by CLI) */\n  install?: SkillInstallConfig;\n  /**\n   * Optional skill quality rating (0..5, one decimal). Surfaced via the\n   * Skills HTTP API for consumers that want to filter by `min-rating` or\n   * sort by quality. Mirrors `SkillMetadata.rating` introduced in v1.2.0.\n   */\n  rating?: number;\n  /**\n   * Other catalog skills this skill depends on (by `name`). Used by the\n   * dependency resolver introduced in v1.2.0 to register dependencies first\n   * during scaffold/install. Aligns with the agentskills Skill Package\n   * Manifest proposal `requires` field.\n   */\n  requires?: string[];\n}\n\n/**\n * The skills catalog manifest — single source of truth for scaffold and install tooling.\n */\nexport interface SkillManifest {\n  /** Manifest schema version */\n  version: 1;\n  /** All catalog skills */\n  skills: SkillCatalogEntry[];\n}\n\n/** Valid example levels for manifest validation */\nexport const VALID_EXAMPLE_LEVELS: readonly SkillExampleLevel[] = ['basic', 'intermediate', 'advanced'];\n\n/** Valid deployment targets for manifest validation */\nexport const VALID_TARGETS: readonly SkillTarget[] = ['node', 'vercel', 'lambda', 'cloudflare', 'all'];\n\n/** Valid categories for manifest validation */\nexport const VALID_CATEGORIES: readonly SkillCategory[] = [\n  'setup',\n  'deployment',\n  'development',\n  'config',\n  'testing',\n  'guides',\n  'production',\n  'extensibility',\n  'observability',\n];\n\n/** Valid bundles for manifest validation */\nexport const VALID_BUNDLES: readonly SkillBundle[] = ['recommended', 'minimal', 'full'];\n"]}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAiNH,mDAAmD;AACtC,QAAA,oBAAoB,GAAiC,CAAC,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;AAExG,uDAAuD;AAC1C,QAAA,aAAa,GAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AAEvG,+CAA+C;AAClC,QAAA,gBAAgB,GAA6B;IACxD,OAAO;IACP,YAAY;IACZ,aAAa;IACb,oBAAoB;IACpB,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,YAAY;IACZ,eAAe;IACf,eAAe;CAChB,CAAC;AAEF,4CAA4C;AAC/B,QAAA,aAAa,GAA2B,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE7E,4CAA4C;AAC/B,QAAA,aAAa,GAA2B,CAAC,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC","sourcesContent":["/**\n * Skills catalog manifest types.\n *\n * Defines the contract between the catalog, scaffold tooling, and future installer.\n *\n * @module skills/manifest\n */\n\n/**\n * Supported deployment targets for skill filtering.\n */\nexport type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';\n\n/**\n * Skill categories for organizing the catalog.\n */\nexport type SkillCategory =\n  | 'setup'\n  | 'deployment'\n  | 'development'\n  | 'development/create'\n  | 'config'\n  | 'testing'\n  | 'guides'\n  | 'production'\n  | 'extensibility'\n  | 'observability';\n\n/**\n * Catalog layouts the validator understands.\n *\n * - `router` (default): the legacy shape used by skills like `frontmcp-development`\n *   — a Scenario Routing Table SKILL.md plus `references/<topic>.md` files with\n *   examples grouped in `examples/<topic>/<example>.md` subdirectories.\n *\n * - `component`: the new per-thing layout used by skills like `create-tool`\n *   — flat `examples/<example>.md` (no per-reference grouping), an optional\n *   `rules/` directory with short DO/DON'T files, and rich SKILL.md frontmatter\n *   designed for Claude Code's auto-trigger heuristics (explicit `triggers:`,\n *   `paths:` globs, `when_to_use`).\n */\nexport type SkillLayout = 'router' | 'component';\n\n/**\n * Bundle membership for curated scaffold presets.\n */\nexport type SkillBundle = 'recommended' | 'minimal' | 'full';\n\n/**\n * Install destination types for future provider wiring.\n */\nexport type SkillDestination = 'project-local' | '.claude/skills' | 'codex' | 'gemini';\n\n/**\n * Merge strategy when installing a skill that already exists at the destination.\n */\nexport type SkillMergeStrategy = 'overwrite' | 'skip-existing';\n\n/**\n * Install configuration for a catalog skill.\n */\nexport interface SkillInstallConfig {\n  /** Where this skill can be installed */\n  destinations: SkillDestination[];\n  /** How to handle existing skills at the destination */\n  mergeStrategy: SkillMergeStrategy;\n  /** Other skills this depends on (by name) */\n  dependencies?: string[];\n}\n\n/**\n * Complexity level for a reference example.\n */\nexport type SkillExampleLevel = 'basic' | 'intermediate' | 'advanced';\n\n/**\n * Metadata for a single example file within a reference's examples/ directory.\n */\nexport interface SkillReferenceExampleEntry {\n  /** Example name — matches filename without extension */\n  name: string;\n  /** Short description of what the example demonstrates */\n  description: string;\n  /** Complexity level */\n  level: SkillExampleLevel;\n  /** Searchable tags for the example */\n  tags: string[];\n  /** Concrete APIs or patterns the example demonstrates */\n  features: string[];\n}\n\n/**\n * Metadata for a single reference file within a skill's references/ directory.\n * Extracted from YAML frontmatter or inferred from the markdown heading.\n */\nexport interface SkillReferenceEntry {\n  /** Reference name — matches filename without extension */\n  name: string;\n  /** Short description from frontmatter or first paragraph */\n  description: string;\n  /** Example files for this reference, located in examples/<reference-name>/ */\n  examples?: SkillReferenceExampleEntry[];\n}\n\n/**\n * Top-level example entry used by `layout: 'component'` skills, where\n * examples live flat under `examples/<example>.md` (not grouped under a\n * parent reference). Shape mirrors {@link SkillReferenceExampleEntry} so\n * downstream consumers can use a uniform metadata type.\n */\nexport interface SkillComponentExampleEntry {\n  /** Example name — matches filename without extension */\n  name: string;\n  /** Short description of what the example demonstrates */\n  description: string;\n  /** Complexity level */\n  level: SkillExampleLevel;\n  /** Searchable tags for the example */\n  tags: string[];\n  /** Concrete APIs or patterns the example demonstrates */\n  features: string[];\n}\n\n/**\n * Top-level rule entry used by `layout: 'component'` skills. Rules are short\n * DO / DON'T constraint files under `rules/<rule>.md`. The body explains the\n * rule, gives good / bad examples, and (where possible) ends with a grep-based\n * verification snippet.\n */\nexport interface SkillComponentRuleEntry {\n  /** Rule name — matches filename without extension */\n  name: string;\n  /** One-sentence statement of the rule */\n  constraint: string;\n  /** Enforcement strength — `required` for must-follow, `recommended` for nudges */\n  severity?: 'required' | 'recommended';\n}\n\n/**\n * A single entry in the skills catalog manifest.\n *\n * This is the core contract connecting SKILL.md files to scaffolding,\n * future installation, and provider-specific destinations.\n */\nexport interface SkillCatalogEntry {\n  /** Unique skill name — matches SKILL.md frontmatter `name` */\n  name: string;\n  /** Skill category for organization */\n  category: SkillCategory;\n  /** Short description */\n  description: string;\n  /** Path to the skill directory, relative to catalog/ */\n  path: string;\n  /** Deployment targets this skill applies to */\n  targets: SkillTarget[];\n  /** Whether the skill has scripts/, references/, or assets/ directories */\n  hasResources: boolean;\n  /** Resolved reference metadata from references/ directory */\n  references?: SkillReferenceEntry[];\n  /**\n   * Catalog layout — see {@link SkillLayout}. Defaults to `'router'` when\n   * absent for backward compatibility with the legacy frontmcp-* router\n   * skills.\n   */\n  layout?: SkillLayout;\n  /**\n   * Top-level example entries — only populated when `layout === 'component'`.\n   * Router-layout skills group examples under `references[].examples`\n   * instead.\n   */\n  examples?: SkillComponentExampleEntry[];\n  /**\n   * Top-level rule entries — only populated when `layout === 'component'`.\n   * Each rule corresponds to a file in `rules/<name>.md`.\n   */\n  rules?: SkillComponentRuleEntry[];\n  /**\n   * Priority hint surfaced to Claude Code's auto-discovery. Higher number =\n   * earlier in the ranking. Mirrors `metadata.priority` in SKILL.md\n   * frontmatter.\n   */\n  priority?: number;\n  /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */\n  storageDefault?: Record<string, string>;\n  /** Tags for secondary filtering and search */\n  tags: string[];\n  /** Bundle membership for scaffold presets */\n  bundle?: SkillBundle[];\n  /** Install configuration for future distribution (optional — not yet used by CLI) */\n  install?: SkillInstallConfig;\n  /**\n   * Optional skill quality rating (0..5, one decimal). Surfaced via the\n   * Skills HTTP API for consumers that want to filter by `min-rating` or\n   * sort by quality. Mirrors `SkillMetadata.rating` introduced in v1.2.0.\n   */\n  rating?: number;\n  /**\n   * Other catalog skills this skill depends on (by `name`). Used by the\n   * dependency resolver introduced in v1.2.0 to register dependencies first\n   * during scaffold/install. Aligns with the agentskills Skill Package\n   * Manifest proposal `requires` field.\n   */\n  requires?: string[];\n}\n\n/**\n * The skills catalog manifest — single source of truth for scaffold and install tooling.\n */\nexport interface SkillManifest {\n  /** Manifest schema version */\n  version: 1;\n  /** All catalog skills */\n  skills: SkillCatalogEntry[];\n}\n\n/** Valid example levels for manifest validation */\nexport const VALID_EXAMPLE_LEVELS: readonly SkillExampleLevel[] = ['basic', 'intermediate', 'advanced'];\n\n/** Valid deployment targets for manifest validation */\nexport const VALID_TARGETS: readonly SkillTarget[] = ['node', 'vercel', 'lambda', 'cloudflare', 'all'];\n\n/** Valid categories for manifest validation */\nexport const VALID_CATEGORIES: readonly SkillCategory[] = [\n  'setup',\n  'deployment',\n  'development',\n  'development/create',\n  'config',\n  'testing',\n  'guides',\n  'production',\n  'extensibility',\n  'observability',\n];\n\n/** Valid layouts for manifest validation */\nexport const VALID_LAYOUTS: readonly SkillLayout[] = ['router', 'component'];\n\n/** Valid bundles for manifest validation */\nexport const VALID_BUNDLES: readonly SkillBundle[] = ['recommended', 'minimal', 'full'];\n"]}

package/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md

@@ -1,61 +0,0 @@
----
-name: basic-class-tool
-reference: create-tool
-level: basic
-description: 'A minimal tool using the class-based pattern with Zod input validation and output schema.'
-tags: [development, tool, class]
-features:
-  - 'Extending `ToolContext` and implementing the `execute()` method'
-  - 'Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)'
-  - 'Defining `outputSchema` to validate and restrict output fields'
-  - 'Registering the tool in an `@App` via the `tools` array'
----
-
-# Basic Class-Based Tool
-
-A minimal tool using the class-based pattern with Zod input validation and output schema.
-
-## Code
-
-```typescript
-// src/apps/main/tools/greet-user.tool.ts
-import { Tool, ToolContext, z } from '@frontmcp/sdk';
-
-@Tool({
-  name: 'greet_user',
-  description: 'Greet a user by name',
-  inputSchema: {
-    name: z.string().describe('The name of the user to greet'),
-  },
-  outputSchema: {
-    greeting: z.string(),
-  },
-})
-class GreetUserTool extends ToolContext {
-  async execute(input: { name: string }): Promise<{ greeting: string }> {
-    return { greeting: `Hello, ${input.name}!` };
-  }
-}
-```
-
-```typescript
-// src/apps/main/index.ts
-import { App } from '@frontmcp/sdk';
-
-@App({
-  name: 'main',
-  tools: [GreetUserTool],
-})
-class MainApp {}
-```
-
-## What This Demonstrates
-
-- Extending `ToolContext` and implementing the `execute()` method
-- Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)
-- Defining `outputSchema` to validate and restrict output fields
-- Registering the tool in an `@App` via the `tools` array
-
-## Related
-
-- See `create-tool` for the full API reference including annotations, rate limiting, and elicitation

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

@@ -1,84 +0,0 @@
----
-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 { ResourceNotFoundError, Tool, ToolContext, z } from '@frontmcp/sdk';
-
-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

@@ -1,92 +0,0 @@
----
-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.progress(progress, total, message?)`'
-  - '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, z } from '@frontmcp/sdk';
-
-@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.progress(i + 1, input.items.length, `Processing item ${i + 1}`);
-      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.progress(progress, total, message?)`
-- 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

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

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

@@ -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