@frontmcp/skills 0.0.1

package/catalog/development/create-prompt/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: create-prompt
+description: Create MCP prompts for reusable AI interaction patterns. Use when building prompts, defining prompt arguments, or creating conversation templates.
+tags: [prompts, mcp, templates, messages, decorator]
+tools:
+  - name: create_prompt
+    purpose: Scaffold a new prompt class
+parameters:
+  - name: name
+    description: Prompt name in kebab-case
+    type: string
+    required: true
+examples:
+  - scenario: Create a code review prompt with language argument
+    expected-outcome: Prompt registered and callable via MCP
+  - scenario: Create a multi-turn debugging prompt with assistant priming
+    expected-outcome: Prompt producing structured message sequences
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/prompts
+---
+
+# Creating MCP Prompts
+
+Prompts define reusable AI interaction patterns in the MCP protocol. They produce structured message sequences that clients use to guide LLM conversations. In FrontMCP, prompts are classes extending `PromptContext`, decorated with `@Prompt`, that return `GetPromptResult` objects.
+
+## When to Use @Prompt
+
+Use `@Prompt` when you need to expose a reusable conversation template that an AI client can invoke with arguments. Prompts are ideal for code review patterns, debugging sessions, RAG queries, report generation, translation workflows, and any scenario where you want a standardized message structure.
+
+## Class-Based Pattern
+
+Create a class extending `PromptContext` and implement `execute(args)`. The `@Prompt` decorator accepts `name`, optional `description`, and `arguments` (the prompt's input parameters).
+
+```typescript
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+@Prompt({
+  name: 'code-review',
+  description: 'Generate a structured code review for the given code',
+  arguments: [
+    { name: 'code', description: 'The code to review', required: true },
+    { name: 'language', description: 'Programming language', required: false },
+  ],
+})
+class CodeReviewPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const language = args.language ?? 'unknown language';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Please review the following ${language} code. Focus on correctness, performance, and maintainability.\n\n\`\`\`${language}\n${args.code}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+### Decorator Options
+
+The `@Prompt` decorator accepts:
+
+- `name` (required) -- unique prompt name
+- `description` (optional) -- human-readable description
+- `arguments` (optional) -- array of `PromptArgument` objects
+
+### PromptArgument Structure
+
+Each entry in the `arguments` array has this shape:
+
+```typescript
+interface PromptArgument {
+  name: string; // argument name
+  description?: string; // human-readable description
+  required?: boolean; // whether the argument must be provided (default: false)
+}
+```
+
+Required arguments are validated before `execute()` runs. Missing required arguments throw `MissingPromptArgumentError`.
+
+### GetPromptResult Structure
+
+The `execute()` method must return a `GetPromptResult`:
+
+```typescript
+interface GetPromptResult {
+  messages: Array<{
+    role: 'user' | 'assistant';
+    content: {
+      type: 'text';
+      text: string;
+    };
+  }>;
+}
+```
+
+Messages use two roles:
+
+- `user` -- represents the human side of the conversation
+- `assistant` -- primes the conversation with expected response patterns
+
+### Available Context Methods and Properties
+
+`PromptContext` extends `ExecutionContextBase`, providing:
+
+**Methods:**
+
+- `execute(args)` -- the main method you implement, receives `Record<string, string>`
+- `this.get(token)` -- resolve a dependency from DI (throws if not found)
+- `this.tryGet(token)` -- resolve a dependency from DI (returns `undefined` if not found)
+- `this.fail(err)` -- abort execution, triggers error flow (never returns)
+- `this.mark(stage)` -- set active execution stage for debugging/tracking
+- `this.fetch(input, init?)` -- HTTP fetch with context propagation
+
+**Properties:**
+
+- `this.metadata` -- prompt metadata from the decorator
+- `this.scope` -- the current scope instance
+- `this.context` -- the execution context
+
+## Multi-Turn Conversations
+
+Use `assistant` role messages to prime the conversation with expected response patterns:
+
+```typescript
+@Prompt({
+  name: 'debug-session',
+  description: 'Start a structured debugging session',
+  arguments: [
+    { name: 'error', description: 'The error message or stack trace', required: true },
+    { name: 'context', description: 'Additional context about what was happening', required: false },
+  ],
+})
+class DebugSessionPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const contextNote = args.context ? `\n\nAdditional context: ${args.context}` : '';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `I encountered an error and need help debugging it.\n\nError:\n\`\`\`\n${args.error}\n\`\`\`${contextNote}`,
+          },
+        },
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: "I'll help you debug this. Let me analyze the error systematically.\n\n**Step 1: Error Classification**\nLet me first identify what type of error this is and its likely root cause.\n\n",
+          },
+        },
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Please continue with your analysis and suggest specific fixes.',
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+## Dynamic Prompt Generation
+
+Prompts can perform async operations to generate context-aware messages. Use `this.get()` for dependency injection and `this.fetch()` for HTTP requests.
+
+```typescript
+import type { Token } from '@frontmcp/di';
+
+interface KnowledgeBase {
+  search(query: string, limit: number): Promise<Array<{ title: string; content: string }>>;
+}
+const KNOWLEDGE_BASE: Token<KnowledgeBase> = Symbol('knowledge-base');
+
+@Prompt({
+  name: 'rag-query',
+  description: 'Answer a question using knowledge base context',
+  arguments: [
+    { name: 'question', description: 'The question to answer', required: true },
+    { name: 'maxSources', description: 'Maximum number of sources to include', required: false },
+  ],
+})
+class RagQueryPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const kb = this.get(KNOWLEDGE_BASE);
+    const maxSources = parseInt(args.maxSources ?? '3', 10);
+    const sources = await kb.search(args.question, maxSources);
+
+    const contextBlock = sources.map((s, i) => `### Source ${i + 1}: ${s.title}\n${s.content}`).join('\n\n');
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Answer the following question using only the provided sources. If the sources do not contain enough information, say so clearly.\n\n**Question:** ${args.question}\n\n---\n\n${contextBlock}`,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+## Embedding Resources in Prompts
+
+Include MCP resource content directly in prompt messages using the `resource` content type:
+
+```typescript
+@Prompt({
+  name: 'analyze-config',
+  description: 'Analyze application configuration and suggest improvements',
+  arguments: [{ name: 'configUri', description: 'URI of the config resource to analyze', required: true }],
+})
+class AnalyzeConfigPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'resource',
+            resource: {
+              uri: args.configUri,
+              mimeType: 'application/json',
+              text: '(resource content will be resolved by the client)',
+            },
+          },
+        },
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Analyze the configuration above. Identify potential issues, security concerns, and suggest improvements.',
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+## Function-Style Builder
+
+For simple prompts that do not need a class, use the `prompt()` function builder:
+
+```typescript
+import { prompt } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+const TranslatePrompt = prompt({
+  name: 'translate',
+  description: 'Translate text between languages',
+  arguments: [
+    { name: 'text', description: 'Text to translate', required: true },
+    { name: 'from', description: 'Source language', required: true },
+    { name: 'to', description: 'Target language', required: true },
+  ],
+})(
+  (args): GetPromptResult => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Translate the following text from ${args?.from} to ${args?.to}. Provide only the translation, no explanations.\n\nText: ${args?.text}`,
+        },
+      },
+    ],
+  }),
+);
+```
+
+Register it the same way as a class prompt: `prompts: [TranslatePrompt]`.
+
+## Error Handling
+
+Use `this.fail()` to abort prompt execution. Missing required arguments are caught automatically before `execute()` runs.
+
+```typescript
+@Prompt({
+  name: 'generate-tests',
+  description: 'Generate test cases for a function',
+  arguments: [
+    { name: 'functionCode', description: 'The function to test', required: true },
+    { name: 'framework', description: 'Test framework (jest, mocha, vitest)', required: true },
+  ],
+})
+class GenerateTestsPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const validFrameworks = ['jest', 'mocha', 'vitest'];
+    if (!validFrameworks.includes(args.framework)) {
+      this.fail(new Error(`Unsupported test framework: "${args.framework}". Supported: ${validFrameworks.join(', ')}`));
+    }
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Write comprehensive ${args.framework} test cases for the following function. Include edge cases, error handling, and boundary conditions.\n\n\`\`\`\n${args.functionCode}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+## Stage Tracking
+
+Use `this.mark()` for debugging and observability in complex prompts:
+
+```typescript
+@Prompt({
+  name: 'research-report',
+  description: 'Generate a structured research report prompt',
+  arguments: [
+    { name: 'topic', description: 'Research topic', required: true },
+    { name: 'depth', description: 'Report depth: brief, standard, or comprehensive', required: false },
+  ],
+})
+class ResearchReportPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    this.mark('build-outline');
+    const depth = args.depth ?? 'standard';
+    const outline = this.buildOutline(depth);
+
+    this.mark('compose-messages');
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Write a ${depth} research report on "${args.topic}".\n\nFollow this structure:\n${outline}\n\nInclude citations where possible and maintain an objective, academic tone.`,
+          },
+        },
+      ],
+    };
+  }
+
+  private buildOutline(depth: string): string {
+    const sections = ['Introduction', 'Background', 'Key Findings'];
+    if (depth === 'standard' || depth === 'comprehensive') {
+      sections.push('Analysis', 'Discussion');
+    }
+    if (depth === 'comprehensive') {
+      sections.push('Methodology', 'Limitations', 'Future Research');
+    }
+    sections.push('Conclusion');
+    return sections.map((s, i) => `${i + 1}. ${s}`).join('\n');
+  }
+}
+```
+
+## Registration
+
+Add prompt classes (or function-style prompts) to the `prompts` array in `@App`.
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'my-app',
+  prompts: [CodeReviewPrompt, DebugSessionPrompt, TranslatePrompt],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+```
+
+## Nx Generator
+
+Scaffold a new prompt using the Nx generator:
+
+```bash
+nx generate @frontmcp/nx:prompt
+```
+
+This creates the prompt file, spec file, and updates barrel exports.

package/catalog/development/create-provider/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: create-provider
+description: Create dependency injection providers for database connections, API clients, and singleton services. Use when tools and resources need shared services, DB pools, or configuration objects.
+tags: [provider, di, dependency-injection, singleton, database, service]
+parameters:
+  - name: name
+    description: Provider name
+    type: string
+    required: true
+examples:
+  - scenario: Create a database connection pool provider
+    expected-outcome: Singleton DB pool injectable into all tools via this.get()
+  - scenario: Create a config provider from environment variables
+    expected-outcome: Type-safe config object available in any context
+priority: 8
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/extensibility/providers
+---
+
+# Creating Providers (Dependency Injection)
+
+Providers are singleton services — database pools, API clients, config objects — that tools, resources, prompts, and agents can access via `this.get(token)`.
+
+## When to Use
+
+Create a provider when:
+
+- Multiple tools need the same database connection pool
+- You have API clients that should be shared (not recreated per request)
+- Configuration values should be centralized and type-safe
+- You need lifecycle management (initialize on startup, cleanup on shutdown)
+
+## Step 1: Define a Token
+
+Tokens identify providers in the DI container:
+
+```typescript
+import type { Token } from '@frontmcp/di';
+
+// Define a typed token
+interface DatabaseService {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>;
+  close(): Promise<void>;
+}
+
+const DB_TOKEN: Token<DatabaseService> = Symbol('DatabaseService');
+```
+
+## Step 2: Create the Provider
+
+```typescript
+import { Provider } from '@frontmcp/sdk';
+import { createPool, Pool } from 'your-db-driver';
+
+@Provider({ name: 'DatabaseProvider' })
+class DatabaseProvider implements DatabaseService {
+  private pool!: Pool;
+
+  async onInit() {
+    // Called once when server starts
+    this.pool = await createPool({
+      connectionString: process.env.DATABASE_URL,
+      max: 20,
+    });
+  }
+
+  async query(sql: string, params?: unknown[]) {
+    return this.pool.query(sql, params);
+  }
+
+  async onDestroy() {
+    // Called when server shuts down
+    await this.pool.end();
+  }
+}
+```
+
+## Step 3: Register in @App or @FrontMcp
+
+```typescript
+@App({
+  name: 'MyApp',
+  providers: [DatabaseProvider], // App-scoped provider
+  tools: [QueryTool, InsertTool],
+})
+class MyApp {}
+
+// OR at server level (shared across all apps)
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  providers: [DatabaseProvider], // Server-scoped provider
+})
+class Server {}
+```
+
+## Step 4: Use in Tools
+
+Access providers via `this.get(token)` in any context (ToolContext, ResourceContext, PromptContext, AgentContext):
+
+```typescript
+@Tool({
+  name: 'query_users',
+  description: 'Query users from the database',
+  inputSchema: {
+    filter: z.string().optional(),
+    limit: z.number().default(10),
+  },
+  outputSchema: {
+    users: z.array(z.object({ id: z.string(), name: z.string(), email: z.string() })),
+  },
+})
+class QueryUsersTool extends ToolContext {
+  async execute(input: { filter?: string; limit: number }) {
+    const db = this.get(DB_TOKEN); // Get the database provider
+    const users = await db.query('SELECT id, name, email FROM users WHERE name LIKE $1 LIMIT $2', [
+      `%${input.filter ?? ''}%`,
+      input.limit,
+    ]);
+    return { users };
+  }
+}
+```
+
+### Safe Access
+
+```typescript
+// Throws if not registered
+const db = this.get(DB_TOKEN);
+
+// Returns undefined if not registered
+const db = this.tryGet(DB_TOKEN);
+if (!db) {
+  this.fail(new Error('Database not configured'));
+}
+```
+
+## Common Provider Patterns
+
+### Configuration Provider
+
+```typescript
+interface AppConfig {
+  apiBaseUrl: string;
+  maxRetries: number;
+  debug: boolean;
+}
+
+const CONFIG_TOKEN: Token<AppConfig> = Symbol('AppConfig');
+
+@Provider({ name: 'ConfigProvider' })
+class ConfigProvider implements AppConfig {
+  readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
+  readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
+  readonly debug = process.env.DEBUG === 'true';
+}
+```
+
+### HTTP API Client Provider
+
+```typescript
+interface ApiClient {
+  get(path: string): Promise<unknown>;
+  post(path: string, body: unknown): Promise<unknown>;
+}
+
+const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
+
+@Provider({ name: 'ApiClientProvider' })
+class ApiClientProvider implements ApiClient {
+  private baseUrl!: string;
+  private apiKey!: string;
+
+  async onInit() {
+    this.baseUrl = process.env.API_URL!;
+    this.apiKey = process.env.API_KEY!;
+  }
+
+  async get(path: string) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    return res.json();
+  }
+
+  async post(path: string, body: unknown) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return res.json();
+  }
+}
+```
+
+### Cache Provider
+
+```typescript
+const CACHE_TOKEN: Token<Map<string, unknown>> = Symbol('Cache');
+
+@Provider({ name: 'CacheProvider' })
+class CacheProvider extends Map<string, unknown> {
+  // Map is already a valid provider - no lifecycle needed
+}
+```
+
+## Provider Lifecycle
+
+| Method        | When Called             | Use For                          |
+| ------------- | ----------------------- | -------------------------------- |
+| `onInit()`    | Server startup (async)  | Open connections, load config    |
+| `onDestroy()` | Server shutdown (async) | Close connections, flush buffers |
+
+Providers are initialized in dependency order — if Provider A depends on Provider B, B initializes first.
+
+## Nx Generator
+
+```bash
+nx generate @frontmcp/nx:provider my-provider --project=my-app
+```
+
+## Verification
+
+```bash
+# Start server — providers initialize on startup
+frontmcp dev
+
+# Call a tool that uses the provider
+# If provider fails to init, you'll see an error at startup
+```