@frontmcp/skills 0.0.1

package/catalog/auth/configure-auth/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: configure-auth
+description: Set up authentication with public, transparent, local, or remote auth modes. Use when adding auth, OAuth, login, session security, or protecting tools and resources.
+tags:
+  - auth
+  - oauth
+  - security
+bundle:
+  - recommended
+  - full
+visibility: both
+priority: 10
+parameters:
+  - name: mode
+    description: Authentication mode (public, transparent, local, remote)
+    type: string
+    required: false
+    default: public
+  - name: provider
+    description: OAuth provider URL for transparent or remote modes
+    type: string
+    required: false
+examples:
+  - scenario: Public mode with anonymous scopes
+    parameters:
+      mode: public
+    expected-outcome: Server accepts all connections with anonymous scopes and session TTL
+  - scenario: Transparent mode validating external JWTs
+    parameters:
+      mode: transparent
+      provider: https://auth.example.com
+    expected-outcome: Server validates JWTs from the configured provider against the expected audience
+  - scenario: Local mode with server-signed tokens
+    parameters:
+      mode: local
+    expected-outcome: Server signs its own JWT tokens for client authentication
+  - scenario: Remote mode with full OAuth flow
+    parameters:
+      mode: remote
+      provider: https://auth.example.com
+    expected-outcome: Server redirects clients through a remote OAuth authorization flow
+license: Apache-2.0
+compatibility: Requires Node.js 18+ and @frontmcp/auth package
+metadata:
+  category: auth
+  difficulty: intermediate
+  docs: https://docs.agentfront.dev/frontmcp/authentication/overview
+---
+
+# Configure Authentication for FrontMCP
+
+This skill covers setting up authentication in a FrontMCP server. FrontMCP supports four auth modes, each suited to different deployment scenarios. All authentication logic lives in the `@frontmcp/auth` library.
+
+## Auth Modes Overview
+
+| Mode          | Use Case                                   | Token Issuer        |
+| ------------- | ------------------------------------------ | ------------------- |
+| `public`      | Open access with optional scoping          | None                |
+| `transparent` | Validate externally-issued JWTs            | External provider   |
+| `local`       | Server signs its own tokens                | The FrontMCP server |
+| `remote`      | Full OAuth 2.1 flow with external provider | External provider   |
+
+## Mode 1: Public
+
+Public mode allows all connections without authentication. Use this for development or open APIs where access control is handled elsewhere.
+
+```typescript
+@App({
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+})
+class MyApp {}
+```
+
+- `sessionTtl` -- session lifetime in seconds.
+- `anonymousScopes` -- scopes granted to all unauthenticated clients.
+
+## Mode 2: Transparent
+
+Transparent mode validates JWTs issued by an external provider without initiating an OAuth flow. The server fetches the provider's JWKS to verify token signatures.
+
+```typescript
+@App({
+  auth: {
+    mode: 'transparent',
+    provider: 'https://auth.example.com',
+    expectedAudience: 'my-api',
+  },
+})
+class MyApp {}
+```
+
+- `provider` -- the authorization server URL. FrontMCP fetches JWKS from `{provider}/.well-known/jwks.json`.
+- `expectedAudience` -- the `aud` claim value that tokens must contain.
+
+Use transparent mode when clients already have tokens from your identity provider and the server only needs to verify them.
+
+## Mode 3: Local
+
+Local mode lets the FrontMCP server sign its own JWT tokens. This is useful for internal services or environments where an external identity provider is not available.
+
+```typescript
+@App({
+  auth: {
+    mode: 'local',
+    local: {
+      issuer: 'my-server',
+      audience: 'my-api',
+    },
+  },
+})
+class MyApp {}
+```
+
+- `local.issuer` -- the `iss` claim set in generated tokens.
+- `local.audience` -- the `aud` claim set in generated tokens.
+
+The server generates a signing key pair on startup (or loads one from the configured key store). Clients obtain tokens through a server-provided endpoint.
+
+## Mode 4: Remote
+
+Remote mode performs a full OAuth 2.1 authorization flow with an external provider. Clients are redirected to the provider for authentication and return with an authorization code.
+
+```typescript
+@App({
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: 'xxx',
+  },
+})
+class MyApp {}
+```
+
+- `provider` -- the OAuth 2.1 authorization server URL.
+- `clientId` -- the OAuth client identifier registered with the provider.
+
+## OAuth Local Dev Flow
+
+For local development with `remote` or `transparent` mode, you can skip the full OAuth flow by setting the environment to development:
+
+```typescript
+@App({
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: 'dev-client-id',
+  },
+})
+class MyApp {}
+```
+
+When `NODE_ENV=development`, FrontMCP relaxes token validation to support local identity provider instances (e.g., a local Keycloak or mock OAuth server). Tokens are still validated, but HTTPS requirements and strict issuer checks are loosened.
+
+## Multi-App Auth
+
+Each `@App` in a FrontMCP server can have a different auth configuration. This is useful when a single server hosts multiple logical applications with different security requirements:
+
+```typescript
+@App({
+  name: 'public-api',
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+  tools: [PublicSearchTool, PublicInfoTool],
+})
+class PublicApi {}
+
+@App({
+  name: 'admin-api',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: 'admin-client',
+  },
+  tools: [AdminTool, ConfigTool],
+})
+class AdminApi {}
+```
+
+## Credential Vault
+
+The credential vault stores downstream API tokens obtained during the OAuth flow. Use it when your MCP tools need to call external APIs on behalf of the authenticated user:
+
+```typescript
+@App({
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: 'mcp-client-id',
+  },
+  vault: {
+    encryption: {
+      secret: process.env['VAULT_SECRET'],
+    },
+    providers: [
+      {
+        name: 'github',
+        type: 'oauth2',
+        scopes: ['repo', 'read:user'],
+      },
+      {
+        name: 'slack',
+        type: 'oauth2',
+        scopes: ['chat:write', 'channels:read'],
+      },
+    ],
+  },
+})
+class MyApp {}
+```
+
+Tools access downstream credentials via the `this.authProviders` context extension:
+
+```typescript
+@Tool({ name: 'create_github_issue' })
+class CreateGithubIssueTool extends ToolContext {
+  async execute(input: { title: string; body: string }) {
+    // Access downstream credentials via the authProviders context extension
+    const github = await this.authProviders.get('github');
+    const headers = await this.authProviders.headers('github');
+    // Use headers to call GitHub API
+  }
+}
+```
+
+The `authProviders` accessor (from `@frontmcp/auth`) provides:
+
+- `get(provider)` -- get the credential/token for a provider.
+- `headers(provider)` -- get pre-formatted auth headers for HTTP requests.
+- `has(provider)` -- check if a provider is configured.
+- `refresh(provider)` -- force refresh the credential.
+
+## Common Mistakes
+
+- **Using memory session store in production** -- sessions are lost on restart. Use Redis or Vercel KV.
+- **Hardcoding secrets** -- use environment variables for `clientId`, vault secrets, and Redis passwords.
+- **Missing audience validation** -- always set the audience field. Without it, tokens from any audience would be accepted.
+
+## Reference
+
+- Auth docs: [docs.agentfront.dev/frontmcp/authentication/overview](https://docs.agentfront.dev/frontmcp/authentication/overview)
+- Auth package: `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth)
+- Auth options interface: import `AuthOptionsInput` from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/options)
+- Credential vault: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/vault)

package/catalog/auth/configure-auth/references/auth-modes.md

@@ -0,0 +1,77 @@
+# Auth Modes Detailed Comparison
+
+## Public Mode
+
+No authentication required. All requests get anonymous access.
+
+```typescript
+auth: {
+  mode: 'public',
+  sessionTtl: 3600,
+  anonymousScopes: ['read', 'write'],
+  publicAccess: { tools: true, resources: true, prompts: true },
+}
+```
+
+**Use when:** Development, internal tools, public APIs.
+
+## Transparent Mode
+
+Server validates tokens from an upstream identity provider. Does not issue or refresh tokens.
+
+```typescript
+auth: {
+  mode: 'transparent',
+  provider: 'https://auth.example.com',
+  expectedAudience: 'my-api',
+  clientId: 'my-client-id',
+}
+```
+
+**Use when:** Behind an API gateway or reverse proxy that handles auth.
+
+## Local Mode
+
+Server signs its own JWT tokens. Full control over token lifecycle.
+
+```typescript
+auth: {
+  mode: 'local',
+  local: {
+    issuer: 'my-server',
+    audience: 'my-api',
+  },
+  tokenStorage: 'redis',
+  consent: { enabled: true },
+  incrementalAuth: { enabled: true },
+}
+```
+
+**Use when:** Standalone servers with full auth control, development with local OAuth.
+
+## Remote Mode
+
+Server delegates to an upstream auth orchestrator for token management.
+
+```typescript
+auth: {
+  mode: 'remote',
+  provider: 'https://auth.example.com',
+  clientId: 'my-client-id',
+  clientSecret: process.env.AUTH_SECRET,
+  tokenStorage: 'redis',
+}
+```
+
+**Use when:** Enterprise deployments with centralized identity management.
+
+## Comparison Table
+
+| Feature          | Public        | Transparent     | Local       | Remote       |
+| ---------------- | ------------- | --------------- | ----------- | ------------ |
+| Token issuance   | Anonymous JWT | None (upstream) | Self-signed | Orchestrator |
+| Token refresh    | No            | No              | Yes         | Yes          |
+| PKCE support     | No            | No              | Yes         | Yes          |
+| Credential vault | No            | No              | Yes         | Yes          |
+| Consent flow     | No            | No              | Optional    | Optional     |
+| Federated auth   | No            | No              | Optional    | Optional     |

package/catalog/auth/configure-session/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: configure-session
+description: Configure session storage with Redis, Vercel KV, or in-memory backends. Use when setting up sessions, choosing a storage provider, or configuring TTL and key prefixes.
+tags:
+  - session
+  - storage
+  - redis
+  - memory
+bundle:
+  - recommended
+  - full
+visibility: both
+priority: 5
+parameters:
+  - name: provider
+    description: Session storage provider
+    type: string
+    required: false
+    default: memory
+  - name: ttl
+    description: Default session TTL in milliseconds
+    type: number
+    required: false
+    default: 3600000
+  - name: key-prefix
+    description: Redis/KV key prefix for session keys
+    type: string
+    required: false
+    default: 'mcp:session:'
+examples:
+  - scenario: Configure Redis session store for production
+    parameters:
+      provider: redis
+    expected-outcome: Sessions are persisted in Redis with automatic TTL expiration and key prefixing
+  - scenario: Configure Vercel KV for serverless deployment
+    parameters:
+      provider: vercel-kv
+    expected-outcome: Sessions use Vercel KV with environment-based credentials
+  - scenario: Use memory store for local development
+    parameters:
+      provider: memory
+    expected-outcome: Sessions are stored in-process memory, suitable for development only
+license: Apache-2.0
+compatibility: Requires Node.js 18+. Redis provider requires ioredis. Vercel KV provider requires @vercel/kv.
+metadata:
+  category: auth
+  difficulty: beginner
+  docs: https://docs.agentfront.dev/frontmcp/deployment/redis-setup
+---
+
+# Configure Session Management
+
+This skill covers setting up session storage in FrontMCP. Sessions track authenticated user state, token storage, and request context across MCP interactions.
+
+## Storage Providers
+
+| Provider    | Use Case            | Persistence | Package Required |
+| ----------- | ------------------- | ----------- | ---------------- |
+| `memory`    | Development/testing | None        | None (default)   |
+| `redis`     | Node.js production  | Yes         | `ioredis`        |
+| `vercel-kv` | Vercel deployments  | Yes         | `@vercel/kv`     |
+
+Never use the memory store in production. Sessions are lost on process restart, which breaks authentication for all connected clients.
+
+## Redis (Production)
+
+Configure Redis session storage via the `@FrontMcp` decorator:
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App()
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+  },
+})
+class MyServer {}
+```
+
+The SDK internally calls `createSessionStore()` to create a `RedisSessionStore`. The factory lazy-loads `ioredis` so it is not bundled when you use a different provider.
+
+## Vercel KV
+
+For Vercel deployments, use the `vercel-kv` provider. Credentials are read from environment variables set automatically by the Vercel platform:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+class MyServer {}
+```
+
+Required environment variables (auto-injected when a KV store is linked to your Vercel project):
+
+| Variable            | Description                    |
+| ------------------- | ------------------------------ |
+| `KV_REST_API_URL`   | Vercel KV REST endpoint        |
+| `KV_REST_API_TOKEN` | Vercel KV authentication token |
+
+## Memory (Development Default)
+
+When no Redis or KV configuration is provided, the SDK falls back to an in-memory store. This is suitable only for development:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  // No redis config -- defaults to memory
+})
+class MyServer {}
+```
+
+## Key Prefix
+
+All persistent stores support a `keyPrefix` option that namespaces session keys. This is important when multiple FrontMCP servers share the same Redis instance:
+
+```typescript
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'billing-mcp:session:',
+  },
+})
+class BillingServer {}
+```
+
+Use a unique prefix per server to prevent session key collisions.
+
+## TTL Configuration
+
+The `defaultTtlMs` option controls how long sessions live before expiring:
+
+| Scenario                     | Recommended TTL         |
+| ---------------------------- | ----------------------- |
+| Interactive user sessions    | `3_600_000` (1 hour)    |
+| Long-running agent workflows | `86_400_000` (24 hours) |
+| Short-lived CI/CD operations | `600_000` (10 minutes)  |
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: 'localhost',
+    port: 6379,
+    defaultTtlMs: 86_400_000, // 24 hours for agent workflows
+  },
+})
+class MyServer {}
+```
+
+## Pub/Sub for Resource Subscriptions
+
+If your server uses resource subscriptions (clients subscribe to resource change notifications), you need a pub/sub channel. Vercel KV does not support pub/sub, so you must use Redis for the pub/sub channel even when using Vercel KV for sessions:
+
+```typescript
+import { createSessionStore, createPubsubStore } from '@frontmcp/sdk/auth/session';
+
+// Sessions in Vercel KV
+const sessionStore = await createSessionStore({
+  provider: 'vercel-kv',
+  url: process.env['KV_REST_API_URL'],
+  token: process.env['KV_REST_API_TOKEN'],
+});
+
+// Pub/sub requires Redis
+const pubsubStore = createPubsubStore({
+  provider: 'redis',
+  host: process.env['REDIS_HOST'] ?? 'localhost',
+  port: 6379,
+});
+```
+
+## Common Mistakes
+
+- **Constructing stores directly** -- always use factory functions (`createSessionStore`). Direct construction bypasses lazy-loading and key prefix normalization.
+- **Using memory store in production** -- sessions vanish on restart. Clients must re-authenticate and in-flight workflows are lost.
+- **Missing `await` for Vercel KV** -- the `createSessionStore` factory is async when the provider is `vercel-kv`. Forgetting to await causes the store to be used before its connection is ready.
+- **Sharing key prefixes** -- if two servers share a Redis instance with the same prefix, their sessions collide. Always use a unique prefix per server.
+
+## Reference
+
+- Session docs: [docs.agentfront.dev/frontmcp/deployment/redis-setup](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
+- Session store factory: `createSessionStore()` — import from `@frontmcp/sdk`
+- Redis session store: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/session)
+- Vercel KV session store: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/session)

package/catalog/config/configure-elicitation/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: configure-elicitation
+description: Enable interactive user input requests from tools during execution. Use when tools need to ask the user for confirmation, choices, or additional data mid-execution.
+tags: [elicitation, user-input, interactive, confirmation, form]
+examples:
+  - scenario: Tool asks user for confirmation before destructive action
+    expected-outcome: Execution pauses, user confirms, tool proceeds
+  - scenario: Tool presents a form for user to fill in
+    expected-outcome: User fills form fields, tool receives structured input
+priority: 6
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/elicitation
+---
+
+# Configuring Elicitation
+
+Elicitation allows tools to request interactive input from users mid-execution — confirmations, choices, or structured form data.
+
+## When to Use
+
+Enable elicitation when:
+
+- Tools need user confirmation before destructive actions (delete, deploy, overwrite)
+- Tools need additional input during execution (file selection, parameter choice)
+- Building multi-step workflows that require user decisions at each stage
+
+## Enable Elicitation
+
+### Basic (In-Memory)
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  elicitation: {
+    enabled: true,
+  },
+})
+class Server {}
+```
+
+### With Redis (Distributed/Production)
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  elicitation: {
+    enabled: true,
+    redis: { provider: 'redis', host: 'localhost', port: 6379 },
+  },
+})
+class Server {}
+```
+
+## ElicitationOptionsInput
+
+```typescript
+interface ElicitationOptionsInput {
+  enabled?: boolean; // default: false
+  redis?: RedisOptionsInput; // storage for elicitation state
+}
+```
+
+## Using Elicitation in Tools
+
+When elicitation is enabled, tools can request user input via the MCP elicitation protocol:
+
+```typescript
+import { 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 }) {
+    // Count records that would be deleted
+    const db = this.get(DB_TOKEN);
+    const count = await db.count(input.table, input.filter);
+
+    // Request confirmation from user before proceeding
+    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 };
+    }
+
+    const deleted = await db.delete(input.table, input.filter);
+    return { deleted };
+  }
+}
+```
+
+## How It Works
+
+1. Tool calls `this.elicit()` with a message and requested schema
+2. Server sends an `elicitation/request` to the client
+3. Client displays the request to the user (UI varies by client)
+4. User responds with structured data matching the schema
+5. `this.elicit()` returns the user's response
+6. Tool continues execution with the response
+
+## Notes
+
+- When `enabled: false` (default), `this.elicit()` is not available — keeps resource overhead low
+- When enabled, tool output schemas are automatically extended with elicitation fallback type
+- Use Redis storage for production/multi-instance deployments
+- Not all MCP clients support elicitation — handle gracefully when `this.elicit()` returns `undefined`
+
+## Verification
+
+```bash
+# Enable elicitation and start
+frontmcp dev
+
+# Test with an MCP client that supports elicitation
+# The tool should pause and request user input
+```