@frontmcp/skills 0.0.1

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

@@ -0,0 +1,95 @@
+---
+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

@@ -0,0 +1,100 @@
+---
+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/build-for-sdk/SKILL.md

@@ -0,0 +1,218 @@
+---
+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
+---
+
+# 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
+
+Use `--target sdk` when:
+
+- 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
+
+## Build Command
+
+```bash
+frontmcp build --target sdk
+```
+
+Produces dual-format output:
+
+- `{name}.cjs.js` — CommonJS format
+- `{name}.esm.mjs` — ES Module format
+- `*.d.ts` — TypeScript declarations
+
+All `@frontmcp/*` dependencies are marked as external (not bundled).
+
+## Disable HTTP Server
+
+Set `serve: false` in your `@FrontMcp` decorator to prevent the HTTP listener from starting:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-sdk', version: '1.0.0' },
+  apps: [MyApp],
+  serve: false, // No HTTP server — library mode only
+})
+class MySDK {}
+```
+
+## Programmatic Usage with `create()`
+
+The `create()` factory spins up a server from a flat config object — no decorators or classes needed:
+
+```typescript
+import { create } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const server = await create({
+  info: { name: 'my-service', version: '1.0.0' },
+  tools: [
+    tool({
+      name: 'calculate',
+      description: 'Perform calculation',
+      inputSchema: { expression: z.string() },
+      outputSchema: { result: z.number() },
+    })((input) => ({ result: eval(input.expression) })),
+  ],
+  cacheKey: 'my-service', // Reuse same instance on repeated calls
+});
+
+// Call tools directly
+const result = await server.callTool('calculate', { expression: '2 + 2' });
+
+// List available tools
+const { tools } = await server.listTools();
+
+// Clean up
+await server.dispose();
+```
+
+### CreateConfig Fields
+
+```typescript
+create({
+  // Required
+  info: { name: string; version: string },
+
+  // App-level (merged into synthetic app)
+  tools?: ToolType[],
+  resources?: ResourceType[],
+  prompts?: PromptType[],
+  agents?: AgentType[],
+  skills?: SkillType[],
+  plugins?: PluginType[],
+  providers?: ProviderType[],
+  adapters?: AdapterType[],
+  auth?: AuthOptionsInput,
+
+  // Server-level
+  redis?: RedisOptionsInput,
+  transport?: TransportOptionsInput,
+  logging?: LoggingOptionsInput,
+  elicitation?: ElicitationOptionsInput,
+
+  // create()-specific
+  appName?: string,       // defaults to info.name
+  cacheKey?: string,      // same key = reuse server instance
+  machineId?: string,     // stable session ID across restarts
+})
+```
+
+## Platform-Specific Connections
+
+Use `connect*()` functions to get tools formatted for a specific LLM platform:
+
+### OpenAI Function Calling
+
+```typescript
+import { connectOpenAI } from '@frontmcp/sdk';
+
+const client = await connectOpenAI(MyServerConfig, {
+  session: { id: 'user-123', user: { sub: 'user-id' } },
+});
+
+const tools = await client.listTools();
+// Returns OpenAI format: [{ type: 'function', function: { name, description, parameters, strict: true } }]
+
+const result = await client.callTool('my-tool', { arg: 'value' });
+await client.close();
+```
+
+### Anthropic Claude
+
+```typescript
+import { connectClaude } from '@frontmcp/sdk';
+
+const client = await connectClaude(MyServerConfig);
+const tools = await client.listTools();
+// Returns Claude format: [{ name, description, input_schema }]
+```
+
+### LangChain
+
+```typescript
+import { connectLangChain } from '@frontmcp/sdk';
+
+const client = await connectLangChain(MyServerConfig);
+const tools = await client.listTools();
+// Returns LangChain tool schema format
+```
+
+### Vercel AI SDK
+
+```typescript
+import { connectVercelAI } from '@frontmcp/sdk';
+
+const client = await connectVercelAI(MyServerConfig);
+const tools = await client.listTools();
+// Returns Vercel AI SDK format
+```
+
+### ConnectOptions
+
+```typescript
+const client = await connectOpenAI(config, {
+  clientInfo: { name: 'my-app', version: '1.0' },
+  session: { id: 'session-123', user: { sub: 'user-id', name: 'Alice' } },
+  authToken: 'jwt-token-here',
+  capabilities: { roots: { listChanged: true } },
+});
+```
+
+## DirectClient API
+
+All `connect*()` functions return a `DirectClient` with these methods:
+
+| Method                  | Description                            |
+| ----------------------- | -------------------------------------- |
+| `listTools()`           | List tools in platform-specific format |
+| `callTool(name, args)`  | Execute a tool                         |
+| `listResources()`       | List available resources               |
+| `readResource(uri)`     | Read a resource                        |
+| `listPrompts()`         | List available prompts                 |
+| `getPrompt(name, args)` | Get a prompt                           |
+| `close()`               | Clean up connection                    |
+
+## SDK vs Node Target
+
+| Aspect       | `--target sdk`                    | `--target node`       |
+| ------------ | --------------------------------- | --------------------- |
+| Output       | CJS + ESM + .d.ts                 | Single JS executable  |
+| HTTP server  | No (`serve: false`)               | Yes (listens on port) |
+| Use case     | Library/embed in apps             | Standalone deployment |
+| Distribution | npm package                       | Docker/binary         |
+| Tool format  | Platform-specific via connect\*() | Raw MCP protocol      |
+
+## Verification
+
+```bash
+# Build
+frontmcp build --target sdk
+
+# Check outputs
+ls dist/
+# my-sdk.cjs.js  my-sdk.esm.mjs  *.d.ts
+
+# Test programmatically
+node -e "const { create } = require('./dist/my-sdk.cjs.js'); ..."
+```

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

@@ -0,0 +1,192 @@
+---
+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.