@frontmcp/skills 1.1.2 → 1.2.0

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

@@ -59,25 +59,47 @@ Not all FrontMCP features are available in browser environments:
 
 ## Usage with @frontmcp/react
 
-The browser build is commonly paired with `@frontmcp/react` for React applications:
+The browser build is commonly paired with `@frontmcp/react` for React applications. `FrontMcpProvider` takes a pre-created `DirectMcpServer` (via the SDK's `create()` factory) — not a `serverUrl`. Hooks for listing/invoking are `useListTools` / `useCallTool`:
 
 ```typescript
-import { FrontMcpProvider, useTools } from '@frontmcp/react';
+import { create } from '@frontmcp/sdk';
+import { FrontMcpProvider, useListTools, useCallTool } from '@frontmcp/react';
+
+// Create the server once (outside React) and pass the instance to the provider.
+const server = await create({
+  info: { name: 'browser-app', version: '1.0.0' },
+  // tools/resources/prompts as flat config (see build-for-sdk)
+  tools: [/* ... */],
+});
 
 function App() {
   return (
-    <FrontMcpProvider config={{ serverUrl: 'https://my-mcp.example.com' }}>
+    <FrontMcpProvider server={server}>
       <ToolUI />
     </FrontMcpProvider>
   );
 }
 
 function ToolUI() {
-  const { tools, callTool } = useTools();
-  // Use tools in your React components
+  // useListTools returns ToolInfo[] directly (live-updates from the provider's registry).
+  const tools = useListTools();
+  // useCallTool returns [callFn, state, reset]. Pass the tool name to the hook,
+  // and call the returned function with just the arguments object.
+  const [callGetWeather, weatherState] = useCallTool('get_weather');
+  return (
+    <ul>
+      {tools.map((t) => (
+        <li key={t.name}>
+          <button onClick={() => callGetWeather({})}>{t.name}</button>
+        </li>
+      ))}
+    </ul>
+  );
 }
 ```
 
+For connecting to a remote MCP server (HTTP), create a server-bound `DirectMcpServer` via `connect()` from `@frontmcp/sdk` and pass that instance to the provider.
+
 ## Browser vs Node vs SDK Target
 
 | Aspect      | `--target browser` | `--target node`   | `--target sdk`      |
@@ -99,13 +121,14 @@ ls dist/browser/
 
 ## Common Patterns
 
-| Pattern           | Correct                                  | Incorrect                         | Why                                        |
-| ----------------- | ---------------------------------------- | --------------------------------- | ------------------------------------------ |
-| Crypto usage      | `@frontmcp/utils` (uses WebCrypto)       | `node:crypto`                     | `node:crypto` is not available in browsers |
-| Storage           | In-memory stores or remote API           | SQLite / Redis directly           | No filesystem or native TCP in browsers    |
-| File system ops   | Avoid `@frontmcp/utils` fs functions     | `readFile()`, `writeFile()`       | fs utilities throw in browser environments |
-| Entry file        | Separate browser entry (`src/client.ts`) | Reusing server entry point        | Server entry may import Node-only modules  |
-| Server connection | `FrontMcpProvider` with `serverUrl`      | Direct `connect()` with localhost | Browser needs a remote URL, not localhost  |
+| Pattern           | Correct                                           | Incorrect                                   | Why                                                    |
+| ----------------- | ------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
+| Crypto usage      | `@frontmcp/utils` (uses WebCrypto)                | `node:crypto`                               | `node:crypto` is not available in browsers             |
+| Storage           | In-memory stores or remote API                    | SQLite / Redis directly                     | No filesystem or native TCP in browsers                |
+| File system ops   | Avoid `@frontmcp/utils` fs functions              | `readFile()`, `writeFile()`                 | fs utilities throw in browser environments             |
+| Entry file        | Separate browser entry (`src/client.ts`)          | Reusing server entry point                  | Server entry may import Node-only modules              |
+| Provider props    | `<FrontMcpProvider server={await create({...})}>` | `<FrontMcpProvider config={{ serverUrl }}>` | Real prop is `server: DirectMcpServer`; no `serverUrl` |
+| Tool listing hook | `useListTools()` -> `{ data: { tools } }`         | `useTools()` -> `{ tools, callTool }`       | `useTools` is not exported; real hooks are split       |
 
 ## Verification Checklist
 
@@ -139,11 +162,11 @@ ls dist/browser/
 
 ## Examples
 
-| Example                                                                                               | Level        | Description                                                                                           |
-| ----------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
-| [`browser-build-with-custom-entry`](../examples/build-for-browser/browser-build-with-custom-entry.md) | Intermediate | Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.          |
-| [`browser-crypto-and-storage`](../examples/build-for-browser/browser-crypto-and-storage.md)           | Advanced     | Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments. |
-| [`react-provider-setup`](../examples/build-for-browser/react-provider-setup.md)                       | Basic        | Connect a React application to a remote FrontMCP server using `@frontmcp/react`.                      |
+| Example                                                                                               | Level        | Description                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`browser-build-with-custom-entry`](../examples/build-for-browser/browser-build-with-custom-entry.md) | Intermediate | Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports. Re-export the real `@frontmcp/react` symbols (`useListTools`, `useListResources`, `useCallTool`) — `useTools`/`useResources` do not exist. |
+| [`browser-crypto-and-storage`](../examples/build-for-browser/browser-crypto-and-storage.md)           | Advanced     | Use `@frontmcp/utils` crypto in the browser, and create the FrontMCP server with `create()` from `@frontmcp/sdk` so the React provider can consume it via the `server` prop.                                                            |
+| [`react-provider-setup`](../examples/build-for-browser/react-provider-setup.md)                       | Basic        | Connect a React application to a FrontMCP server using `@frontmcp/react`. `FrontMcpProvider` takes a `DirectMcpServer` instance via the `server` prop — there is no `serverUrl` option.                                                 |
 
 > See all examples in [`examples/build-for-browser/`](../examples/build-for-browser/)
 

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

