@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/TEMPLATE.md

@@ -1,9 +1,10 @@
 ---
 name: skill-name
-description: Short description of what this skill does
-tags: [category, keyword]
+description: Primary action sentence. Use when [scenario 1], [scenario 2], or [scenario 3].
+tags: [category, keyword1, keyword2]
 tools:
-  - tool_name
+  - name: tool_name
+    purpose: What this tool does in this skill
 parameters:
   - name: param_name
     description: What this parameter controls
@@ -12,18 +13,40 @@ parameters:
 examples:
   - scenario: When to use this skill
     expected-outcome: What the user should see after completion
-compatibility: Node.js 22+
+priority: 7
+visibility: both
 license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/...
 ---
 
-# Skill Name
+# Skill Title
 
-Brief description of the skill's purpose and when to use it.
+One-paragraph overview of what this skill accomplishes and its role in the FrontMCP ecosystem.
+
+## When to Use This Skill
+
+### Must Use
+
+- Scenario where this is the only correct skill to apply
+- Another mandatory scenario
+
+### Recommended
+
+- Scenario where this skill helps but alternatives exist
+- Helpful but optional scenario
+
+### Skip When
+
+- Scenario where another skill is the better choice (see `other-skill-name`)
+- Situation where this skill does not apply
+
+> **Decision:** One-liner summarizing when to pick this skill over alternatives.
 
 ## Prerequisites
 
-- List any prerequisites
-- Tools or packages needed
+- Required packages or tools
+- Prior skills that should be completed first (see `prerequisite-skill`)
 
 ## Steps
 
@@ -39,11 +62,33 @@ Describe the first step with code examples:
 
 Continue with subsequent steps.
 
-### Step 3: Verification
+## Common Patterns
+
+<!-- Include this section only for skills with clear right/wrong usage patterns -->
+
+| Pattern         | Correct                  | Incorrect      | Why                                  |
+| --------------- | ------------------------ | -------------- | ------------------------------------ |
+| Decorator usage | `@Tool({ name: '...' })` | `@Tool('...')` | Decorator requires an options object |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Config item verified
+- [ ] Dependencies installed
+
+### Runtime
+
+- [ ] Feature works as expected
+- [ ] Error cases handled
+
+## Troubleshooting
 
-How to verify the skill completed successfully.
+| Problem              | Cause          | Solution      |
+| -------------------- | -------------- | ------------- |
+| Common error message | Why it happens | How to fix it |
 
-## Notes
+## Reference
 
-- Any important caveats or tips
-- Links to related documentation
+- [Documentation](https://docs.agentfront.dev/frontmcp/...)
+- Related skills: `related-skill-a`, `related-skill-b`

package/catalog/frontmcp-config/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: frontmcp-config
+description: "Domain router for configuring MCP servers \u2014 transport, HTTP, throttle, elicitation, auth, sessions, and storage. Use when configuring any aspect of a FrontMCP server."
+tags: [router, config, transport, http, auth, session, redis, sqlite, throttle, guide]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/configuration/overview
+---
+
+# FrontMCP Configuration Router
+
+Entry point for configuring FrontMCP servers. This skill helps you find the right configuration skill based on what aspect of your server you need to set up.
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up a new server and need to understand which configuration options exist
+- Deciding between authentication modes, transport protocols, or storage backends
+- Planning server configuration across transport, auth, throttling, and storage
+
+### Recommended
+
+- Looking up which skill covers a specific config option (CORS, rate limits, session TTL, etc.)
+- Understanding how configuration layers work (server-level vs app-level vs tool-level)
+- Reviewing the full configuration surface area before production deployment
+
+### Skip When
+
+- You already know which config area to change (go directly to `configure-transport`, `configure-auth`, etc.)
+- You need to build components, not configure the server (see `frontmcp-development`)
+- You need to deploy, not configure (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill when you need to figure out WHAT to configure. Use the specific skill when you already know.
+
+## Prerequisites
+
+- A FrontMCP project scaffolded with `frontmcp create` (see `frontmcp-setup`)
+- Node.js 22+ and npm/yarn installed
+
+## Steps
+
+1. Identify the configuration area you need using the Scenario Routing Table below
+2. Navigate to the specific configuration skill (e.g., `configure-transport`, `configure-auth`) for detailed instructions
+3. Apply the configuration in your `@FrontMcp` or `@App` decorator
+4. Verify using the Verification Checklist at the end of this skill
+
+## Scenario Routing Table
+
+| Scenario                                                   | Skill                   | Description                                                   |
+| ---------------------------------------------------------- | ----------------------- | ------------------------------------------------------------- |
+| Choose between SSE, Streamable HTTP, or stdio              | `configure-transport`   | Transport protocol selection with distributed session options |
+| Set up CORS, port, base path, or request limits            | `configure-http`        | HTTP server options for Streamable HTTP and SSE transports    |
+| Add rate limiting, concurrency, or IP filtering            | `configure-throttle`    | Server-level and per-tool throttle configuration              |
+| Enable tools to ask users for input                        | `configure-elicitation` | Elicitation schemas, stores, and multi-step flows             |
+| Set up authentication (public, transparent, local, remote) | `configure-auth`        | OAuth flows, credential vault, multi-app auth                 |
+| Configure session storage backends                         | `configure-session`     | Memory, Redis, Vercel KV, and custom session stores           |
+| Add Redis for production storage                           | `setup-redis`           | Docker Redis, Vercel KV, pub/sub for subscriptions            |
+| Add SQLite for local development                           | `setup-sqlite`          | SQLite with WAL mode, migration helpers                       |
+
+## Configuration Layers
+
+FrontMCP configuration cascades through three layers:
+
+```text
+Server (@FrontMcp)     ← Global defaults
+  └── App (@App)       ← App-level overrides
+       └── Tool (@Tool) ← Per-tool overrides
+```
+
+| Setting               | Server       | App | Tool           |
+| --------------------- | ------------ | --- | -------------- |
+| Transport             | Yes          | No  | No             |
+| HTTP (CORS, port)     | Yes          | No  | No             |
+| Throttle (rate limit) | Yes (global) | No  | Yes (per-tool) |
+| Auth mode             | Yes          | Yes | No             |
+| Session store         | Yes          | No  | No             |
+| Elicitation           | No           | No  | Yes (per-tool) |
+
+## Cross-Cutting Patterns
+
+| Pattern             | Rule                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| Auth + session      | Auth mode determines session requirements: `remote` needs Redis/KV; `public` can use memory       |
+| Transport + storage | Stateless transports (serverless) require distributed storage; stateful (Node) can use in-process |
+| Throttle scope      | Server-level throttle applies to all tools; per-tool throttle overrides for specific tools        |
+| Environment config  | Use environment variables for all secrets (API keys, Redis URLs, OAuth credentials)               |
+| Config validation   | FrontMCP validates config at startup; invalid config throws before the server starts              |
+
+## Common Patterns
+
+| Pattern              | Correct                                                                                | Incorrect                                              | Why                                                                                                             |
+| -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Auth mode for dev    | `auth: { mode: 'public' }` or `auth: { mode: 'transparent', provider: '...' }` locally | `auth: { mode: 'remote', ... }` with real OAuth in dev | Remote auth requires a running OAuth provider; public/transparent are simpler for local dev                     |
+| Session store        | Redis for production, memory for development                                           | Memory for production                                  | Memory sessions are lost on restart and don't work across serverless invocations                                |
+| Rate limit placement | Server-level for global limits, per-tool for expensive operations                      | Only server-level                                      | Some tools are cheap (list) and some are expensive (generate); per-tool limits prevent abuse of expensive tools |
+| CORS config          | Explicit allowed origins in production                                                 | `cors: { origin: '*' }` in production                  | Wildcard CORS allows any origin to call your server                                                             |
+| Config secrets       | `process.env.REDIS_URL` via environment variable                                       | Hardcoded `redis://localhost:6379` in source           | Hardcoded secrets leak to git and break in different environments                                               |
+
+## Verification Checklist
+
+### Transport and HTTP
+
+- [ ] Transport protocol configured and server starts without errors
+- [ ] CORS allows expected origins (test with browser or curl)
+- [ ] Port and base path accessible from client
+
+### Authentication
+
+- [ ] Auth mode set appropriately for the environment (public/transparent for dev, remote for prod)
+- [ ] OAuth credentials stored in environment variables, not source code
+- [ ] Session store configured with appropriate backend (memory for dev, Redis for prod)
+
+### Throttle and Security
+
+- [ ] Global rate limit configured to prevent abuse
+- [ ] Expensive tools have per-tool throttle overrides
+- [ ] IP allow/deny lists configured if needed
+
+### Storage
+
+- [ ] Redis or SQLite configured and connectable
+- [ ] Storage persists across server restarts (not memory in production)
+
+## Troubleshooting
+
+| Problem                                 | Cause                                            | Solution                                                                                             |
+| --------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Server fails to start with config error | Invalid or missing required config field         | Check the error message; FrontMCP validates config at startup and reports the specific invalid field |
+| CORS blocked in browser                 | Missing or incorrect CORS origin config          | Add the client's origin to `http.cors.origin`; see `configure-http`                                  |
+| Rate limit too aggressive               | Global limit applied to all tools                | Add per-tool overrides for cheap tools with higher limits; see `configure-throttle`                  |
+| Sessions lost on serverless             | Using memory session store on stateless platform | Switch to Redis or Vercel KV; see `configure-session`                                                |
+| Auth callback fails                     | OAuth redirect URI mismatch                      | Ensure the callback URL in your OAuth provider matches `auth.callbackUrl`; see `configure-auth`      |
+
+## Reference
+
+- [Configuration Overview](https://docs.agentfront.dev/frontmcp/configuration/overview)
+- Related skills: `configure-transport`, `configure-http`, `configure-throttle`, `configure-elicitation`, `configure-auth`, `configure-session`, `setup-redis`, `setup-sqlite`

package/catalog/frontmcp-config/references/configure-auth.md

@@ -0,0 +1,238 @@
+# 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.
+
+## When to Use This Skill
+
+### Must Use
+
+- Adding authentication to a new FrontMCP server for the first time
+- Switching between auth modes (e.g., moving from `public` to `remote` for production)
+- Configuring the credential vault to access downstream APIs on behalf of authenticated users
+
+### Recommended
+
+- Setting up multi-app auth where different `@App` instances need different security postures
+- Configuring OAuth local dev flow for development against `remote` or `transparent` modes
+- Adding audience validation or session TTL tuning to an existing auth setup
+
+### Skip When
+
+- You need to manage session storage backends (Redis, Vercel KV) -- use `configure-session` instead
+- You are building a plugin that extends auth context -- use `create-plugin` instead
+
+> **Decision:** Use this skill whenever you need to choose, configure, or change the authentication mode on a FrontMCP server.
+
+## 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',
+    },
+  },
+})
+class MyApp {}
+```
+
+- `local.issuer` -- the `iss` claim set in generated tokens (defaults to server URL if omitted).
+
+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. Credential vault is managed through the auth provider's OAuth flow — downstream tokens are stored automatically when users authorize external services.
+
+```typescript
+@App({
+  name: 'MyApp',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: 'mcp-client-id',
+  },
+})
+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 Patterns
+
+| Pattern                     | Correct                                                                        | Incorrect                                                       | Why                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Session store in production | Use Redis or Vercel KV session store                                           | Use default in-memory session store                             | Sessions are lost on restart; in-memory does not survive process recycling    |
+| Secret management           | Load `clientId`, vault secrets, and Redis passwords from environment variables | Hardcode secrets in source code                                 | Hardcoded secrets leak into version control and are difficult to rotate       |
+| Audience validation         | Always set `expectedAudience` in transparent/remote mode                       | Omit the audience field                                         | Without audience validation, tokens issued for any audience would be accepted |
+| Auth mode for development   | Use `public` mode or local OAuth mock for dev environments                     | Use `remote` mode pointing at production IdP during development | Avoids accidental production token usage and simplifies local iteration       |
+| Vault encryption secret     | Generate a strong random secret and store in env var `VAULT_SECRET`            | Use a short or predictable string for vault encryption          | Weak secrets compromise all stored downstream credentials                     |
+
+## Verification Checklist
+
+**Configuration**
+
+- [ ] Auth mode is set to the correct value for the deployment target (`public`, `transparent`, `local`, or `remote`)
+- [ ] `provider` URL is set when using `transparent` or `remote` mode
+- [ ] `clientId` is configured when using `remote` mode
+- [ ] `expectedAudience` is set when using `transparent` mode
+
+**Security**
+
+- [ ] No secrets are hardcoded in source files -- all loaded from environment variables
+- [ ] Vault encryption secret is a strong random value
+- [ ] Production deployments use Redis or Vercel KV for session storage, not in-memory
+
+**Runtime**
+
+- [ ] Server starts without auth-related errors in the console
+- [ ] Tokens are validated correctly (test with a valid and an invalid token)
+- [ ] Downstream credential vault returns tokens for configured providers
+- [ ] Multi-app configurations route requests to the correct auth mode per app
+
+## Troubleshooting
+
+| Problem                                 | Cause                                                                        | Solution                                                                                          |
+| --------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `JWKS fetch failed` error on startup    | The `provider` URL is unreachable or does not serve `/.well-known/jwks.json` | Verify the provider URL is correct and accessible from the server; check network/firewall rules   |
+| Tokens rejected with `invalid audience` | The `expectedAudience` value does not match the `aud` claim in the token     | Align the `expectedAudience` config with the audience value your identity provider sets in tokens |
+| Sessions lost after server restart      | Using the default in-memory session store in production                      | Switch to Redis or Vercel KV session store via `configure-session` reference                      |
+| `VAULT_SECRET is not defined` error     | The vault encryption secret environment variable is missing                  | Set `VAULT_SECRET` in your environment or `.env` file before starting the server                  |
+| OAuth redirect fails in local dev       | `remote` mode requires HTTPS and reachable callback URLs                     | Set `NODE_ENV=development` to relax HTTPS requirements, or use a local OAuth mock server          |
+
+## Reference
+
+- Docs: [Authentication Overview](https://docs.agentfront.dev/frontmcp/authentication/overview)
+- Related skills: `configure-session`, `create-plugin`

package/catalog/frontmcp-config/references/configure-elicitation.md

@@ -0,0 +1,178 @@
+# Configuring Elicitation
+
+Elicitation allows tools to request interactive input from users mid-execution — confirmations, choices, or structured form data.
+
+## When to Use This Skill
+
+### Must Use
+
+- Tools need user confirmation before destructive actions (delete, deploy, overwrite)
+- Building interactive multi-step workflows that require user decisions mid-execution
+- Tools need structured form input from the user during execution (e.g., parameter selection, file choice)
+
+### Recommended
+
+- Adding a safety gate to tools that modify external systems (databases, APIs, deployments)
+- Implementing approval flows where a tool must get explicit consent before proceeding
+- Multi-instance production deployments where elicitation state must be shared via Redis
+
+### Skip When
+
+- Tools are fully autonomous and never need user input -- elicitation adds overhead when unused
+- The MCP client does not support elicitation -- check client capabilities first (see Notes section)
+- Only need input validation, not mid-execution prompts -- use Zod input schemas on the `@Tool` decorator
+
+> **Decision:** Use this skill when tools need to pause execution and request interactive input from the user; skip if all tools run autonomously without user interaction.
+
+## 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
+```
+
+## Common Patterns
+
+| Pattern                      | Correct                                                                 | Incorrect                                                        | Why                                                                                                              |
+| ---------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Handling unsupported clients | Check `if (!confirmation)` after `this.elicit()` and provide a fallback | Assuming `this.elicit()` always returns a value                  | Not all MCP clients support elicitation; `undefined` is returned when the client cannot handle the request       |
+| Schema for confirmation      | Use `{ confirmed: { type: 'boolean' } }` in `requestedSchema`           | Using a plain string prompt without a schema                     | Structured schemas let the client render proper UI controls (checkboxes, dropdowns) instead of free-text input   |
+| Redis for production         | Set `elicitation: { enabled: true, redis: { provider: 'redis', ... } }` | Using in-memory elicitation state in a multi-instance deployment | In-memory state is per-process; if the response arrives at a different instance, the elicitation context is lost |
+| Enabled flag                 | Explicitly set `elicitation: { enabled: true }`                         | Omitting the `enabled` field and expecting elicitation to work   | Elicitation is disabled by default (`enabled: false`) to minimize resource overhead                              |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `elicitation.enabled` is set to `true` in the `@FrontMcp` decorator
+- [ ] For production/multi-instance: `elicitation.redis` is configured with a valid Redis provider
+- [ ] The `requestedSchema` in `this.elicit()` calls uses valid JSON Schema objects
+
+### Runtime
+
+- [ ] Tool execution pauses when `this.elicit()` is called and the client supports elicitation
+- [ ] The user sees a prompt or form matching the requested schema
+- [ ] After the user responds, `this.elicit()` returns the structured data and the tool resumes
+- [ ] When the client does not support elicitation, `this.elicit()` returns `undefined` and the tool handles the fallback gracefully
+
+### Integration
+
+- [ ] MCP client under test advertises elicitation support in its capabilities
+- [ ] Destructive tools have elicitation-based confirmation gates before proceeding
+
+## Troubleshooting
+
+| Problem                                           | Cause                                                                       | Solution                                                                                            |
+| ------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `this.elicit is not a function`                   | Elicitation is not enabled in the server configuration                      | Set `elicitation: { enabled: true }` in the `@FrontMcp` decorator                                   |
+| `this.elicit()` returns `undefined` immediately   | The connected MCP client does not support elicitation                       | Check client capabilities; provide a fallback code path for unsupported clients                     |
+| Elicitation works locally but fails in production | In-memory store loses state across multiple server instances                | Configure `elicitation.redis` to share elicitation state via Redis                                  |
+| User sees raw JSON instead of a form              | The MCP client renders the `requestedSchema` as raw data rather than a form | Use standard JSON Schema types (`boolean`, `string`, `enum`) that clients can render as UI controls |
+| Tool hangs indefinitely waiting for user response | No timeout configured and user never responds                               | Implement a timeout or cancellation mechanism in the tool logic to handle non-responsive users      |
+
+## Reference
+
+- [Elicitation Docs](https://docs.agentfront.dev/frontmcp/servers/elicitation)
+- Related skills: `configure-http`, `configure-transport`, `setup-redis`, `create-tool`