@frontmcp/skills 1.0.0-beta.13 → 1.0.0-beta.14

package/catalog/TEMPLATE.md

@@ -88,6 +88,61 @@ Continue with subsequent steps.
 | -------------------- | -------------- | ------------- |
 | Common error message | Why it happens | How to fix it |
 
+## Examples
+
+Each reference file has a corresponding `examples/<reference-name>/` directory with standalone, copy-pasteable examples.
+
+### Example file structure
+
+````markdown
+---
+name: example-name
+reference: parent-reference-name
+level: basic | intermediate | advanced
+description: One sentence describing the exact scenario this example covers.
+tags: [keyword1, keyword2, keyword3]
+features:
+  - Concrete API or pattern this example demonstrates
+  - Another concrete behavior shown in the code
+---
+
+# Example Title
+
+One sentence expanding slightly on the frontmatter description.
+
+## Code
+
+\```typescript
+// src/path/to/file.ts
+import { ... } from '@frontmcp/sdk';
+// Complete, self-contained code
+\```
+
+## What This Demonstrates
+
+- Key pattern or API shown
+
+## Related
+
+- See `reference-name` for the full API reference
+````
+
+Use the example file frontmatter as the single source of truth for example metadata. Reference `## Examples` tables and `skills-manifest.json` should mirror `name`, `level`, `description`, `tags`, and `features` from the example file.
+
+### Linking from references
+
+Add a `## Examples` section at the bottom of each reference file (before `## Reference`):
+
+```markdown
+## Examples
+
+| Example                                                      | Level | Description   |
+| ------------------------------------------------------------ | ----- | ------------- |
+| [`example-name`](../examples/reference-name/example-name.md) | Basic | What it shows |
+
+> See all examples in [`examples/reference-name/`](../examples/reference-name/)
+```
+
 ## Reference
 
 - [Documentation](https://docs.agentfront.dev/frontmcp/...)

package/catalog/frontmcp-config/SKILL.md

@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/configuration/overview
+  docs: https://docs.agentfront.dev/frontmcp/fundamentals/overview
 ---
 
 # FrontMCP Configuration Router
@@ -152,5 +152,5 @@ Server (@FrontMcp)     ← Global defaults
 
 ## Reference
 
-- [Configuration Overview](https://docs.agentfront.dev/frontmcp/configuration/overview)
+- [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)
 - Related skills: `configure-transport`, `configure-http`, `configure-throttle`, `configure-elicitation`, `configure-auth`, `configure-session`, `setup-redis`, `setup-sqlite`

package/catalog/frontmcp-config/examples/configure-auth/multi-app-auth.md

@@ -0,0 +1,87 @@
+---
+name: multi-app-auth
+reference: configure-auth
+level: advanced
+description: 'Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.'
+tags: [config, auth, security, multi-app, remote, multi]
+features:
+  - 'Hosting multiple `@App` instances on a single FrontMCP server with different auth modes'
+  - 'Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints'
+  - 'Isolating tools per app so each security posture governs only its own tools'
+---
+
+# Multi-App Auth with Different Security Postures
+
+Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'public_search',
+  description: 'Search public records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class PublicSearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Public result: ${input.query}`] };
+  }
+}
+
+@Tool({
+  name: 'admin_config',
+  description: 'Modify server configuration (admin only)',
+  inputSchema: { key: z.string(), value: z.string() },
+  outputSchema: { updated: z.boolean() },
+})
+class AdminConfigTool extends ToolContext {
+  async execute(input: { key: string; value: string }) {
+    // Only authenticated admins can reach this tool
+    return { updated: true };
+  }
+}
+
+@App({
+  name: 'public-api',
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+  tools: [PublicSearchTool],
+})
+class PublicApi {}
+
+@App({
+  name: 'admin-api',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['ADMIN_OAUTH_CLIENT_ID'] ?? 'admin-client',
+  },
+  tools: [AdminConfigTool],
+})
+class AdminApi {}
+
+@FrontMcp({
+  info: { name: 'multi-app-server', version: '1.0.0' },
+  apps: [PublicApi, AdminApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Hosting multiple `@App` instances on a single FrontMCP server with different auth modes
+- Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints
+- Isolating tools per app so each security posture governs only its own tools
+
+## Related
+
+- See `configure-auth` for individual auth mode configuration details
+- See `configure-auth-modes` for a feature comparison table across all modes

package/catalog/frontmcp-config/examples/configure-auth/public-mode-setup.md

@@ -0,0 +1,63 @@
+---
+name: public-mode-setup
+reference: configure-auth
+level: basic
+description: 'Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.'
+tags: [config, auth, session, public, mode, setup]
+features:
+  - "Configuring `mode: 'public'` for unauthenticated access"
+  - 'Setting `sessionTtl` to control anonymous session lifetime'
+  - 'Granting `anonymousScopes` so tools can check scope-based permissions even without auth'
+---
+
+# Public Auth Mode Setup
+
+Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search',
+  description: 'Search public records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class SearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Result for: ${input.query}`] };
+  }
+}
+
+@App({
+  name: 'public-api',
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+  tools: [SearchTool],
+})
+class PublicApi {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [PublicApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `mode: 'public'` for unauthenticated access
+- Setting `sessionTtl` to control anonymous session lifetime
+- Granting `anonymousScopes` so tools can check scope-based permissions even without auth
+
+## Related
+
+- See `configure-auth` for all four auth modes
+- See `configure-auth-modes` for a detailed comparison of modes

package/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md

@@ -0,0 +1,76 @@
+---
+name: remote-oauth-with-vault
+reference: configure-auth
+level: intermediate
+description: 'Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.'
+tags: [config, oauth, auth, remote, vault]
+features:
+  - "Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow"
+  - 'Loading `clientId` from environment variables instead of hardcoding'
+  - "Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls"
+---
+
+# Remote OAuth Mode with Credential Vault
+
+Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'create_github_issue',
+  description: 'Create a GitHub issue on behalf of the user',
+  inputSchema: {
+    repo: z.string(),
+    title: z.string(),
+    body: z.string(),
+  },
+  outputSchema: { issueUrl: z.string() },
+})
+class CreateGithubIssueTool extends ToolContext {
+  async execute(input: { repo: string; title: string; body: string }) {
+    // Access downstream credentials via the authProviders context extension
+    const headers = await this.authProviders.headers('github');
+
+    const response = await fetch(`https://api.github.com/repos/${input.repo}/issues`, {
+      method: 'POST',
+      headers: { ...headers, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: input.title, body: input.body }),
+    });
+    const issue = await response.json();
+    return { issueUrl: issue.html_url };
+  }
+}
+
+@App({
+  name: 'dev-tools',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['OAUTH_CLIENT_ID'] ?? 'mcp-client-id',
+  },
+  tools: [CreateGithubIssueTool],
+})
+class DevToolsApp {}
+
+@FrontMcp({
+  info: { name: 'dev-tools-server', version: '1.0.0' },
+  apps: [DevToolsApp],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow
+- Loading `clientId` from environment variables instead of hardcoding
+- Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls
+
+## Related
+
+- See `configure-auth` for credential vault API (`get`, `headers`, `has`, `refresh`)
+- See `configure-session` for setting up Redis-based session storage in production

package/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md

@@ -0,0 +1,77 @@
+---
+name: local-self-signed-tokens
+reference: configure-auth-modes
+level: intermediate
+description: 'Configure a server that signs its own JWT tokens with consent and incremental auth enabled.'
+tags: [config, auth, redis, local, auth-modes, modes]
+features:
+  - "Using `mode: 'local'` so the server signs its own JWTs"
+  - 'Setting `local.issuer` and `local.audience` to control token claims'
+  - 'Enabling `consent` for explicit user authorization flow'
+  - 'Enabling `incrementalAuth` to request additional scopes progressively'
+  - 'Using Redis for token storage in production'
+---
+
+# Local Self-Signed Tokens
+
+Configure a server that signs its own JWT tokens with consent and incremental auth enabled.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'manage_users',
+  description: 'Manage user accounts',
+  inputSchema: { action: z.enum(['list', 'create', 'delete']), userId: z.string().optional() },
+  outputSchema: { success: z.boolean(), message: z.string() },
+})
+class ManageUsersTool extends ToolContext {
+  async execute(input: { action: string; userId?: string }) {
+    return { success: true, message: `Action ${input.action} completed` };
+  }
+}
+
+@App({
+  name: 'internal-api',
+  auth: {
+    mode: 'local',
+    local: {
+      issuer: 'my-internal-server',
+      audience: 'internal-api',
+    },
+    tokenStorage: 'redis',
+    consent: { enabled: true },
+    incrementalAuth: { enabled: true },
+  },
+  tools: [ManageUsersTool],
+})
+class InternalApi {}
+
+@FrontMcp({
+  info: { name: 'local-auth-server', version: '1.0.0' },
+  apps: [InternalApi],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: 6379,
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'local'` so the server signs its own JWTs
+- Setting `local.issuer` and `local.audience` to control token claims
+- Enabling `consent` for explicit user authorization flow
+- Enabling `incrementalAuth` to request additional scopes progressively
+- Using Redis for token storage in production
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `configure-session` for session storage configuration

package/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md

@@ -0,0 +1,73 @@
+---
+name: remote-enterprise-oauth
+reference: configure-auth-modes
+level: advanced
+description: 'Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.'
+tags: [config, oauth, auth, redis, remote, auth-modes]
+features:
+  - "Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server"
+  - 'Loading `clientId` and `clientSecret` from environment variables (never hardcoded)'
+  - 'Configuring Redis-backed token storage for production persistence'
+  - 'Full OAuth flow: clients are redirected to the provider and return with an authorization code'
+---
+
+# Remote Enterprise OAuth
+
+Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'query_data',
+  description: 'Query enterprise data warehouse',
+  inputSchema: { sql: z.string() },
+  outputSchema: { rows: z.array(z.record(z.string(), z.unknown())), rowCount: z.number() },
+})
+class QueryDataTool extends ToolContext {
+  async execute(input: { sql: string }) {
+    return { rows: [{ id: 1, name: 'example' }], rowCount: 1 };
+  }
+}
+
+@App({
+  name: 'enterprise-api',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['OAUTH_CLIENT_ID']!,
+    clientSecret: process.env['OAUTH_CLIENT_SECRET'],
+    tokenStorage: 'redis',
+  },
+  tools: [QueryDataTool],
+})
+class EnterpriseApi {}
+
+@FrontMcp({
+  info: { name: 'enterprise-server', version: '1.0.0' },
+  apps: [EnterpriseApi],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'redis.internal',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server
+- Loading `clientId` and `clientSecret` from environment variables (never hardcoded)
+- Configuring Redis-backed token storage for production persistence
+- Full OAuth flow: clients are redirected to the provider and return with an authorization code
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `setup-redis` for Redis provisioning details

package/catalog/frontmcp-config/examples/configure-auth-modes/transparent-jwt-validation.md

@@ -0,0 +1,64 @@
+---
+name: transparent-jwt-validation
+reference: configure-auth-modes
+level: basic
+description: 'Validate externally-issued JWTs without managing token lifecycle on the server.'
+tags: [config, auth, transparent, auth-modes, modes, jwt]
+features:
+  - "Using `mode: 'transparent'` to validate tokens from an external identity provider"
+  - 'Setting `expectedAudience` to restrict which tokens are accepted'
+  - 'The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically'
+---
+
+# Transparent JWT Validation
+
+Validate externally-issued JWTs without managing token lifecycle on the server.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_profile',
+  description: 'Get the authenticated user profile',
+  inputSchema: { userId: z.string() },
+  outputSchema: { id: z.string(), email: z.string() },
+})
+class GetProfileTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    return { id: input.userId, email: `${input.userId}@example.com` };
+  }
+}
+
+@App({
+  name: 'api',
+  auth: {
+    mode: 'transparent',
+    provider: 'https://auth.example.com',
+    expectedAudience: 'my-api',
+    clientId: 'my-client-id',
+  },
+  tools: [GetProfileTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'transparent-server', version: '1.0.0' },
+  apps: [ApiApp],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'transparent'` to validate tokens from an external identity provider
+- Setting `expectedAudience` to restrict which tokens are accepted
+- The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `configure-auth` for the full authentication setup guide

package/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md

@@ -0,0 +1,83 @@
+---
+name: basic-confirmation-gate
+reference: configure-elicitation
+level: basic
+description: 'Request user confirmation before executing a destructive action.'
+tags: [config, elicitation, confirmation, gate]
+features:
+  - 'Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator'
+  - 'Using `this.elicit()` to pause tool execution and request user confirmation'
+  - 'Handling the case where the client does not support elicitation (`!confirmation`)'
+  - 'Using a boolean `requestedSchema` for simple yes/no confirmations'
+---
+
+# Basic Confirmation Gate
+
+Request user confirmation before executing a destructive action.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_records',
+  description: 'Delete records from the database',
+  inputSchema: {
+    table: z.string(),
+    filter: z.string(),
+  },
+  outputSchema: { deleted: z.number() },
+})
+class DeleteRecordsTool extends ToolContext {
+  async execute(input: { table: string; filter: string }) {
+    const count = 42; // simulate counting matching records
+
+    const confirmation = await this.elicit({
+      message: `This will delete ${count} records from ${input.table}. Are you sure?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deletion' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deleted: 0 };
+    }
+
+    return { deleted: count };
+  }
+}
+
+@App({
+  name: 'db-tools',
+  tools: [DeleteRecordsTool],
+})
+class DbApp {}
+
+@FrontMcp({
+  info: { name: 'elicit-server', version: '1.0.0' },
+  apps: [DbApp],
+  elicitation: {
+    enabled: true,
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator
+- Using `this.elicit()` to pause tool execution and request user confirmation
+- Handling the case where the client does not support elicitation (`!confirmation`)
+- Using a boolean `requestedSchema` for simple yes/no confirmations
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `setup-redis` for distributed elicitation state

package/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md

@@ -0,0 +1,87 @@
+---
+name: distributed-elicitation-redis
+reference: configure-elicitation
+level: intermediate
+description: 'Configure elicitation with Redis storage for multi-instance production deployments.'
+tags: [config, redis, elicitation, distributed]
+features:
+  - 'Configuring Redis-backed elicitation state for multi-instance deployments'
+  - 'Using a `requestedSchema` with both required and optional fields'
+  - 'Elicitation state is shared across server instances so the response can arrive at any replica'
+  - 'Loading Redis connection details from environment variables'
+---
+
+# Distributed Elicitation with Redis
+
+Configure elicitation with Redis storage for multi-instance production deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'deploy_service',
+  description: 'Deploy a service to production',
+  inputSchema: {
+    service: z.string(),
+    version: z.string(),
+  },
+  outputSchema: { deploymentId: z.string(), status: z.string() },
+})
+class DeployServiceTool extends ToolContext {
+  async execute(input: { service: string; version: string }) {
+    const confirmation = await this.elicit({
+      message: `Deploy ${input.service}@${input.version} to production?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deployment' },
+          reason: { type: 'string', description: 'Deployment reason (optional)' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deploymentId: '', status: 'cancelled' };
+    }
+
+    return { deploymentId: 'deploy-abc123', status: 'started' };
+  }
+}
+
+@App({
+  name: 'deploy-tools',
+  tools: [DeployServiceTool],
+})
+class DeployApp {}
+
+@FrontMcp({
+  info: { name: 'deploy-server', version: '1.0.0' },
+  apps: [DeployApp],
+  elicitation: {
+    enabled: true,
+    redis: {
+      provider: 'redis',
+      host: process.env['REDIS_HOST'] ?? 'localhost',
+      port: Number(process.env['REDIS_PORT'] ?? 6379),
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring Redis-backed elicitation state for multi-instance deployments
+- Using a `requestedSchema` with both required and optional fields
+- Elicitation state is shared across server instances so the response can arrive at any replica
+- Loading Redis connection details from environment variables
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `configure-session` for session storage with Redis