@@ -57,7 +57,7 @@ frontmcp build --target cli --js               # JS bundle only (no SEA)
 
 ## Requirements
 
-- **Node.js 24+** required for SEA support
+- **Node.js 24+** required for the SEA path (`frontmcp build --target cli`). The plain JS bundle path (`--target cli --js`) only requires the Node version your entry file supports.
 - The entry file must export or instantiate a `@FrontMcp` decorated class
 - SEA binaries are platform-specific (build on macOS for macOS, Linux for Linux)
 
@@ -147,13 +147,13 @@ frontmcp service uninstall my-server
 
 ## Common Patterns
 
-| Pattern               | Correct                                             | Incorrect                        | Why                                                         |
-| --------------------- | --------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
-| Node.js version       | Node.js 24+ for SEA builds                          | Node.js 18 or 20                 | SEA support requires Node.js 24+                            |
-| Entry file            | Export or instantiate a `@FrontMcp` decorated class | Export a plain function          | The build expects a FrontMcp entry point                    |
-| Transport for CLI     | `socketPath` or stdin/stdout                        | TCP port binding                 | CLI tools run locally; ports may conflict                   |
-| Cross-platform binary | Build on each target OS separately                  | Build on macOS and ship to Linux | SEA binaries are platform-specific                          |
-| JS-only bundle        | `frontmcp build --target cli --js`                  | `frontmcp build --target node`   | `--target node` assumes server deployment with node_modules |
+| Pattern               | Correct                                              | Incorrect                        | Why                                                         |
+| --------------------- | ---------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| Node.js version       | Node.js 24+ for SEA builds (not required for `--js`) | Using SEA flow on Node < 24      | SEA support requires Node.js 24+; `--js` bundles do not     |
+| Entry file            | Export or instantiate a `@FrontMcp` decorated class  | Export a plain function          | The build expects a FrontMcp entry point                    |
+| Transport for CLI     | `socketPath` or stdin/stdout                         | TCP port binding                 | CLI tools run locally; ports may conflict                   |
+| Cross-platform binary | Build on each target OS separately                   | Build on macOS and ship to Linux | SEA binaries are platform-specific                          |
+| JS-only bundle        | `frontmcp build --target cli --js`                   | `frontmcp build --target node`   | `--target node` assumes server deployment with node_modules |
 
 ## Verification Checklist
 

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

