@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

@@ -0,0 +1,143 @@
+---
+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.
+
+## 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,191 @@
+---
+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.
+
+## 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 24+** 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
+```
+
+## 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                                                         |
+| --------------------- | --------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| 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 |
+
+## 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 24                    | Upgrade to Node.js 24+                                      |
+| 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`

package/catalog/{deployment/build-for-sdk/SKILL.md → frontmcp-deployment/references/build-for-sdk.md}

@@ -1,33 +1,33 @@
 ---
 name: build-for-sdk
-description: Build a FrontMCP server as an embeddable SDK library for Node.js applications without HTTP serving. Use when embedding MCP in existing apps, using connect()/connectOpenAI()/connectClaude(), or distributing as an npm package.
-tags: [deployment, sdk, library, embed, programmatic, connect]
-examples:
-  - scenario: Embed MCP tools in an existing Express app
-    expected-outcome: Tools callable programmatically without HTTP server
-  - scenario: Build SDK for npm distribution
-    expected-outcome: CJS + ESM + TypeScript declarations package
-  - scenario: Connect tools to OpenAI function calling
-    expected-outcome: Tools formatted for OpenAI API consumption
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/direct-client
+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).
 
-## When to Use
+## When to Use This Skill
 
-Use `--target sdk` when:
+### Must Use
 
-- Embedding MCP tools in an existing Node.js application
-- Distributing your tools as an npm package
-- Connecting tools to LLM platforms (OpenAI, Claude, LangChain, Vercel AI) programmatically
-- Running tools in-memory without network overhead
+- Embedding MCP tools in an existing Node.js application without starting an HTTP server
+- Distributing your MCP server as an npm package with CJS + ESM + TypeScript declarations
+- Connecting tools to LLM platforms (OpenAI, Claude, LangChain, Vercel AI) via `connect*()` functions
+
+### Recommended
+
+- Running MCP tools in-memory for low-latency, zero-network-overhead execution
+- Building a shared tool library consumed by multiple services in a monorepo
+- Testing MCP tools programmatically in integration test suites
+
+### Skip When
+
+- Deploying a standalone MCP server that listens on a port -- use `--target node` or `build-for-cli`
+- Building a browser-based MCP client -- use `build-for-browser`
+- Deploying to Cloudflare Workers -- use `deploy-to-cloudflare`
+
+> **Decision:** Choose this skill when you need MCP tools as a library or programmatic API; use other targets for standalone servers or browser clients.
 
 ## Build Command
 
