@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/config/configure-transport/SKILL.md

@@ -1,151 +0,0 @@
----
-name: configure-transport
-description: Choose and configure transport protocols — SSE, Streamable HTTP, stateless API, or legacy. Use when deciding between transport modes, enabling distributed sessions, or configuring event stores.
-tags: [transport, sse, streamable-http, stateless, protocol, session]
-parameters:
-  - name: preset
-    description: Protocol preset (legacy, modern, stateless-api, full)
-    type: string
-    default: legacy
-examples:
-  - scenario: Use modern SSE + Streamable HTTP for production
-    expected-outcome: Server accepts both SSE and streamable HTTP connections
-  - scenario: Configure stateless API for serverless
-    expected-outcome: No session state, pure request/response
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/runtime-modes
----
-
-# Configuring Transport
-
-Configure how clients connect to your FrontMCP server — SSE, Streamable HTTP, stateless API, or a combination.
-
-## When to Use
-
-Configure transport when:
-
-- Choosing between SSE and Streamable HTTP protocols
-- Deploying to serverless (needs stateless mode)
-- Running multiple server instances (needs distributed sessions)
-- Enabling SSE event resumability
-
-## 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}'
-```

package/catalog/deployment/build-for-browser/SKILL.md

@@ -1,95 +0,0 @@
----
-name: build-for-browser
-description: Build a FrontMCP server for browser environments. Use when creating browser-compatible MCP clients, embedding MCP in web apps, or building client-side tool interfaces.
-tags: [deployment, browser, client, web, frontend]
-examples:
-  - scenario: Build browser bundle for a React web application
-    expected-outcome: Browser-compatible JS bundle importable in frontend code
-  - scenario: Create a browser-based MCP client
-    expected-outcome: Client-side MCP tools running in the browser
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/browser-compatibility
----
-
-# Building for Browser
-
-Build your FrontMCP server or client for browser environments.
-
-## When to Use
-
-Use `--target browser` when:
-
-- Embedding MCP tools in a web application
-- Building a browser-based MCP client with `@frontmcp/react`
-- Creating client-side tool interfaces that connect to a remote MCP server
-
-## 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/
-```

package/catalog/deployment/build-for-cli/SKILL.md

@@ -1,100 +0,0 @@
----
-name: build-for-cli
-description: Build a distributable CLI binary (SEA) or JS bundle from an MCP server. Use when creating standalone executables, CLI tools, or self-contained binaries.
-tags: [deployment, cli, binary, sea, executable]
-parameters:
-  - name: output-format
-    description: Output as native binary (default) or JS bundle (--js)
-    type: string
-    default: binary
-examples:
-  - scenario: Build a standalone CLI binary for distribution
-    expected-outcome: Single executable file that runs without Node.js installed
-  - scenario: Build a JS bundle for Node.js execution
-    expected-outcome: Bundled JS file runnable with node
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/production-build
----
-
-# 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
-
-Use `--target cli` when you want to distribute your MCP server as:
-
-- A standalone executable that end users run without installing Node.js
-- A CLI tool installable via package managers
-- A self-contained binary for deployment without dependencies
-
-## 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
-```

package/catalog/deployment/deploy-to-cloudflare/SKILL.md

@@ -1,192 +0,0 @@
----
-name: deploy-to-cloudflare
-description: Deploy a FrontMCP server to Cloudflare Workers. Use when deploying to Cloudflare, configuring wrangler.toml, or setting up Workers KV storage.
-tags:
-  - deployment
-  - cloudflare
-  - workers
-  - serverless
-parameters:
-  - name: worker-name
-    description: Name for the Cloudflare Worker
-    type: string
-    required: false
-    default: frontmcp-worker
-  - name: kv-namespace
-    description: KV namespace binding name for session and state storage
-    type: string
-    required: false
-  - name: compatibility-date
-    description: Cloudflare Workers compatibility date
-    type: string
-    required: false
-    default: '2024-01-01'
-examples:
-  - scenario: Deploy a basic MCP server to Cloudflare Workers
-    parameters:
-      worker-name: my-mcp-worker
-    expectedOutcome: A FrontMCP server running as a Cloudflare Worker with wrangler.toml configured and deployed via wrangler deploy.
-  - scenario: Deploy with Workers KV for persistent storage
-    parameters:
-      worker-name: my-mcp-worker
-      kv-namespace: FRONTMCP_KV
-    expectedOutcome: A FrontMCP server with Cloudflare KV providing persistent storage for sessions and skill state.
-compatibility: Wrangler CLI required. Cloudflare Workers support is experimental.
-license: Apache-2.0
-visibility: both
-priority: 10
-metadata:
-  category: deployment
-  difficulty: intermediate
-  platform: cloudflare
-  docs: https://docs.agentfront.dev/frontmcp/deployment/serverless
----
-
-# 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>
-
-## 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:
-
-```
-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()
-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). Use `frontmcp build --target cloudflare --analyze` to inspect the bundle.
-- **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
-
-- **Worker exceeds size limit**: Minimize dependencies. Run `frontmcp build --target cloudflare --analyze` and remove unused packages.
-- **Module format errors**: Ensure `wrangler.toml` does not set `type = "module"`. FrontMCP Cloudflare builds use CommonJS.
-- **KV binding errors**: Verify the KV namespace is created and the binding name in `wrangler.toml` matches your code.
-- **Timeout errors**: Check CPU time limits for your Cloudflare plan. Optimize or offload heavy computation.