@@ -56,33 +56,49 @@ frontmcp build --target cloudflare
 This produces:
 
 ```text
-dist/
-  main.js      # Your compiled server (CommonJS)
-  index.js     # Cloudflare handler wrapper
-wrangler.toml  # Wrangler configuration
+dist/cloudflare/
+  index.js       # Cloudflare Workers entry (CommonJS) — wraps your @FrontMcp server
+  main.js        # Your compiled server module (CommonJS)
+wrangler.toml    # Wrangler configuration (overwritten on every build)
 ```
 
 Cloudflare Workers use CommonJS (not ESM). The build command sets `--module commonjs` automatically.
 
+> **Important:** The Cloudflare adapter sets `alwaysWriteConfig: true` and overwrites the entire `wrangler.toml` on every build with the three-line template below. Hand-edited bindings (`[[kv_namespaces]]`, `[vars]`, `[[d1_databases]]`, etc.) WILL be erased the next time you run `frontmcp build --target cloudflare`. Configure `name` and `compatibility_date` via your `frontmcp.config` file's `deployments[].wrangler` section, and keep bindings in a separate config file referenced from your toolchain (or re-add them after each build).
+
 ## Step 3: Configure wrangler.toml
 
-The generated `wrangler.toml`:
+The build always writes exactly this:
 
 ```toml
 name = "frontmcp-worker"
-main = "dist/index.js"
+main = "dist/cloudflare/index.js"
 compatibility_date = "2024-01-01"
+```
 
-[vars]
-NODE_ENV = "production"
+`name` and `compatibility_date` come from `frontmcp.config.{ts,js}`'s `deployments` array. Example:
+
+```ts
+// frontmcp.config.ts
+export default {
+  deployments: [
+    {
+      target: 'cloudflare',
+      wrangler: {
+        name: 'my-worker',
+        compatibilityDate: '2025-01-15',
+      },
+    },
+  ],
+};
 ```
 
-To add KV storage for sessions and state:
+To add KV storage or other bindings, append them AFTER each build (or use a wrapper script that runs the build then concatenates a `wrangler.bindings.toml` you maintain separately):
 
 ```toml
-name = "frontmcp-worker"
-main = "dist/index.js"
-compatibility_date = "2024-01-01"
+name = "my-worker"
+main = "dist/cloudflare/index.js"
+compatibility_date = "2025-01-15"
 
 [[kv_namespaces]]
 binding = "FRONTMCP_KV"
@@ -103,7 +119,7 @@ Copy the returned `id` into your `wrangler.toml`.
 ## Step 4: Configure the Server
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'MyApp' })
 class MyApp {}
@@ -112,7 +128,7 @@ class MyApp {}
   info: { name: 'my-worker', version: '1.0.0' },
   apps: [MyApp],
   transport: {
-    type: 'sse',
+    protocol: 'legacy', // preset: 'legacy' | 'modern' | 'stateless-api' | 'full' — see configure-transport
   },
 })
 class MyServer {}
@@ -120,7 +136,9 @@ class MyServer {}
 export default MyServer;
 ```
 
-For KV-backed session storage, use the Cloudflare KV or Upstash Redis provider.
+> **Note:** The transport schema uses `protocol`, not `type`. The preset string accepts `'legacy'` (default), `'modern'`, `'stateless-api'`, or `'full'`. For granular control, pass an object instead, e.g. `protocol: { sse: true, streamable: true }`. `transport: { type: 'sse' }` will fail Zod validation at startup.
+
+For session storage, use Upstash Redis (HTTP) via `redis: { provider: 'vercel-kv' }` or wire Cloudflare KV directly inside your tools — the SDK does not include a built-in Cloudflare KV provider, and ioredis-style `redis: { ... }` configs are rejected by the Cloudflare adapter at build time (no Node TCP on Workers).
 
 ## Step 5: Deploy
 