@@ -216,3 +216,49 @@ ls dist/
 # Test programmatically
 node -e "const { create } = require('./dist/my-sdk.cjs.js'); ..."
 ```
+
+## Common Patterns
+
+| Pattern             | Correct                                     | Incorrect                                | Why                                                         |
+| ------------------- | ------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
+| HTTP server         | `serve: false` in `@FrontMcp` decorator     | Omitting `serve` (defaults to `true`)    | SDK mode should not bind a port                             |
+| Dependency bundling | `@frontmcp/*` marked as external            | Bundling all `@frontmcp/*` packages      | Consumers already have these as peer deps                   |
+| Instance reuse      | Pass `cacheKey` to `create()`               | Call `create()` on every request         | Same key reuses the server instance, avoiding repeated init |
+| Cleanup             | Call `server.dispose()` or `client.close()` | Letting the process exit without cleanup | Avoids leaked connections and open handles                  |
+| Platform tools      | `connectOpenAI()` for OpenAI format         | Manually formatting tool schemas         | `connect*()` handles schema translation automatically       |
+
+## Verification Checklist
+
+**Build**
+
+- [ ] `frontmcp build --target sdk` completes without errors
+- [ ] Output contains `.cjs.js`, `.esm.mjs`, and `.d.ts` files
+- [ ] `@frontmcp/*` packages are not included in the bundle
+
+**Programmatic API**
+
+- [ ] `create()` returns a working server instance
+- [ ] `server.callTool()` executes tools and returns results
+- [ ] `server.listTools()` returns all registered tools
+- [ ] `server.dispose()` cleans up without errors
+
+**Platform Connections**
+
+- [ ] `connectOpenAI()` returns tools in OpenAI function-calling format
+- [ ] `connectClaude()` returns tools in Anthropic `input_schema` format
+- [ ] `client.close()` releases all resources
+
+## Troubleshooting
+
+| Problem                         | Cause                                              | Solution                                                            |
+| ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
+| HTTP server starts unexpectedly | Missing `serve: false` in decorator                | Add `serve: false` to the `@FrontMcp` options                       |
+| `create()` returns stale tools  | Cached instance from a previous `cacheKey`         | Use a unique `cacheKey` or call `dispose()` before re-creating      |
+| TypeScript types missing        | `.d.ts` files not generated                        | Ensure `tsconfig` has `declaration: true` and build target is `sdk` |
+| `connectOpenAI()` format wrong  | Using raw `listTools()` instead of platform client | Use `connectOpenAI()` which formats tools for OpenAI automatically  |
+| Bundle includes `@frontmcp/*`   | Build config missing externals                     | Verify `--target sdk` is set; it marks `@frontmcp/*` as external    |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/direct-client>
+- **Related skills:** `build-for-cli`, `build-for-browser`, `deploy-to-cloudflare`

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

@@ -0,0 +1,218 @@
+---
+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.
+
+<Warning>
+Cloudflare Workers support is **experimental**. The Express-to-Workers adapter has limitations with streaming, certain middleware, and some response methods. For production Cloudflare deployments, consider using Hono or native Workers APIs.
+</Warning>
+
+## When to Use This Skill
+
+### Must Use
+
+- Deploying a FrontMCP server to Cloudflare Workers
+- Configuring `wrangler.toml` for a FrontMCP project targeting Cloudflare
+- Setting up Workers KV, D1, or Durable Objects storage for an MCP server on Cloudflare
+
+### Recommended
+
+- Evaluating serverless edge deployment options for low-latency MCP endpoints
+- Migrating an existing Node.js MCP server to a Cloudflare Workers environment
+- Adding a custom domain to a Cloudflare-hosted MCP server
+
+### Skip When
+
+- Deploying to a traditional Node.js server or Docker container -- use `build-for-cli` or `--target node`
+- Building a browser-based MCP client -- use `build-for-browser`
+- Embedding MCP tools in an existing app without HTTP -- use `build-for-sdk`
+
+> **Decision:** Choose this skill when your deployment target is Cloudflare Workers; otherwise pick the skill that matches your runtime.
+
+## Prerequisites
+
+- A Cloudflare account (https://dash.cloudflare.com)
+- Wrangler CLI installed: `npm install -g wrangler`
+- A built FrontMCP project
+
+## Step 1: Create a Cloudflare-targeted Project
+
+```bash
+npx frontmcp create my-app --target cloudflare
+```
+
+This generates the project with a `wrangler.toml` and a deploy script (`npm run deploy` runs `wrangler deploy`).
+
+## Step 2: Build for Cloudflare
+
+```bash
+frontmcp build --target cloudflare
+```
+
+This produces:
+
+```text
+dist/
+  main.js      # Your compiled server (CommonJS)
+  index.js     # Cloudflare handler wrapper
+wrangler.toml  # Wrangler configuration
+```
+
+Cloudflare Workers use CommonJS (not ESM). The build command sets `--module commonjs` automatically.
+
+## Step 3: Configure wrangler.toml
+
+The generated `wrangler.toml`:
+
+```toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+NODE_ENV = "production"
+```
+
+To add KV storage for sessions and state:
+
+```toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+Create the KV namespace via the dashboard or CLI:
+
+```bash
+wrangler kv:namespace create FRONTMCP_KV
+```
+
+Copy the returned `id` into your `wrangler.toml`.
+
+## Step 4: Configure the Server
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+For KV-backed session storage, use the Cloudflare KV or Upstash Redis provider.
+
+## Step 5: Deploy
+
+```bash
+# Preview deployment
+wrangler dev
+
+# Production deployment
+wrangler deploy
+```
+
+### Custom Domain
+
+Configure a custom domain in the Cloudflare dashboard under **Workers & Pages > your worker > Settings > Domains & Routes**, or via wrangler:
+
+```bash
+wrangler domains add mcp.example.com
+```
+
+## Step 6: Verify
+
+```bash
+# Health check
+curl https://frontmcp-worker.your-subdomain.workers.dev/health
+
+# Test MCP endpoint
+curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## Workers Limitations
+
+- **Bundle size**: Workers have a 1 MB compressed / 10 MB uncompressed limit (paid plan: 10 MB / 30 MB). Review dependencies and remove unused packages to reduce bundle size.
+- **CPU time**: 10 ms CPU time on free plan, 30 seconds on paid. Long-running operations must be optimized or use Durable Objects.
+- **No native modules**: `better-sqlite3` and other native Node.js modules are not available. Use KV, D1, or Upstash Redis for storage.
+- **Streaming**: SSE streaming may have limitations through the Workers adapter. Test thoroughly.
+
+## Storage Options
+
+| Storage       | Use Case                      | Notes                             |
+| ------------- | ----------------------------- | --------------------------------- |
+| Cloudflare KV | Simple key-value, low write   | Eventually consistent, fast reads |
+| Upstash Redis | Sessions, pub/sub, high write | Redis-compatible REST API         |
+| Cloudflare D1 | Relational data               | SQLite-based, serverless          |
+
+## Troubleshooting
+
+| Problem                       | Cause                                          | Solution                                                                  |
+| ----------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
+| Worker exceeds size limit     | Too many bundled dependencies                  | Review dependencies and remove unused packages to reduce bundle size      |
+| Module format errors          | `wrangler.toml` sets `type = "module"`         | Remove the `type` field; FrontMCP Cloudflare builds use CommonJS          |
+| KV binding errors             | Namespace not created or binding name mismatch | Run `wrangler kv:namespace create` and copy the `id` into `wrangler.toml` |
+| Timeout errors                | CPU time exceeds plan limit                    | Upgrade plan or offload heavy computation to Durable Objects              |
+| CORS failures on MCP endpoint | Missing CORS headers in Worker response        | Add CORS middleware or headers in your FrontMCP server configuration      |
+
+## 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 |
+
+## Verification Checklist
+
+**Build**
+
+- [ ] `frontmcp build --target cloudflare` completes without errors
+- [ ] Bundle size is within Cloudflare plan limits (free: 1 MB compressed)
+
+**Configuration**
+
+- [ ] `wrangler.toml` has correct `name`, `main`, and `compatibility_date`
+- [ ] KV namespace IDs match between dashboard and `wrangler.toml`
+- [ ] Secrets are stored via `wrangler secret put`, not in `[vars]`
+
+**Deployment**
+
+- [ ] `wrangler dev` serves the MCP endpoint locally
+- [ ] `wrangler deploy` succeeds without errors
+- [ ] Health endpoint responds with 200
+
+**Runtime**
+
+- [ ] `tools/list` JSON-RPC call returns expected tools
+- [ ] SSE streaming works end-to-end (if using SSE transport)
+- [ ] Custom domain resolves correctly (if configured)
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/serverless>
+- **Related skills:** `build-for-cli`, `build-for-browser`, `build-for-sdk`