@frontmcp/skills 1.0.0-beta.10 → 1.0.0-beta.12

package/catalog/frontmcp-config/SKILL.md

@@ -52,16 +52,24 @@ Entry point for configuring FrontMCP servers. This skill helps you find the righ
 
 ## 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                       |
+| 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
 
@@ -73,14 +81,19 @@ Server (@FrontMcp)     ← Global defaults
        └── 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) |
+| 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
 

package/catalog/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

@@ -1,3 +1,8 @@
+---
+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.

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

@@ -1,3 +1,8 @@
+---
+name: configure-elicitation
+description: Configure interactive user input during tool execution for confirmations, choices, and forms
+---
+
 # Configuring Elicitation
 
 Elicitation allows tools to request interactive input from users mid-execution — confirmations, choices, or structured form data.

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

@@ -1,3 +1,8 @@
+---
+name: configure-http
+description: Configure HTTP server port, CORS policy, unix sockets, and entry path prefix
+---
+
 # Configuring HTTP Options
 
 Configure the HTTP server — port, CORS policy, unix sockets, and entry path prefix.

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

@@ -1,3 +1,8 @@
+---
+name: configure-session
+description: Set up session storage with Redis or Vercel KV for persistent user state across requests
+---
+
 # 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.

package/catalog/frontmcp-config/references/configure-throttle-guard-config.md

@@ -1,3 +1,8 @@
+---
+name: configure-throttle-guard-config
+description: Complete GuardConfig interface reference for rate limiting, concurrency, and IP filtering
+---
+
 # GuardConfig Full Reference
 
 ## Complete Configuration

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

@@ -1,3 +1,8 @@
+---
+name: configure-throttle
+description: Protect servers with rate limiting, concurrency control, execution timeouts, and IP filtering
+---
+
 # Configuring Throttle, Rate Limits, and IP Filtering
 
 Protect your FrontMCP server with rate limiting, concurrency control, execution timeouts, and IP filtering — at both server and per-tool levels.

package/catalog/frontmcp-config/references/configure-transport-protocol-presets.md

@@ -1,3 +1,8 @@
+---
+name: configure-transport-protocol-presets
+description: Reference for legacy, modern, stateless, and minimal transport protocol presets
+---
+
 # Transport Protocol Presets Reference
 
 ## Preset Configurations

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

@@ -1,3 +1,8 @@
+---
+name: configure-transport
+description: Configure client transport protocols including SSE, Streamable HTTP, and stateless API modes
+---
+
 # Configuring Transport
 
 Configure how clients connect to your FrontMCP server — SSE, Streamable HTTP, stateless API, or a combination.

package/catalog/frontmcp-config/references/setup-redis.md

@@ -1,3 +1,8 @@
+---
+name: setup-redis
+description: Cross-reference to the full Redis configuration guide in frontmcp-setup
+---
+
 # Redis Setup Reference
 
 > This reference is maintained in `frontmcp-setup/references/setup-redis.md`.

package/catalog/frontmcp-config/references/setup-sqlite.md

@@ -1,3 +1,8 @@
+---
+name: setup-sqlite
+description: Cross-reference to the full SQLite configuration guide in frontmcp-setup
+---
+
 # SQLite Setup Reference
 
 > This reference is maintained in `frontmcp-setup/references/setup-sqlite.md`.

package/catalog/frontmcp-deployment/SKILL.md

@@ -53,15 +53,40 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 
 ## Scenario Routing Table
 