@@ -143,8 +161,8 @@ wrangler domains add mcp.example.com
 ## Step 6: Verify
 
 ```bash
-# Health check
-curl https://frontmcp-worker.your-subdomain.workers.dev/health
+# Health check (FrontMCP serves /healthz by default; /health is a legacy alias)
+curl https://frontmcp-worker.your-subdomain.workers.dev/healthz
 
 # Test MCP endpoint
 curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
@@ -179,13 +197,14 @@ curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
 
 ## Common Patterns
 
-| Pattern            | Correct                                     | Incorrect                         | Why                                                |
-| ------------------ | ------------------------------------------- | --------------------------------- | -------------------------------------------------- |
-| Module format      | CommonJS (`main = "dist/index.js"`)         | ESM (`type = "module"`)           | FrontMCP Cloudflare builds emit CommonJS           |
-| Storage binding    | `[[kv_namespaces]]` with matching `binding` | Hardcoded KV namespace ID in code | Bindings are injected at runtime by Workers        |
-| Compatibility date | Set to a recent, tested date                | Omitting `compatibility_date`     | Workers behavior changes across compat dates       |
-| Build command      | `frontmcp build --target cloudflare`        | `frontmcp build` (no target)      | Default target is Node.js, not Workers             |
-| Secrets            | `wrangler secret put MY_SECRET`             | Storing secrets in `[vars]`       | `[vars]` are visible in plaintext in the dashboard |
+| Pattern            | Correct                                                                    | Incorrect                         | Why                                                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Module format      | CommonJS (`main = "dist/cloudflare/index.js"`)                             | ESM (`type = "module"`)           | FrontMCP Cloudflare builds emit CommonJS at this exact path; the build overwrites `wrangler.toml` to enforce it                          |
+| Transport key      | `transport: { protocol: 'modern' }` (or `{ sse: true, streamable: true }`) | `transport: { type: 'sse' }`      | The schema field is `protocol`; valid presets are `'legacy' \| 'modern' \| 'stateless-api' \| 'full'`, or pass a `ProtocolConfig` object |
+| Storage binding    | `[[kv_namespaces]]` with matching `binding`                                | Hardcoded KV namespace ID in code | Bindings are injected at runtime by Workers                                                                                              |
+| Compatibility date | Set via `frontmcp.config.deployments[].wrangler.compatibilityDate`         | Hand-editing `wrangler.toml`      | The build overwrites `wrangler.toml`; config-driven values survive                                                                       |
+| Build command      | `frontmcp build --target cloudflare`                                       | `frontmcp build` (no target)      | Default target is Node.js, not Workers                                                                                                   |
+| Secrets            | `wrangler secret put MY_SECRET`                                            | Storing secrets in `[vars]`       | `[vars]` are visible in plaintext in the dashboard                                                                                       |
 
 ## Verification Checklist
 

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

@@ -36,6 +36,13 @@ This skill walks you through deploying a FrontMCP server to AWS Lambda with API
 - SAM CLI installed: `brew install aws-sam-cli` (macOS) or see AWS docs
 - Node.js 24 or later
 - A FrontMCP project ready to build
+- **Peer dependency:** `@codegenie/serverless-express` installed in your project. The Lambda adapter externalizes it at bundle time and validates its presence at build time:
+
+  ```bash
+  npm install @codegenie/serverless-express
+  ```
+
+  If it isn't installed, `frontmcp build --target lambda` fails with a clear error before producing artifacts.
 
 ## Step 1: Build for Lambda
 
@@ -43,7 +50,16 @@ This skill walks you through deploying a FrontMCP server to AWS Lambda with API
 frontmcp build --target lambda
 ```
 
-This produces a Lambda-compatible output with a single handler file optimized for cold-start performance, minimized bundle size with tree-shaking, and a `template.yaml` scaffold for SAM.
+This produces a Lambda-compatible output under `dist/lambda/`:
+
+```text
+dist/lambda/
+├── handler.cjs               # Bundled Lambda handler (CJS, exports `handler`)
+├── serverless-setup.js       # Sets FRONTMCP_SERVERLESS=1 before decorators
+└── ...                       # Chunks split out by rspack
+```
+
+The handler is auto-generated. It calls `getServerlessHandlerAsync()` from `@frontmcp/sdk` and wraps the resulting Express app with `@codegenie/serverless-express`. You do **not** need to write a custom `lambda.ts` entry — the build produces `handler.cjs` with a working `handler` export. SAM/CDK reference it as `handler.handler`.
 
 ## Step 2: SAM Template
 
