@frontmcp/skills 0.0.1 → 1.0.0-beta.9

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

@@ -0,0 +1,195 @@
+# Configuring Transport
+
+Configure how clients connect to your FrontMCP server — SSE, Streamable HTTP, stateless API, or a combination.
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up a new FrontMCP server and need to decide on a transport protocol (SSE, Streamable HTTP, or stateless)
+- Deploying to serverless targets (Vercel, Lambda, Cloudflare) that require stateless transport mode
+- Running multiple server instances behind a load balancer that require distributed sessions via Redis
+
+### Recommended
+
+- Migrating an existing server from legacy SSE to modern Streamable HTTP
+- Enabling SSE event resumability so clients can reconnect after network interruptions
+- Fine-tuning protocol flags beyond what the built-in presets provide
+
+### Skip When
+
+- You are configuring authentication or session tokens (use `configure-auth` instead)
+- You need to set up plugin middleware without changing the transport layer (use `create-plugin` reference instead)
+
+> **Decision:** Use this skill whenever you need to choose, combine, or customize the protocol(s) your MCP server exposes to clients.
+
+## TransportOptionsInput
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    sessionMode: 'stateful', // 'stateful' | 'stateless'
+    protocol: 'legacy', // preset or custom ProtocolConfig
+    persistence: {
+      // false to disable
+      redis: { provider: 'redis', host: 'localhost', port: 6379 },
+      defaultTtlMs: 3600000,
+    },
+    distributedMode: 'auto', // boolean | 'auto'
+    eventStore: {
+      enabled: true,
+      provider: 'redis', // 'memory' | 'redis'
+      maxEvents: 10000,
+      ttlMs: 300000,
+    },
+  },
+})
+class Server {}
+```
+
+## Protocol Presets
+
+Choose a preset that matches your deployment:
+
+| Preset               | SSE | Streamable HTTP | JSON | Stateless | Legacy SSE | Strict Session |
+| -------------------- | --- | --------------- | ---- | --------- | ---------- | -------------- |
+| `'legacy'` (default) | Yes | Yes             | No   | No        | Yes        | Yes            |
+| `'modern'`           | Yes | Yes             | No   | No        | No         | Yes            |
+| `'stateless-api'`    | No  | No              | No   | Yes       | No         | No             |
+| `'full'`             | Yes | Yes             | Yes  | Yes       | Yes        | No             |
+
+### When to Use Each
+
+- **`'legacy'`** — Default. Maximum compatibility with all MCP clients (Claude Desktop, etc.). Best for Node.js deployments.
+- **`'modern'`** — Drop legacy SSE support. Use when all clients support modern MCP protocol.
+- **`'stateless-api'`** — No sessions, pure request/response. Use for **Vercel**, **Lambda**, and other serverless targets.
+- **`'full'`** — All protocols enabled. Use for development or when you need every transport option.
+
+### Custom Protocol Config
+
+Override individual protocol flags:
+
+```typescript
+transport: {
+  protocol: {
+    sse: true,              // SSE listener endpoint
+    streamable: true,       // Streamable HTTP POST
+    json: false,            // JSON-only responses (no streaming)
+    stateless: false,       // Stateless HTTP (no sessions)
+    legacy: false,          // Legacy SSE transport
+    strictSession: true,    // Require session ID for streamable HTTP
+  },
+}
+```
+
+## Distributed Sessions
+
+For multi-instance deployments (load balanced), enable persistence with Redis:
+
+```typescript
+transport: {
+  distributedMode: true,
+  persistence: {
+    redis: { provider: 'redis', host: 'redis.internal', port: 6379 },
+    defaultTtlMs: 3600000,  // 1 hour session TTL
+  },
+}
+```
+
+- `distributedMode: 'auto'` — auto-detect based on whether Redis is configured
+- `distributedMode: true` — force distributed mode (requires Redis)
+- `distributedMode: false` — single-instance mode (in-memory sessions)
+
+## Event Store (SSE Resumability)
+
+Enable event store so clients can resume SSE connections after disconnects:
+
+```typescript
+transport: {
+  eventStore: {
+    enabled: true,
+    provider: 'redis',       // 'memory' for single instance, 'redis' for distributed
+    maxEvents: 10000,        // max events to store
+    ttlMs: 300000,           // 5 minute TTL
+    redis: { provider: 'redis', host: 'localhost' },
+  },
+}
+```
+
+## Target-Specific Recommendations
+
+| Target                   | Recommended Preset | Persistence | Event Store |
+| ------------------------ | ------------------ | ----------- | ----------- |
+| Node.js (single)         | `'legacy'`         | `false`     | Memory      |
+| Node.js (multi-instance) | `'modern'`         | Redis       | Redis       |
+| Vercel                   | `'stateless-api'`  | `false`     | Disabled    |
+| Lambda                   | `'stateless-api'`  | `false`     | Disabled    |
+| Cloudflare               | `'stateless-api'`  | `false`     | Disabled    |
+
+## Verification
+
+```bash
+# Start server and test SSE
+frontmcp dev
+
+# Test SSE endpoint
+curl -N http://localhost:3001/sse
+
+# Test streamable HTTP
+curl -X POST http://localhost:3001/ -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## Common Patterns
+
+| Pattern              | Correct                                                                          | Incorrect                                                  | Why                                                                                |
+| -------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Choosing a preset    | `protocol: 'modern'`                                                             | `protocol: { sse: true, streamable: true, legacy: false }` | Use a preset when it matches your needs; custom config is for overrides only       |
+| Serverless transport | `protocol: 'stateless-api'` with `sessionMode: 'stateless'`                      | `protocol: 'legacy'` on Lambda                             | Legacy preset creates sessions that serverless cannot maintain between invocations |
+| Distributed sessions | `distributedMode: true` with Redis `persistence` configured                      | `distributedMode: true` without Redis                      | Distributed mode requires Redis; omitting it causes a startup error                |
+| Event store provider | `provider: 'redis'` for multi-instance, `provider: 'memory'` for single instance | `provider: 'memory'` behind a load balancer                | In-memory event store is not shared across instances, breaking SSE resumability    |
+| Session TTL          | Set `defaultTtlMs` to match your expected session duration                       | Omitting `defaultTtlMs` when using Redis persistence       | Missing TTL can cause sessions to accumulate indefinitely in Redis                 |
+
+## Verification Checklist
+
+### Transport Protocol
+
+- [ ] Correct preset is chosen for the deployment target (see Target-Specific Recommendations table)
+- [ ] Custom protocol flags, if used, do not conflict with the selected `sessionMode`
+- [ ] Legacy SSE is disabled when all clients support modern MCP protocol
+
+### Session and Persistence
+
+- [ ] `sessionMode` is `'stateless'` for serverless deployments
+- [ ] `distributedMode` is enabled and Redis is configured for multi-instance deployments
+- [ ] `defaultTtlMs` is set to a reasonable value when persistence is enabled
+
+### Event Store
+
+- [ ] Event store provider matches the deployment topology (memory for single, Redis for distributed)
+- [ ] `maxEvents` and `ttlMs` are tuned for expected traffic volume
+- [ ] Event store is disabled for stateless-api deployments
+
+### Runtime Validation
+
+- [ ] Server starts without transport-related errors
+- [ ] SSE endpoint (`/sse`) responds with `text/event-stream` when SSE is enabled
+- [ ] Streamable HTTP endpoint (`/`) accepts JSON-RPC POST requests when streamable is enabled
+- [ ] Clients can reconnect and resume SSE streams when event store is enabled
+
+## Troubleshooting
+
+| Problem                                | Cause                                                                      | Solution                                                                                   |
+| -------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Server rejects SSE connections         | SSE is disabled in the protocol config or preset                           | Switch to `'legacy'`, `'modern'`, or `'full'` preset, or set `sse: true` in custom config  |
+| `distributedMode` startup error        | Redis persistence is not configured                                        | Add a `persistence.redis` block with valid connection details                              |
+| Clients lose state after reconnect     | Event store is disabled or using in-memory provider behind a load balancer | Enable event store with `provider: 'redis'` for distributed deployments                    |
+| Serverless function times out on SSE   | Using a stateful preset on a serverless target                             | Switch to `'stateless-api'` preset and set `sessionMode: 'stateless'`                      |
+| Session not found after server restart | In-memory sessions do not survive restarts                                 | Enable Redis persistence with `distributedMode: true`                                      |
+| Streamable HTTP returns 404            | Streamable HTTP is not enabled in the current preset                       | Use `'modern'`, `'legacy'`, or `'full'` preset, or set `streamable: true` in custom config |
+
+## Reference
+
+- **Docs:** [Runtime Modes and Transport Configuration](https://docs.agentfront.dev/frontmcp/deployment/runtime-modes)
+- **Related skills:** `configure-auth`, `create-plugin`

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

@@ -0,0 +1,4 @@
+# Redis Setup Reference
+
+> This reference is maintained in `frontmcp-setup/references/setup-redis.md`.
+> See that file for the full Redis configuration guide including connection options, Vercel KV setup, Docker Compose examples, and troubleshooting.

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

@@ -0,0 +1,4 @@
+# SQLite Setup Reference
+
+> This reference is maintained in `frontmcp-setup/references/setup-sqlite.md`.
+> See that file for the full SQLite configuration guide including WAL mode, encryption, daemon mode, and troubleshooting.

package/catalog/frontmcp-deployment/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: frontmcp-deployment
+description: "Domain router for shipping MCP servers \u2014 deploy to Node, Vercel, Lambda, Cloudflare, or build for CLI, browser, and SDK. Use when choosing a deployment target or build format."
+tags: [router, deployment, node, vercel, lambda, cloudflare, cli, browser, sdk, guide]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/deployment/overview
+---
+
+# FrontMCP Deployment Router
+
+Entry point for deploying and building FrontMCP servers. This skill helps you choose the right deployment target or build format based on your infrastructure requirements.
+
+## When to Use This Skill
+
+### Must Use
+
+- Choosing between deployment targets (Node vs Vercel vs Lambda vs Cloudflare) for a new project
+- Deciding on a build format (server vs CLI vs browser vs SDK) for distribution
+- Planning infrastructure and need to understand trade-offs between deployment options
+
+### Recommended
+
+- Comparing serverless platforms for cost, cold-start, and feature support
+- Understanding which transport protocol and storage provider each target requires
+- Migrating from one deployment target to another
+
+### Skip When
+
+- You already know your deployment target (go directly to `deploy-to-node`, `deploy-to-vercel`, etc.)
+- You need to configure server settings, not deploy (see `frontmcp-config`)
+- You need to build components, not ship them (see `frontmcp-development`)
+
+> **Decision:** Use this skill when you need to figure out WHERE to deploy. Use the specific skill when you already know.
+
+## Prerequisites
+
+- A working FrontMCP server with at least one `@App` and one `@Tool` (see `frontmcp-development`)
+- Server configuration completed (see `frontmcp-config`)
+- Tests passing locally (see `frontmcp-testing`)
+
+## Steps
+
+1. Review the Scenario Routing Table and Target Comparison below to choose a deployment target
+2. Run `frontmcp build --target <target>` to produce the build output
+3. Follow the specific deployment skill (e.g., `deploy-to-node`, `deploy-to-vercel`) for platform instructions
+4. Verify with the Post-Deployment checklist at the end of this skill
+
+## 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          |
+
+## Target Comparison
+
+| Target     | Transport                   | Storage               | Cold Start | Stateful | Best For                         |
+| ---------- | --------------------------- | --------------------- | ---------- | -------- | -------------------------------- |
+| Node       | stdio, SSE, Streamable HTTP | Redis, SQLite, memory | None       | Yes      | Full-featured production servers |
+| Vercel     | Streamable HTTP (stateless) | Vercel KV             | ~250ms     | No       | Rapid deployment, hobby/startup  |
+| Lambda     | Streamable HTTP (stateless) | DynamoDB, ElastiCache | ~500ms     | No       | AWS ecosystem, event-driven      |
+| Cloudflare | Streamable HTTP (stateless) | KV, Durable Objects   | ~5ms       | Limited  | Edge-first, global latency       |
+| CLI        | stdio                       | SQLite, memory        | None       | Yes      | Desktop tools, local agents      |
+| Browser    | In-memory                   | memory                | None       | Yes      | Client-side AI, demos            |
+| SDK        | Programmatic                | Configurable          | None       | Yes      | Embedding in existing apps       |
+
+> **Note on storage:** The FrontMCP SDK's `StorageProvider` type supports `'redis'` and `'vercel-kv'` as built-in providers. References to DynamoDB, Cloudflare KV, D1, and Durable Objects in the table above refer to platform-native storage that you configure outside the SDK (e.g., via AWS SDK, Cloudflare bindings). The SDK does not provide a built-in adapter for these — use them directly in your tools/providers.
+
+## Cross-Cutting Patterns
+
+| Pattern               | Rule                                                                                                     |
+| --------------------- | -------------------------------------------------------------------------------------------------------- |
+| Transport selection   | Stateful servers (Node, CLI) can use stdio or SSE; serverless must use Streamable HTTP (stateless)       |
+| Storage mapping       | Node: Redis or SQLite; Vercel: Vercel KV; Lambda: DynamoDB; Cloudflare: KV; CLI: SQLite; Browser: memory |
+| Environment variables | Never hardcode secrets; use `.env` locally, platform secrets in production                               |
+| Build command         | All targets: `frontmcp build --target <target>` produces optimized output                                |
+| Entry point           | All targets require `export default` of the `@FrontMcp` class from `main.ts`                             |
+
+## Common Patterns
+
+| Pattern            | Correct                                                 | Incorrect                   | Why                                                                          |
+| ------------------ | ------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| Target selection   | Choose based on infrastructure constraints              | Choose based on familiarity | Each target has different transport, storage, and cold-start characteristics |
+| Serverless storage | Use platform-native storage (Vercel KV, DynamoDB)       | Use Redis on serverless     | Platform-native storage avoids VPC/connection overhead on cold starts        |
+| Environment config | Platform secrets (Vercel env, AWS SSM)                  | `.env` files in production  | Platform secrets are encrypted, rotatable, and not committed to git          |
+| Build verification | Run `frontmcp build --target <target>` before deploying | Deploy source code directly | Build step validates config, bundles dependencies, and optimizes output      |
+
+## Verification Checklist
+
+### Pre-Deployment
+
+- [ ] `frontmcp build --target <target>` completes without errors
+- [ ] Environment variables configured for the target platform
+- [ ] Storage provider configured and accessible (Redis, KV, DynamoDB, etc.)
+- [ ] Transport protocol matches target requirements (stateless for serverless)
+
+### Post-Deployment
+
+- [ ] Health check endpoint responds
+- [ ] `tools/list` returns expected tools
+- [ ] Tool execution works end-to-end
+- [ ] Storage persistence verified (create, read, restart, read again)
+
+## Troubleshooting
+
+| Problem                            | Cause                                        | Solution                                                                        |
+| ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------- |
+| Cold start timeout on serverless   | Bundle too large or heavy initialization     | Lazy-load providers; reduce bundle with tree shaking; increase function timeout |
+| Session lost between requests      | Using memory storage on stateless serverless | Switch to platform-native storage (Vercel KV, DynamoDB, etc.)                   |
+| CORS errors on browser/web clients | HTTP CORS not configured                     | Add CORS config via `configure-http` skill                                      |
+| Build fails with missing module    | Node-only module in browser/edge build       | Use conditional imports or `@frontmcp/utils` cross-platform utilities           |
+
+## Reference
+
+- [Deployment Overview](https://docs.agentfront.dev/frontmcp/deployment/overview)
+- Related skills: `deploy-to-node`, `deploy-to-vercel`, `deploy-to-lambda`, `deploy-to-cloudflare`, `build-for-cli`, `build-for-browser`, `build-for-sdk`, `configure-transport`

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

@@ -0,0 +1,138 @@
+# Building for Browser
+
+Build your FrontMCP server or client for browser environments.
+
+## When to Use This Skill
+
+### Must Use
+
+- Building a browser-compatible MCP client or tool interface for a web application
+- Embedding MCP tools in a React, Vue, or other frontend framework using `@frontmcp/react`
+- Creating a client-side bundle that connects to a remote MCP server
+
+### Recommended
+
+- Prototyping MCP tool UIs in the browser before building a full backend
+- Shipping a web-based admin dashboard that lists and invokes MCP tools
+- Building a PWA or single-page app that consumes MCP resources
+
+### Skip When
+
+- Running MCP tools on a Node.js server -- use `--target node` or `build-for-cli`
+- Embedding MCP in an existing Node.js app without HTTP -- use `build-for-sdk`
+- Deploying to Cloudflare Workers or other edge runtimes -- use `deploy-to-cloudflare`
+
+> **Decision:** Choose this skill when the MCP consumer runs in a browser; use server-side build targets for Node.js environments.
+
+## Build Command
+
+```bash
+frontmcp build --target browser
+```
+
+### Options
+
+```bash
+frontmcp build --target browser -o ./dist/browser   # Custom output directory
+frontmcp build --target browser -e ./src/client.ts   # Custom entry file
+```
+
+## Browser Limitations
+
+Not all FrontMCP features are available in browser environments:
+
+| Feature                     | Browser Support | Notes                                     |
+| --------------------------- | --------------- | ----------------------------------------- |
+| Tools (client-side)         | Yes             | Can define and run tools                  |
+| Resources                   | Yes             | Read-only access                          |
+| Prompts                     | Yes             | Full support                              |
+| Redis                       | No              | Use in-memory or connect to server        |
+| SQLite                      | No              | No filesystem access                      |
+| File system utilities       | No              | `@frontmcp/utils` fs ops throw in browser |
+| Crypto (`@frontmcp/utils`)  | Yes             | Uses WebCrypto API                        |
+| Direct client (`connect()`) | Yes             | In-memory connection                      |
+
+## Usage with @frontmcp/react
+
+The browser build is commonly paired with `@frontmcp/react` for React applications:
+
+```typescript
+import { FrontMcpProvider, useTools } from '@frontmcp/react';
+
+function App() {
+  return (
+    <FrontMcpProvider config={{ serverUrl: 'https://my-mcp.example.com' }}>
+      <ToolUI />
+    </FrontMcpProvider>
+  );
+}
+
+function ToolUI() {
+  const { tools, callTool } = useTools();
+  // Use tools in your React components
+}
+```
+
+## Browser vs Node vs SDK Target
+
+| Aspect      | `--target browser` | `--target node`   | `--target sdk`      |
+| ----------- | ------------------ | ----------------- | ------------------- |
+| Runtime     | Browser            | Node.js server    | Node.js library     |
+| Output      | Browser bundle     | Server executable | CJS + ESM + types   |
+| HTTP server | No                 | Yes               | No (`serve: false`) |
+| Use case    | Frontend apps      | Standalone server | Embed in Node apps  |
+
+## Verification
+
+```bash
+# Build
+frontmcp build --target browser
+
+# Check output
+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  |
+
+## Verification Checklist
+
+**Build**
+
+- [ ] `frontmcp build --target browser` completes without errors
+- [ ] Output directory contains browser-compatible JS bundle
+- [ ] No Node.js-only modules are included in the bundle
+
+**Runtime**
+
+- [ ] Bundle loads in the browser without console errors
+- [ ] MCP tools are listed and callable from the frontend
+- [ ] WebCrypto-based operations (auth, PKCE) work correctly
+
+**Integration**
+
+- [ ] `@frontmcp/react` provider connects to the remote MCP server
+- [ ] Tool invocations return expected results in the UI
+- [ ] Resources and prompts render correctly in browser components
+
+## Troubleshooting
+
+| Problem                     | Cause                                     | Solution                                                         |
+| --------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
+| `Module not found: fs`      | Node.js module imported in browser bundle | Use a separate browser entry point that avoids Node-only imports |
+| `crypto is not defined`     | Using `node:crypto` instead of WebCrypto  | Switch to `@frontmcp/utils` crypto functions                     |
+| CORS errors on tool calls   | MCP server missing CORS headers           | Configure CORS middleware on the MCP server                      |
+| Bundle too large            | All server-side code included             | Use `--target browser` and a dedicated client entry file         |
+| `@frontmcp/utils` fs throws | File system ops called in browser         | Remove fs calls; use API endpoints or in-memory alternatives     |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/browser-compatibility>
+- **Related skills:** `build-for-sdk`, `build-for-cli`, `deploy-to-cloudflare`

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

@@ -0,0 +1,138 @@
+# 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.
+
+## When to Use This Skill
+
+### Must Use
+
+- Distributing your MCP server as a standalone executable that runs without Node.js
+- Creating a CLI tool installable via package managers (Homebrew, apt, etc.)
+- Producing a self-contained binary for air-gapped or dependency-free deployment
+
+### Recommended
+
+- Shipping an MCP-powered developer tool to end users who may not have Node.js
+- Building platform-specific binaries for CI/CD artifact pipelines
+- Creating a single-file JS bundle for lightweight Node.js execution
+
+### Skip When
+
+- Deploying to a server environment with Node.js available -- use `--target node`
+- Embedding tools in an existing Node.js application -- use `build-for-sdk`
+- Targeting browser environments -- use `build-for-browser`
+
+> **Decision:** Choose this skill when your goal is a distributable binary or bundled JS file; use other build targets for server or library deployments.
+
+## Build Commands
+
+### Native Binary (SEA)
+
+```bash
+frontmcp build --target cli
+```
+
+Produces a Node.js Single Executable Application — a single binary embedding your server code and the Node.js runtime.
+
+### JS Bundle Only
+
+```bash
+frontmcp build --target cli --js
+```
+
+Produces a bundled JS file without the native binary wrapper. Run with `node dist/server.js`.
+
+### Options
+
+```bash
+frontmcp build --target cli -o ./build        # Custom output directory
+frontmcp build --target cli -e ./src/main.ts   # Custom entry file
+frontmcp build --target cli --js               # JS bundle only (no SEA)
+```
+
+## Requirements
+
+- **Node.js 22+** required for SEA support
+- The entry file must export or instantiate a `@FrontMcp` decorated class
+- SEA binaries are platform-specific (build on macOS for macOS, Linux for Linux)
+
+## CLI Target vs Node Target
+
+| Aspect   | `--target cli`                     | `--target node`                |
+| -------- | ---------------------------------- | ------------------------------ |
+| Output   | Single binary or JS bundle         | JS files for server deployment |
+| Runtime  | Embedded Node.js (SEA) or external | Requires Node.js installed     |
+| Use case | Distribution to end users          | Server deployment (Docker, VM) |
+| Includes | Bundled dependencies               | External node_modules          |
+
+## Server Configuration for CLI Mode
+
+When building for CLI distribution, configure your server for local/stdin transport:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-cli-tool', version: '1.0.0' },
+  apps: [MyApp],
+  http: { socketPath: '/tmp/my-tool.sock' }, // Unix socket instead of TCP
+  sqlite: { path: '~/.my-tool/data.db' }, // Local storage
+})
+class MyCLIServer {}
+```
+
+## Verification
+
+```bash
+# Build
+frontmcp build --target cli
+
+# Test the binary
+./dist/my-server --help
+
+# Or test JS bundle
+node dist/my-server.cjs.js
+```
+
+## Common Patterns
+
+| Pattern               | Correct                                             | Incorrect                        | Why                                                         |
+| --------------------- | --------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| Node.js version       | Node.js 22+ for SEA builds                          | Node.js 18 or 20                 | SEA support requires Node.js 22+                            |
+| 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
+
+**Build**
+
+- [ ] `frontmcp build --target cli` completes without errors
+- [ ] Output directory contains the expected binary or `.cjs.js` file
+- [ ] Binary file size is reasonable (no unexpected bloat)
+
+**Runtime**
+
+- [ ] Binary runs without Node.js installed on a clean machine
+- [ ] `--help` flag prints usage information
+- [ ] JS bundle runs correctly with `node dist/my-server.cjs.js`
+
+**Distribution**
+
+- [ ] Binary is tested on the target platform (macOS, Linux, Windows)
+- [ ] Exit codes are correct (0 for success, non-zero for errors)
+- [ ] No hard-coded absolute paths in the bundled output
+
+## Troubleshooting
+
+| Problem                      | Cause                                       | Solution                                                    |
+| ---------------------------- | ------------------------------------------- | ----------------------------------------------------------- |
+| SEA build fails              | Node.js version below 22                    | Upgrade to Node.js 22+                                      |
+| Binary crashes on startup    | Missing `@FrontMcp` decorated entry         | Ensure entry file exports or instantiates a decorated class |
+| Binary too large             | All dependencies bundled including dev deps | Review dependencies and remove unused packages from bundle  |
+| Permission denied on binary  | Missing execute permission                  | Run `chmod +x dist/my-server`                               |
+| Binary fails on different OS | SEA binaries are platform-specific          | Build on the target OS or use CI matrix builds              |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/production-build>
+- **Related skills:** `build-for-sdk`, `build-for-browser`, `deploy-to-cloudflare`