-| Scenario                                          | Skill                  | Description                                                             |
-| ------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------- |
-| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`       | Node.js with stdio or HTTP transport, PM2/Docker for process management |
-| Serverless with zero config and Vercel KV         | `deploy-to-vercel`     | Vercel Functions with Streamable HTTP, Vercel KV for storage            |
-| AWS serverless with API Gateway                   | `deploy-to-lambda`     | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache      |
-| Edge computing with global distribution           | `deploy-to-cloudflare` | Cloudflare Workers with KV or Durable Objects for storage               |
-| Standalone executable binary for distribution     | `build-for-cli`        | Single-binary CLI with stdio transport, embedded storage                |
-| Run MCP in a web browser                          | `build-for-browser`    | Browser-compatible bundle with in-memory transport                      |
-| Embed MCP into an existing Node.js application    | `build-for-sdk`        | Library build for programmatic usage without standalone server          |
+| Scenario                                          | Skill                       | Description                                                             |
+| ------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
+| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`            | Node.js with stdio or HTTP transport, PM2/Docker for process management |
+| Serverless with zero config and Vercel KV         | `deploy-to-vercel`          | Vercel Functions with Streamable HTTP, Vercel KV for storage            |
+| AWS serverless with API Gateway                   | `deploy-to-lambda`          | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache      |
+| Edge computing with global distribution           | `deploy-to-cloudflare`      | Cloudflare Workers with KV or Durable Objects for storage               |
+| Standalone executable binary for distribution     | `build-for-cli`             | Single-binary CLI with stdio transport, embedded storage                |
+| Run MCP in a web browser                          | `build-for-browser`         | Browser-compatible bundle with in-memory transport                      |
+| Embed MCP into an existing Node.js application    | `build-for-sdk`             | Library build for programmatic usage without standalone server          |
+| Write a Dockerfile for Node.js deployment         | `deploy-to-node-dockerfile` | Dockerfile configuration for Node.js deployment                         |
+| Configure Vercel-specific settings (vercel.json)  | `deploy-to-vercel-config`   | Vercel-specific configuration (vercel.json)                             |
+
+### CLI Commands for Deployment and Operations
+
+Beyond `frontmcp build`, the CLI provides commands for the full deployment lifecycle:
+
+| Command                      | Description                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `frontmcp build -t <target>` | Build for target: `node`, `vercel`, `lambda`, `cloudflare`, `cli`, `browser`, `sdk` |
+| `frontmcp build -t cli --js` | Build CLI as JS bundle (instead of native binary via SEA)                           |
+| `frontmcp start <name>`      | Start a named MCP server with supervisor (process management)                       |
+| `frontmcp stop <name>`       | Stop managed server (`-f` for force kill)                                           |
+| `frontmcp restart <name>`    | Restart managed server                                                              |
+| `frontmcp status [name]`     | Show process status (detail if name given, table if omitted)                        |
+| `frontmcp list`              | List all managed processes                                                          |
+| `frontmcp logs <name>`       | Tail log output (`-F` follow, `-n` lines)                                           |
+| `frontmcp socket <entry>`    | Start Unix socket daemon for local MCP server                                       |
+| `frontmcp service <action>`  | Install/uninstall systemd (Linux) or launchd (macOS) service                        |
+| `frontmcp install <source>`  | Install MCP app from npm, local path, or git                                        |
+| `frontmcp uninstall <name>`  | Remove installed MCP app                                                            |
+| `frontmcp configure <name>`  | Re-run setup questionnaire for installed app                                        |
+| `frontmcp doctor`            | Check Node.js/npm versions and tsconfig requirements                                |
+| `frontmcp inspector`         | Launch MCP Inspector for debugging                                                  |
+| `frontmcp init`              | Create or fix tsconfig.json for FrontMCP                                            |
 
 ## Target Comparison
 

package/catalog/frontmcp-deployment/references/build-for-browser.md

@@ -1,3 +1,8 @@
+---
+name: build-for-browser
+description: Build a FrontMCP server or client for browser environments and frontend frameworks
+---
+
 # Building for Browser
 
 Build your FrontMCP server or client for browser environments.

package/catalog/frontmcp-deployment/references/build-for-cli.md

@@ -1,3 +1,8 @@
+---
+name: build-for-cli
+description: Build a FrontMCP server as a standalone CLI binary using Node.js SEA or bundled JS
+---
+
 # Building a CLI Binary
 
 Build your FrontMCP server as a distributable CLI binary using Node.js Single Executable Applications (SEA) or as a bundled JS file.