@@ -69,7 +85,7 @@ Resources:
     Type: AWS::Serverless::Function
     Properties:
       Handler: handler.handler
-      CodeUri: .
+      CodeUri: dist/lambda/
       Description: FrontMCP MCP server
       Architectures:
         - arm64
@@ -82,7 +98,7 @@ Resources:
         HealthCheck:
           Type: HttpApi
           Properties:
-            Path: /health
+            Path: /healthz
             Method: GET
       Environment:
         Variables:
@@ -143,16 +159,9 @@ Resources:
 
 ## Step 4: Handler Configuration
 
-FrontMCP generates a Lambda handler file (`handler.cjs` with a `handler` export) during the build step. In SAM/CDK, reference it as `handler.handler`. To customize the handler, create a `lambda.ts` entry point:
+`frontmcp build --target lambda` generates `dist/lambda/handler.cjs` with a `handler` export. In SAM and CDK, reference it as `handler.handler` and set `CodeUri`/`code.fromAsset` to `dist/lambda/`. There is no user-authored handler factory; the adapter wraps your `@FrontMcp` server with `@codegenie/serverless-express` automatically.
 
-```typescript
-import { createLambdaHandler } from '@frontmcp/adapters/lambda';
-import { AppModule } from './app.module';
-
-export const handler = createLambdaHandler(AppModule, {
-  streaming: false,
-});
-```
+If you need to customize behaviour (CORS, request mapping, streaming), do so in your `@FrontMcp` decorated server class — the same code runs locally with `frontmcp dev`, in containers with `--target node`, and in Lambda with `--target lambda`.
 
 ## Step 5: Environment Variables
 
@@ -202,14 +211,14 @@ If you prefer AWS CDK over SAM:
 
 ```typescript
 import * as cdk from 'aws-cdk-lib';
-import * as lambda from 'aws-cdk-lib/aws-lambda';
 import * as apigw from 'aws-cdk-lib/aws-apigatewayv2';
 import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
 
 const fn = new lambda.Function(this, 'FrontMcpHandler', {
   runtime: lambda.Runtime.NODEJS_24_X,
   handler: 'handler.handler',
-  code: lambda.Code.fromAsset('.'),
+  code: lambda.Code.fromAsset('dist/lambda'),
   memorySize: 512,
   timeout: cdk.Duration.seconds(30),
   architecture: lambda.Architecture.ARM_64,
@@ -239,8 +248,8 @@ aws cloudformation describe-stacks \
   --query "Stacks[0].Outputs[?OutputKey=='ApiEndpoint'].OutputValue" \
   --output text
 
-# Health check
-curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+# Health check (FrontMCP serves /healthz by default; /health is a legacy alias)
+curl https://abc123.execute-api.us-east-1.amazonaws.com/healthz
 ```
 
 ## Cold Start Mitigation
@@ -276,7 +285,7 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 | ------------------ | -------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | Build command      | `frontmcp build --target lambda`                               | `tsc` or generic bundler                | The Lambda target produces a single optimized handler with tree-shaking for cold-start performance |
 | Architecture       | `arm64` (Graviton)                                             | `x86_64`                                | ARM64 functions initialize faster and cost less per ms of compute                                  |
-| Handler path       | `handler.handler` in SAM template                              | `index.handler` or `src/lambda.handler` | The FrontMCP build outputs to `dist/`; mismatched paths cause 502 errors                           |
+| Handler path       | `handler.handler` with `CodeUri: dist/lambda/` in SAM          | `index.handler` or `src/lambda.handler` | The FrontMCP Lambda build emits `dist/lambda/handler.cjs`; mismatched paths cause 502 errors       |
 | Secrets management | SSM Parameter Store or Secrets Manager (`{{resolve:ssm:...}}`) | Plaintext env vars in `template.yaml`   | SSM/Secrets Manager encrypts values at rest and supports rotation                                  |
 | Redis connectivity | Lambda in same VPC as ElastiCache with security groups         | Public Redis endpoint from Lambda       | VPC peering ensures low latency and keeps traffic off the public internet                          |
 
@@ -284,8 +293,9 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 
 **Build**
 
+- [ ] `@codegenie/serverless-express` is listed in `package.json` (peer dep validated by the adapter)
 - [ ] `frontmcp build --target lambda` completes without errors
-- [ ] `handler.handler` exists and exports a `handler` function
+- [ ] `dist/lambda/handler.cjs` exists and exports a `handler` function
 
 **SAM / CDK**
 
@@ -295,7 +305,7 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 
 **Runtime**
 
-- [ ] `curl https://<api-id>.execute-api.<region>.amazonaws.com/health` returns `{"status":"ok"}`
+- [ ] `curl https://<api-id>.execute-api.<region>.amazonaws.com/healthz` returns `{"status":"ok"}`
 - [ ] CloudWatch Logs show successful invocations without errors
 - [ ] `NODE_ENV` is set to `production` in the function configuration
 
@@ -311,18 +321,19 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 | Problem                              | Cause                                                           | Solution                                                                                                  |
 | ------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | Timeout errors                       | Function timeout too low or waiting on unreachable resource     | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                       |
-| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler` matches `handler.handler`                                        |
+| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                     |
+| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                      | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                   |
 | Cold starts too slow                 | Low memory, x86 architecture, or large bundle                   | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                |
 | Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
 | `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
 
 ## Examples
 
-| Example                                                                                | Level        | Description                                                                                           |
-| -------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
-| [`cdk-deployment`](../examples/deploy-to-lambda/cdk-deployment.md)                     | Advanced     | Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management. |
-| [`lambda-handler-with-cors`](../examples/deploy-to-lambda/lambda-handler-with-cors.md) | Intermediate | Create a custom Lambda handler with an explicit API Gateway definition for CORS support.              |
-| [`sam-template-basic`](../examples/deploy-to-lambda/sam-template-basic.md)             | Basic        | Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.                         |
+| Example                                                                                | Level        | Description                                                                                                                                                                                                                                                                                |
+| -------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`cdk-deployment`](../examples/deploy-to-lambda/cdk-deployment.md)                     | Advanced     | Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.                                                                                                                                                                                      |
+| [`lambda-handler-with-cors`](../examples/deploy-to-lambda/lambda-handler-with-cors.md) | Intermediate | CORS for a FrontMCP Lambda is configured at the API Gateway HTTP API level, not in the handler. `frontmcp build --target lambda` writes `dist/lambda/handler.cjs` — your `@FrontMcp` server is wrapped automatically with `@codegenie/serverless-express`, so CORS belongs on the gateway. |
+| [`sam-template-basic`](../examples/deploy-to-lambda/sam-template-basic.md)             | Basic        | Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.                                                                                                                                                                                                              |
 
 > See all examples in [`examples/deploy-to-lambda/`](../examples/deploy-to-lambda/)
 

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

@@ -3,60 +3,98 @@ name: deploy-to-node-dockerfile
 description: Multi-stage Dockerfile for building and running a FrontMCP server in production
 ---
 
-# ---- Build Stage ----
+# Multi-Stage Dockerfile for FrontMCP
+
+This reference shows the canonical multi-stage `Dockerfile` for building and running a FrontMCP server (`--target node`) in production.
+
+## When to Use This Skill
+
+### Must Use
+
+- Containerizing a FrontMCP Node target server with Docker for production
+- Producing a slim, non-root image for deployment to Kubernetes, ECS, Fly.io, etc.
+
+### Recommended
+
+- Pairing with `deploy-to-node` for Docker Compose, PM2, or NGINX setups
+- Using a non-root user inside the container for security hardening
+
+### Skip When
 
+- Deploying serverless to Vercel, Lambda, or Cloudflare (no Dockerfile needed)
+- Distributing a single-file binary -- use `build-for-cli` instead
+
+## Reference Dockerfile
+
+Save as `Dockerfile` in your project root. Adjust the package manager (`yarn`/`npm`/`pnpm`) to match your project.
+
+```dockerfile
+# ---- Build Stage ----
 FROM node:24-alpine AS builder
 
 WORKDIR /app
 
 # Install dependencies first for better layer caching
-
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
 
-# Copy source and build
-
+# Copy source and build for the Node.js target
 COPY . .
 RUN yarn frontmcp build --target node
 
 # ---- Production Stage ----
-
 FROM node:24-alpine AS production
 
 WORKDIR /app
 
 # Create non-root user for security
-
 RUN addgroup -S frontmcp && adduser -S frontmcp -G frontmcp
 
 # Copy only production artifacts
-
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/package.json ./
 COPY --from=builder /app/yarn.lock ./
 
 # Install production dependencies only
-
 RUN yarn install --frozen-lockfile --production && \
- yarn cache clean
-
-# Set ownership
+    yarn cache clean
 
+# Set ownership and switch to non-root user
 RUN chown -R frontmcp:frontmcp /app
-
 USER frontmcp
 
 # Environment defaults
-
 ENV NODE_ENV=production
 ENV PORT=3000
 
 EXPOSE 3000
 
+# FrontMCP exposes /healthz by default; /health is a legacy alias kept for
+# backwards compatibility unless you set `health.healthzPath` to '/health'.
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
- CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/healthz || exit 1
 
 CMD ["node", "dist/main.js"]
+```
+
+## Build and Run
+
+```bash
+# Build the image
+docker build -t my-frontmcp-server .
+
+# Run the container
+docker run -p 3000:3000 -e NODE_ENV=production my-frontmcp-server
+
+# Verify
+curl http://localhost:3000/healthz
+```
+
+## Notes
+
+- The build stage installs all dependencies (including dev) so `frontmcp build --target node` can run; the production stage installs only `--production` deps.
+- The non-root `frontmcp` user prevents container escape from running as `root`.
+- For `dist/main.js` to exist, `frontmcp build --target node` must complete without errors. If your entry file is not `src/main.ts`, pass `-e ./path/to/entry.ts`.
 
 ## Examples
 
@@ -66,3 +104,7 @@ CMD ["node", "dist/main.js"]
 | [`secure-nonroot-dockerfile`](../examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md)     | Advanced | A production Dockerfile with a non-root user, proper ownership, and security hardening.    |
 
 > See all examples in [`examples/deploy-to-node-dockerfile/`](../examples/deploy-to-node-dockerfile/)
+
+## Reference
+
+- Related skills: `deploy-to-node`, `build-for-mcpb`

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

@@ -65,7 +65,7 @@ COPY --from=builder /app/package.json ./
 RUN yarn install --frozen-lockfile --production && yarn cache clean
 EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
-  CMD wget -qO- http://localhost:3000/health || exit 1
+  CMD wget -qO- http://localhost:3000/healthz || exit 1
 CMD ["node", "dist/main.js"]
 ```
 
@@ -95,7 +95,7 @@ services:
         condition: service_healthy
     restart: unless-stopped
     healthcheck:
-      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/healthz']
       interval: 30s
       timeout: 5s
       retries: 3
@@ -149,14 +149,17 @@ LOG_LEVEL=info
 
 ## Step 5: Health Checks
 
-FrontMCP servers expose a `/health` endpoint by default:
+FrontMCP servers expose `/healthz` by default (configurable via `health.healthzPath`). `/health` is registered as a legacy alias for backwards compatibility unless `healthzPath` is explicitly set to `/health`:
 
 ```bash
-curl http://localhost:3000/health
+curl http://localhost:3000/healthz
 # Response: { "status": "ok", "uptime": 12345 }
+
+# /health works too (legacy alias) — prefer /healthz for new infra
+curl http://localhost:3000/health
 ```
 
-For Docker, the `HEALTHCHECK` directive in the Dockerfile and the `healthcheck` block in Compose handle this automatically. Point your load balancer or orchestrator at this endpoint for liveness checks.
+For Docker, the `HEALTHCHECK` directive in the Dockerfile and the `healthcheck` block in Compose handle this automatically. Point your load balancer or orchestrator at `/healthz` for liveness checks.
 
 ## Step 6: PM2 for Bare Metal
 
@@ -236,7 +239,7 @@ services:
 
 - [ ] `docker compose up -d` starts all services without errors
 - [ ] `docker compose ps` shows all containers as healthy
-- [ ] `curl http://localhost:3000/health` returns `{"status":"ok"}`
+- [ ] `curl http://localhost:3000/healthz` returns `{"status":"ok"}`
 
 **Production Readiness**