@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-deployment/examples/build-for-cli/unix-socket-daemon.md

@@ -0,0 +1,76 @@
+---
+name: unix-socket-daemon
+reference: build-for-cli
+level: intermediate
+description: 'Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.'
+tags: [deployment, unix-socket, cli, transport, local, unix]
+features:
+  - 'Configuring a FrontMCP server for Unix socket transport instead of TCP'
+  - 'Running the server as a background daemon with process management (`frontmcp start/stop/status`)'
+  - 'Installing the daemon as a system service for automatic startup on reboot'
+---
+
+# Unix Socket Daemon Mode
+
+Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup',
+  description: 'Look up a term in the local database',
+  inputSchema: { term: z.string() },
+})
+class LookupTool extends ToolContext<{ term: string }> {
+  async execute(input: { term: string }) {
+    return { content: [{ type: 'text' as const, text: `Result for: ${input.term}` }] };
+  }
+}
+
+@App({ name: 'DaemonApp', tools: [LookupTool] })
+class DaemonApp {}
+
+@FrontMcp({
+  info: { name: 'my-daemon', version: '1.0.0' },
+  apps: [DaemonApp],
+  http: { socketPath: '/tmp/my-tool.sock' },
+  sqlite: { path: '~/.my-tool/data.db' },
+})
+class MyDaemonServer {}
+```
+
+```bash
+# Start daemon in foreground
+frontmcp socket ./src/main.ts -s ~/.frontmcp/sockets/my-app.sock
+
+# Start daemon in background with a local database
+frontmcp socket ./src/main.ts -b --db ~/.my-tool/data.db
+
+# Manage the daemon process
+frontmcp start my-daemon -e ./src/main.ts --max-restarts 5
+frontmcp status my-daemon
+frontmcp logs my-daemon -F
+frontmcp stop my-daemon
+```
+
+```bash
+# Install as a system service for automatic startup
+# Linux: creates a systemd unit
+# macOS: creates a launchd plist
+frontmcp service install my-daemon
+```
+
+## What This Demonstrates
+
+- Configuring a FrontMCP server for Unix socket transport instead of TCP
+- Running the server as a background daemon with process management (`frontmcp start/stop/status`)
+- Installing the daemon as a system service for automatic startup on reboot
+
+## Related
+
+- See `build-for-cli` for the full process management and system service reference

package/catalog/frontmcp-deployment/examples/build-for-sdk/connect-openai.md

@@ -0,0 +1,78 @@
+---
+name: connect-openai
+reference: build-for-sdk
+level: intermediate
+description: "Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API."
+tags: [deployment, sdk, openai, session, connect]
+features:
+  - 'Setting `serve: false` to prevent the HTTP server from starting in library mode'
+  - 'Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically'
+  - 'Passing session information via `ConnectOptions` for user context'
+---
+
+# Connect to OpenAI Function Calling
+
+Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.
+
+## Code
+
+```typescript
+// src/openai-integration.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { connectOpenAI } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search_docs',
+  description: 'Search documentation by keyword',
+  inputSchema: { query: z.string(), limit: z.number().optional() },
+})
+class SearchDocsTool extends ToolContext<{ query: string; limit?: number }> {
+  async execute(input: { query: string; limit?: number }) {
+    return {
+      content: [{ type: 'text' as const, text: `Found results for: ${input.query}` }],
+    };
+  }
+}
+
+@App({ name: 'DocsApp', tools: [SearchDocsTool] })
+class DocsApp {}
+
+@FrontMcp({
+  info: { name: 'docs-sdk', version: '1.0.0' },
+  apps: [DocsApp],
+  serve: false, // No HTTP server - library mode only
+})
+class DocsSDK {}
+
+// Connect with OpenAI-formatted tools
+async function main() {
+  const client = await connectOpenAI(DocsSDK, {
+    session: { id: 'user-123', user: { sub: 'user-id' } },
+  });
+
+  // Tools are returned in OpenAI format:
+  // [{ type: 'function', function: { name, description, parameters, strict: true } }]
+  const tools = await client.listTools();
+  console.log(JSON.stringify(tools, null, 2));
+
+  // Call a tool
+  const result = await client.callTool('search_docs', { query: 'authentication' });
+  console.log(result);
+
+  // Always clean up
+  await client.close();
+}
+
+main();
+```
+
+## What This Demonstrates
+
+- Setting `serve: false` to prevent the HTTP server from starting in library mode
+- Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically
+- Passing session information via `ConnectOptions` for user context
+
+## Related
+
+- See `build-for-sdk` for `connectClaude()`, `connectLangChain()`, and `connectVercelAI()` alternatives

package/catalog/frontmcp-deployment/examples/build-for-sdk/create-flat-config.md

@@ -0,0 +1,85 @@
+---
+name: create-flat-config
+reference: build-for-sdk
+level: basic
+description: 'Spin up an in-memory FrontMCP server from a flat config object using `create()`.'
+tags: [deployment, sdk, cache, flat, config]
+features:
+  - 'Using `create()` to spin up a server without decorators or classes'
+  - 'Calling tools directly via `server.callTool()` with zero network overhead'
+  - 'Using `cacheKey` to reuse the same server instance across multiple calls'
+---
+
+# Programmatic Server with create()
+
+Spin up an in-memory FrontMCP server from a flat config object using `create()`.
+
+## Code
+
+```typescript
+// src/embedded-server.ts
+import { create, tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+async function main() {
+  const server = await create({
+    info: { name: 'my-service', version: '1.0.0' },
+    tools: [
+      tool({
+        name: 'calculate',
+        description: 'Perform calculation',
+        inputSchema: {
+          a: z.number(),
+          b: z.number(),
+          operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+        },
+        outputSchema: { result: z.number() },
+      })((input) => {
+        switch (input.operation) {
+          case 'add':
+            return { result: input.a + input.b };
+          case 'subtract':
+            return { result: input.a - input.b };
+          case 'multiply':
+            return { result: input.a * input.b };
+          case 'divide':
+            return { result: input.a / input.b };
+        }
+      }),
+    ],
+    cacheKey: 'my-service', // Reuse same instance on repeated calls
+  });
+
+  // Call tools directly - no HTTP involved
+  const result = await server.callTool('calculate', { a: 2, b: 2, operation: 'add' });
+  console.log(result); // { result: 4 }
+
+  // List available tools
+  const { tools } = await server.listTools();
+  console.log(tools.map((t) => t.name)); // ['calculate']
+
+  // Clean up when done
+  await server.dispose();
+}
+
+main();
+```
+
+```bash
+# Build as an SDK library
+frontmcp build --target sdk
+
+# Verify outputs
+ls dist/
+# my-service.cjs.js  my-service.esm.mjs  *.d.ts
+```
+
+## What This Demonstrates
+
+- Using `create()` to spin up a server without decorators or classes
+- Calling tools directly via `server.callTool()` with zero network overhead
+- Using `cacheKey` to reuse the same server instance across multiple calls
+
+## Related
+
+- See `build-for-sdk` for the full `CreateConfig` fields and `DirectClient` API

package/catalog/frontmcp-deployment/examples/build-for-sdk/multi-platform-connect.md

@@ -0,0 +1,104 @@
+---
+name: multi-platform-connect
+reference: build-for-sdk
+level: advanced
+description: 'Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.'
+tags: [deployment, sdk, multi, platform, connect]
+features:
+  - 'Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation'
+  - "Each `connect*()` function returns tools in the platform's native format"
+  - 'All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)'
+---
+
+# Multi-Platform Tool Connection
+
+Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text to a target language',
+  inputSchema: { text: z.string(), targetLang: z.string() },
+})
+class TranslateTool extends ToolContext<{ text: string; targetLang: string }> {
+  async execute(input: { text: string; targetLang: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `[${input.targetLang}] ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'TranslateApp', tools: [TranslateTool] })
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'translate-sdk', version: '1.0.0' },
+  apps: [TranslateApp],
+  serve: false,
+})
+class TranslateSDK {}
+
+export default TranslateSDK;
+```
+
+```typescript
+// src/connect-all-platforms.ts
+import { connectOpenAI, connectClaude, connectLangChain, connectVercelAI } from '@frontmcp/sdk';
+import TranslateSDK from './server';
+
+async function main() {
+  // OpenAI format: [{ type: 'function', function: { name, description, parameters, strict: true } }]
+  const openaiClient = await connectOpenAI(TranslateSDK, {
+    clientInfo: { name: 'my-app', version: '1.0' },
+    session: { id: 'session-1', user: { sub: 'user-1', name: 'Alice' } },
+  });
+  const openaiTools = await openaiClient.listTools();
+  console.log('OpenAI tools:', openaiTools);
+
+  // Claude format: [{ name, description, input_schema }]
+  const claudeClient = await connectClaude(TranslateSDK);
+  const claudeTools = await claudeClient.listTools();
+  console.log('Claude tools:', claudeTools);
+
+  // LangChain tool schema format
+  const langchainClient = await connectLangChain(TranslateSDK);
+  const langchainTools = await langchainClient.listTools();
+  console.log('LangChain tools:', langchainTools);
+
+  // Vercel AI SDK format
+  const vercelClient = await connectVercelAI(TranslateSDK);
+  const vercelTools = await vercelClient.listTools();
+  console.log('Vercel AI tools:', vercelTools);
+
+  // All clients share the same DirectClient API
+  const result = await openaiClient.callTool('translate', {
+    text: 'Hello',
+    targetLang: 'es',
+  });
+  console.log(result);
+
+  // Clean up all clients
+  await openaiClient.close();
+  await claudeClient.close();
+  await langchainClient.close();
+  await vercelClient.close();
+}
+
+main();
+```
+
+## What This Demonstrates
+
+- Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation
+- Each `connect*()` function returns tools in the platform's native format
+- All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)
+
+## Related
+
+- See `build-for-sdk` for the full `DirectClient` API reference and `ConnectOptions` details

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md

@@ -0,0 +1,82 @@
+---
+name: basic-worker-deploy
+reference: deploy-to-cloudflare
+level: basic
+description: 'Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.'
+tags: [deployment, cloudflare, transport, local, worker]
+features:
+  - 'A minimal FrontMCP server configured for Cloudflare Workers with SSE transport'
+  - 'The `wrangler.toml` configuration with `main` pointing to the build output'
+  - 'Using `wrangler dev` for local testing before deploying with `wrangler deploy`'
+---
+
+# Basic Cloudflare Workers Deployment
+
+Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo back the input',
+  inputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext<{ message: string }> {
+  async execute(input: { message: string }) {
+    return { content: [{ type: 'text' as const, text: input.message }] };
+  }
+}
+
+@App({ name: 'MyApp', tools: [EchoTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    protocol: 'legacy',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build for Cloudflare Workers
+frontmcp build --target cloudflare
+
+# Preview locally
+wrangler dev
+
+# Deploy to production
+wrangler deploy
+
+# Verify
+curl https://frontmcp-worker.your-subdomain.workers.dev/health
+```
+
+## What This Demonstrates
+
+- A minimal FrontMCP server configured for Cloudflare Workers with SSE transport
+- The `wrangler.toml` configuration with `main` pointing to the build output
+- Using `wrangler dev` for local testing before deploying with `wrangler deploy`
+
+## Related
+
+- See `deploy-to-cloudflare` for KV storage, D1, bundle size limits, and troubleshooting

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md