@@ -92,6 +97,54 @@ frontmcp build --target cli
 node dist/my-server.cjs.js
 ```
 
+## Unix Socket Daemon Mode
+
+Run your MCP server as a local daemon accessible via Unix socket:
+
+```bash
+# Start daemon in foreground
+frontmcp socket ./src/main.ts -s ~/.frontmcp/sockets/my-app.sock
+
+# Start daemon in background
+frontmcp socket ./src/main.ts -b --db ~/.my-tool/data.db
+
+# Default socket path: ~/.frontmcp/sockets/{app-name}.sock
+```
+
+The daemon accepts JSON-RPC requests over HTTP via the Unix socket, making it ideal for local MCP clients (Claude Code, IDE extensions) that need persistent tool access without a TCP port.
+
+## Process Management
+
+Manage long-running MCP server processes with built-in supervisor commands:
+
+```bash
+# Start a named server (auto-restarts on crash)
+frontmcp start my-server -e ./src/main.ts --max-restarts 5
+
+# Monitor
+frontmcp status my-server    # Detailed status for one server
+frontmcp status              # Table of all managed servers
+frontmcp list                # List all managed processes
+frontmcp logs my-server -F   # Tail logs (follow mode)
+
+# Control
+frontmcp restart my-server
+frontmcp stop my-server      # Graceful shutdown (SIGTERM)
+frontmcp stop my-server -f   # Force kill (SIGKILL)
+```
+
+## System Service Installation
+
+Install your MCP server as a system service for automatic startup:
+
+```bash
+# Install as systemd service (Linux) or launchd service (macOS)
+frontmcp service install my-server
+
+# Uninstall service
+frontmcp service uninstall my-server
+```
+
 ## Common Patterns
 
 | Pattern               | Correct                                             | Incorrect                        | Why                                                         |

package/catalog/frontmcp-deployment/references/build-for-sdk.md

@@ -1,3 +1,8 @@
+---
+name: build-for-sdk
+description: Build a FrontMCP server as an embeddable library with create() and connect() APIs
+---
+
 # Building as an SDK Library
 
 Build your FrontMCP server as an embeddable library that runs without an HTTP server. Use `create()` for flat-config setup or `connect()` for platform-specific tool formatting (OpenAI, Claude, LangChain, Vercel AI).

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-cloudflare
+description: Deploy a FrontMCP server to Cloudflare Workers with KV, D1, and Durable Objects
+---
+
 # Deploy a FrontMCP Server to Cloudflare Workers
 
 This skill guides you through deploying a FrontMCP server to Cloudflare Workers.

package/catalog/frontmcp-deployment/references/deploy-to-lambda.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-lambda
+description: Deploy a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK
+---
+
 # Deploy a FrontMCP Server to AWS Lambda
 
 This skill walks you through deploying a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK.

package/catalog/frontmcp-deployment/references/deploy-to-node-dockerfile.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-node-dockerfile
+description: Multi-stage Dockerfile for building and running a FrontMCP server in production
+---
+
 # ---- Build Stage ----
 
 FROM node:24-alpine AS builder

package/catalog/frontmcp-deployment/references/deploy-to-node.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-node
+description: Deploy a FrontMCP server as a standalone Node.js app with Docker and process managers
+---
+
 # Deploy a FrontMCP Server to Node.js
 
 This skill walks you through deploying a FrontMCP server as a standalone Node.js application, optionally containerized with Docker for production use.

package/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-vercel-config
+description: Reference vercel.json configuration for deploying a FrontMCP server to Vercel
+---
+
 {
 "$schema": "https://openapi.vercel.sh/vercel.json",
 "framework": null,

package/catalog/frontmcp-deployment/references/deploy-to-vercel.md

@@ -1,3 +1,8 @@
+---
+name: deploy-to-vercel
+description: Deploy a FrontMCP server to Vercel serverless functions with Vercel KV storage
+---
+
 # Deploy a FrontMCP Server to Vercel
 
 This skill guides you through deploying a FrontMCP server to Vercel serverless functions with Vercel KV for persistent storage.

package/catalog/frontmcp-development/SKILL.md

@@ -40,20 +40,25 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ## Scenario Routing Table
 
-| Scenario                                                 | Skill                     | Description                                                                                   |
-| -------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
-| Expose an executable action that AI clients can call     | `create-tool`             | Class-based or function-style tools with Zod input/output validation                          |
-| Expose read-only data via a URI                          | `create-resource`         | Static resources or URI template resources for dynamic data                                   |
-| Create a reusable conversation template or system prompt | `create-prompt`           | Prompt entries with arguments and multi-turn message sequences                                |
-| Build an autonomous AI loop that orchestrates tools      | `create-agent`            | Agent entries with LLM config, inner tools, and swarm handoff                                 |
-| Register shared services or configuration via DI         | `create-provider`         | Dependency injection tokens, lifecycle hooks, factory providers                               |
-| Run a background task with progress and retries          | `create-job`              | Job entries with attempt tracking, retry config, and progress                                 |
-| Chain multiple jobs into a sequential pipeline           | `create-workflow`         | Workflow entries that compose jobs with data passing                                          |
-| Write instruction-only AI guidance (no code execution)   | `create-skill`            | Skill entries with markdown instructions from files, strings, or URLs                         |
-| Write AI guidance that also orchestrates tools           | `create-skill-with-tools` | Skill entries that combine instructions with registered tools                                 |
-| Look up any decorator signature or option                | `decorators-guide`        | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more           |
-| Integrate an external API via OpenAPI spec               | `official-adapters`       | OpenapiAdapter with auth, polling, inline specs, and multiple API composition                 |
-| Use official plugins (caching, remember, feature flags)  | `official-plugins`        | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta) |
+| Scenario                                                 | Skill                             | Description                                                                                   |
+| -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
+| Expose an executable action that AI clients can call     | `create-tool`                     | Class-based or function-style tools with Zod input/output validation                          |
+| Expose read-only data via a URI                          | `create-resource`                 | Static resources or URI template resources for dynamic data                                   |
+| Create a reusable conversation template or system prompt | `create-prompt`                   | Prompt entries with arguments and multi-turn message sequences                                |
+| Build an autonomous AI loop that orchestrates tools      | `create-agent`                    | Agent entries with LLM config, inner tools, and swarm handoff                                 |
+| Register shared services or configuration via DI         | `create-provider`                 | Dependency injection tokens, lifecycle hooks, factory providers                               |
+| Run a background task with progress and retries          | `create-job`                      | Job entries with attempt tracking, retry config, and progress                                 |
+| Chain multiple jobs into a sequential pipeline           | `create-workflow`                 | Workflow entries that compose jobs with data passing                                          |
+| Write instruction-only AI guidance (no code execution)   | `create-skill`                    | Skill entries with markdown instructions from files, strings, or URLs                         |
+| Write AI guidance that also orchestrates tools           | `create-skill-with-tools`         | Skill entries that combine instructions with registered tools                                 |
+| Look up any decorator signature or option                | `decorators-guide`                | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more           |
+| Integrate an external API via OpenAPI spec               | `official-adapters`               | OpenapiAdapter with auth, polling, inline specs, and multiple API composition                 |
+| Use official plugins (caching, remember, feature flags)  | `official-plugins`                | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta) |
+| Connect to an external data source via a custom adapter  | `create-adapter`                  | Create custom adapters for external data sources                                              |
+| Configure LLM settings for an agent component            | `create-agent-llm-config`         | Configure LLM settings for agent components                                                   |
+| Add will/did/around lifecycle hooks to a plugin          | `create-plugin-hooks`             | Add lifecycle hooks to plugins (will/did/around)                                              |
+| Annotate tools with client hints for AI clients          | `create-tool-annotations`         | Add MCP tool annotations for client hints                                                     |
+| Define typed output schemas for tool responses           | `create-tool-output-schema-types` | Define typed output schemas for tools                                                         |
 
 ## Recommended Reading Order
 

package/catalog/frontmcp-development/references/create-adapter.md

@@ -1,3 +1,8 @@
+---
+name: create-adapter
+description: Build adapters that generate MCP tools and resources from external sources automatically
+---
+
 # Creating Custom Adapters
 
 Build adapters that automatically generate MCP tools, resources, and prompts from external sources — databases, GraphQL schemas, proprietary APIs, or any definition format.

package/catalog/frontmcp-development/references/create-agent-llm-config.md

@@ -1,3 +1,8 @@
+---
+name: create-agent-llm-config
+description: Reference for supported LLM provider configurations including Anthropic and OpenAI
+---
+
 # Agent LLM Configuration Reference
 
 ## Supported Providers

package/catalog/frontmcp-development/references/create-agent.md

@@ -1,3 +1,8 @@
+---
+name: create-agent
+description: Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools
+---
+
 # Creating an Autonomous Agent
 
 Agents are autonomous AI entities that use an LLM to reason, plan, and invoke inner tools to accomplish goals. In FrontMCP, agents are TypeScript classes that extend `AgentContext`, decorated with `@Agent`, and registered on a `@FrontMcp` server or inside an `@App`.

package/catalog/frontmcp-development/references/create-job.md

@@ -1,3 +1,8 @@
+---
+name: create-job
+description: Create long-running background jobs with retry policies, progress tracking, and permissions
+---
+
 # Creating Jobs
 
 Jobs are long-running background tasks with built-in retry policies, progress tracking, and permission controls. Unlike tools (which execute synchronously within a request), jobs run asynchronously and persist their state across retries and restarts.

package/catalog/frontmcp-development/references/create-plugin-hooks.md

@@ -1,3 +1,8 @@
+---
+name: create-plugin-hooks
+description: Intercept and extend FrontMCP flows using before, after, around, and stage hook decorators
+---
+
 # Creating Plugins with Flow Lifecycle Hooks
 
 Plugins intercept and extend FrontMCP flows using lifecycle hook decorators. Every flow (tool calls, resource reads, prompt gets, etc.) is composed of **stages**, and hooks let you run logic before, after, around, or instead of any stage.
@@ -58,6 +63,42 @@ const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');
 | `http:request`             | HTTP request handling    |
 | `agents:call-agent`        | Agent invocation         |
 
+## Server Lifecycle Hooks
+
+In addition to flow-based hooks, plugins can register callbacks for server lifecycle events. These are not decorator-based — they use the `scope.onServerStarted()` API.
+
+### `onServerStarted()`
+
+Runs after the HTTP server is fully initialized and listening. Use for warming caches, starting background indexing, or logging readiness.
+
+```typescript
+import { Plugin, DynamicPlugin } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'cache-warmer',
+  description: 'Warms caches when the server starts',
+  providers: [CacheService],
+})
+class CacheWarmerPlugin extends DynamicPlugin<{}> {
+  constructor(scope: ScopeEntry) {
+    super();
+    // Register lifecycle callback
+    scope.onServerStarted(async () => {
+      const cache = this.get(CacheService);
+      await cache.warmAll();
+      console.log('Cache warmed successfully');
+    });
+  }
+}
+```
+
+**Signature:** `scope.onServerStarted(callback: () => void | Promise<void>): void`
+
+- Callbacks are stored and executed after `server.start()` completes
+- Supports both sync and async callbacks
+- Multiple callbacks are executed in registration order with `await`
+- Typically used in plugin constructors or provider `onInit()` methods
+
 ## Pre-Built Hook Type Exports
 
 For convenience, FrontMCP exports typed aliases so you do not need to call `FlowHooksOf` directly: