@frontmcp/skills 0.0.1 → 1.0.0-beta.11

package/README.md

@@ -39,14 +39,14 @@ export default class Server {}
 
 ## Installation
 
-**Node.js 22+** required (24 recommended).
+**Node.js 24+** required.
 
 ```bash
 # New project (recommended)
 npx frontmcp create my-app
 
 # Existing project
-npm i -D frontmcp @types/node@^22
+npm i -D frontmcp @types/node@^24
 npx frontmcp init
 ```
 

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,156 @@
+---
+name: frontmcp-config
+description: 'Use when you want to configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, add authentication, configure JWT, or set up OAuth. The skill for server CONFIGURATION.'
+tags: [router, config, transport, http, auth, session, redis, sqlite, throttle, guide]
+category: config
+targets: [all]
+bundle: [recommended, full]
+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 24+ 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                          |
+| Understand auth mode details (public/transparent/local/remote) | `configure-auth-modes`                 | Authentication mode details (public, transparent, local, remote) |
+| Fine-tune guard configuration for throttling                   | `configure-throttle-guard-config`      | Advanced guard configuration for throttling                      |
+| Use transport protocol presets                                 | `configure-transport-protocol-presets` | Transport protocol preset configurations                         |
+| Split apps into separate scopes (`splitByApp`)                 | `decorators-guide`                     | Per-app scope and basePath isolation on `@FrontMcp`              |
+| Enable widget-to-host communication (ext-apps)                 | `decorators-guide`                     | `extApps` host capabilities, session validation, widget comms    |
+| Enable background jobs and workflows                           | `decorators-guide`                     | `jobs: { enabled: true, store? }` on `@FrontMcp`                 |
+| Configure pagination for list operations                       | `decorators-guide`                     | `pagination` defaults for `tools/list` endpoint                  |
+| Configure npm/ESM package loader for remote apps               | `decorators-guide`                     | `loader` config for `App.esm()` / `App.remote()` resolution      |
+
+## 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 (`@FrontMcp`)             | App (`@App`)          | Tool (`@Tool`)                              |
+| --------------------- | -------------------------------- | --------------------- | ------------------------------------------- |
+| Transport             | Yes                              | No                    | No                                          |
+| HTTP (CORS, port)     | Yes                              | No                    | No                                          |
+| Throttle (rate limit) | Yes (`throttle` global defaults) | No                    | Yes (`rateLimit`, `concurrency`, `timeout`) |
+| Auth mode             | Yes                              | Yes (override)        | No                                          |
+| Auth providers        | No                               | Yes (`authProviders`) | Yes (`authProviders`)                       |
+| Session store         | Yes                              | No                    | No                                          |
+| Elicitation           | Yes (enable: `elicitation`)      | No                    | Yes (usage: `this.elicit()`)                |
+| ExtApps               | Yes                              | No                    | No                                          |
+| Jobs / Workflows      | Yes (`jobs: { enabled }`)        | No                    | No                                          |
+| Pagination            | Yes                              | No                    | No                                          |
+| SplitByApp            | Yes                              | No                    | No                                          |
+
+## 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/{auth/configure-auth/references/auth-modes.md → frontmcp-config/references/configure-auth-modes.md}

@@ -1,3 +1,8 @@
+---
+name: configure-auth-modes
+description: Detailed comparison of public, transparent, remote, and managed auth modes
+---
+
 # Auth Modes Detailed Comparison
 
 ## Public Mode

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

@@ -0,0 +1,243 @@
+---
+name: configure-auth
+description: Set up authentication modes, credential vault, and OAuth flows for FrontMCP servers
+---
+
+# 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`