@@ -0,0 +1,97 @@
+---
+name: worker-custom-domain
+reference: deploy-to-cloudflare
+level: advanced
+description: 'Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.'
+tags: [deployment, json-rpc, cloudflare, worker, custom, domain]
+features:
+  - 'Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts'
+  - 'Adding a custom domain with `wrangler domains add` for production-ready URLs'
+  - 'End-to-end verification of both the health check and MCP JSON-RPC endpoint'
+---
+
+# Cloudflare Worker with Custom Domain and Project Scaffold
+
+Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.
+
+## Code
+
+```bash
+# Scaffold a new project targeting Cloudflare
+npx frontmcp create my-app --target cloudflare
+cd my-app
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text',
+  inputSchema: { text: z.string(), lang: z.string() },
+})
+class TranslateTool extends ToolContext<{ text: string; lang: string }> {
+  async execute(input: { text: string; lang: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `[${input.lang}] ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'TranslateApp', tools: [TranslateTool] })
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'translate-worker', version: '1.0.0' },
+  apps: [TranslateApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class TranslateServer {}
+
+export default TranslateServer;
+```
+
+```toml
+# wrangler.toml
+name = "translate-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Add a custom domain
+wrangler domains add mcp.example.com
+
+# Verify health endpoint
+curl https://mcp.example.com/health
+
+# Test MCP endpoint
+curl -X POST https://mcp.example.com/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## What This Demonstrates
+
+- Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts
+- Adding a custom domain with `wrangler domains add` for production-ready URLs
+- End-to-end verification of both the health check and MCP JSON-RPC endpoint
+
+## Related
+
+- See `deploy-to-cloudflare` for bundle size limits, CPU time constraints, and the full storage options table

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md

@@ -0,0 +1,92 @@
+---
+name: worker-with-kv-storage
+reference: deploy-to-cloudflare
+level: intermediate
+description: 'Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.'
+tags: [deployment, cloudflare, cli, session, worker, kv]
+features:
+  - 'Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`'
+  - 'Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)'
+  - 'Creating the KV namespace via CLI and copying the ID into the configuration'
+---
+
+# Cloudflare Worker with KV Storage
+
+Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'store_value',
+  description: 'Store a value by key',
+  inputSchema: { key: z.string(), value: z.string() },
+})
+class StoreValueTool extends ToolContext<{ key: string; value: string }> {
+  async execute(input: { key: string; value: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `Stored: ${input.key}` }],
+    };
+  }
+}
+
+@App({ name: 'StorageApp', tools: [StoreValueTool] })
+class StorageApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [StorageApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.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"
+```
+
+```bash
+# Create the KV namespace
+wrangler kv:namespace create FRONTMCP_KV
+# Copy the returned id into wrangler.toml
+
+# Store secrets securely (not in [vars])
+wrangler secret put MY_API_KEY
+
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Verify
+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}'
+```
+
+## What This Demonstrates
+
+- Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`
+- Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)
+- Creating the KV namespace via CLI and copying the ID into the configuration
+
+## Related
+
+- See `deploy-to-cloudflare` for D1, Durable Objects, bundle size limits, and storage comparison table