@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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

@@ -1,33 +1,28 @@
----
-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
+## When to Use This Skill
+
+### Must Use
+
+- 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
 
-Use `--target sdk` when:
+### Skip 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
+- 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 +211,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,213 @@
+# 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`

package/catalog/{deployment/deploy-to-lambda/SKILL.md → frontmcp-deployment/references/deploy-to-lambda.md}

@@ -1,66 +1,35 @@
----
-name: deploy-to-lambda
-description: Deploy a FrontMCP server to AWS Lambda with API Gateway. Use when deploying to AWS, setting up SAM or CDK, or configuring Lambda handlers.
-tags:
-  - deployment
-  - lambda
-  - aws
-  - serverless
-parameters:
-  - name: runtime
-    description: AWS Lambda runtime version
-    type: string
-    required: false
-    default: nodejs22.x
-  - name: memory
-    description: Lambda function memory in MB
-    type: number
-    required: false
-    default: 512
-  - name: timeout
-    description: Lambda function timeout in seconds
-    type: number
-    required: false
-    default: 30
-  - name: region
-    description: AWS region for deployment
-    type: string
-    required: false
-    default: us-east-1
-examples:
-  - scenario: Deploy with SAM
-    parameters:
-      memory: 512
-      timeout: 30
-      region: us-east-1
-    expected-outcome: A FrontMCP server deployed as an AWS Lambda function behind API Gateway, managed by SAM.
-  - scenario: Deploy with CDK
-    parameters:
-      memory: 1024
-      timeout: 60
-      region: eu-west-1
-    expected-outcome: A FrontMCP server deployed via AWS CDK with API Gateway and Lambda.
-compatibility: AWS CLI and SAM CLI required
-license: Apache-2.0
-visibility: both
-priority: 10
-metadata:
-  category: deployment
-  difficulty: advanced
-  platform: aws
-  docs: https://docs.agentfront.dev/frontmcp/deployment/serverless
----
-
 # Deploy a FrontMCP Server to AWS Lambda
 
 This skill walks you through deploying a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK.
 
+## When to Use This Skill
+
+### Must Use
+
+- Deploying a FrontMCP server to AWS Lambda behind API Gateway
+- Setting up a SAM or CDK stack for a serverless MCP endpoint on AWS
+- Integrating with AWS-native services like ElastiCache, Secrets Manager, or CloudWatch
+
+### Recommended
+
+- Your organization standardizes on AWS and you need IAM-based access control
+- You want provisioned concurrency for predictable latency on critical MCP endpoints
+- Deploying across multiple AWS regions with infrastructure-as-code (SAM or CDK)
+
+### Skip When
+
+- Deploying to Vercel or you prefer a simpler serverless DX -- use `deploy-to-vercel` instead
+- You need a long-lived process with WebSockets or persistent connections -- use `deploy-to-node` instead
+- You do not use AWS and want to avoid managing IAM roles, VPCs, and CloudFormation stacks
+
+> **Decision:** Choose this skill when you need serverless deployment within the AWS ecosystem; choose a different target when you want simpler ops or a non-AWS platform.
+
 ## Prerequisites
 
 - AWS account with appropriate IAM permissions
 - AWS CLI configured: `aws configure`
 - SAM CLI installed: `brew install aws-sam-cli` (macOS) or see AWS docs
-- Node.js 22 or later
+- Node.js 24 or later
 - A FrontMCP project ready to build
 
 ## Step 1: Build for Lambda
@@ -83,7 +52,7 @@ Description: FrontMCP server on AWS Lambda
 Globals:
   Function:
     Timeout: 30
-    Runtime: nodejs22.x
+    Runtime: nodejs24.x
     MemorySize: 512
     Environment:
       Variables:
@@ -94,7 +63,7 @@ Resources:
   FrontMcpFunction:
     Type: AWS::Serverless::Function
     Properties:
-      Handler: dist/lambda.handler
+      Handler: handler.handler
       CodeUri: .
       Description: FrontMCP MCP server
       Architectures:
@@ -169,7 +138,7 @@ Resources:
 
 ## Step 4: Handler Configuration
 
-FrontMCP generates a Lambda handler at `dist/lambda.handler` during the build step. To customize the handler, create a `lambda.ts` entry point:
+FrontMCP generates a Lambda handler file (`handler.cjs` with a `handler` export) during the build step. In SAM/CDK, reference it as `handler.handler`. To customize the handler, create a `lambda.ts` entry point:
 
 ```typescript
 import { createLambdaHandler } from '@frontmcp/adapters/lambda';
@@ -233,8 +202,8 @@ import * as apigw from 'aws-cdk-lib/aws-apigatewayv2';
 import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 
 const fn = new lambda.Function(this, 'FrontMcpHandler', {
-  runtime: lambda.Runtime.NODEJS_22_X,
-  handler: 'dist/lambda.handler',
+  runtime: lambda.Runtime.NODEJS_24_X,
+  handler: 'handler.handler',
   code: lambda.Code.fromAsset('.'),
   memorySize: 512,
   timeout: cdk.Duration.seconds(30),
@@ -296,9 +265,53 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 | 512 MB  | ~500ms             | ~700ms           |
 | 1024 MB | ~350ms             | ~500ms           |
 
+## Common Patterns
+
+| Pattern            | Correct                                                        | Incorrect                               | Why                                                                                                |
+| ------------------ | -------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Build command      | `frontmcp build --target lambda`                               | `tsc` or generic bundler                | The Lambda target produces a single optimized handler with tree-shaking for cold-start performance |
+| Architecture       | `arm64` (Graviton)                                             | `x86_64`                                | ARM64 functions initialize faster and cost less per ms of compute                                  |
+| Handler path       | `handler.handler` in SAM template                              | `index.handler` or `src/lambda.handler` | The FrontMCP build outputs to `dist/`; mismatched paths cause 502 errors                           |
+| Secrets management | SSM Parameter Store or Secrets Manager (`{{resolve:ssm:...}}`) | Plaintext env vars in `template.yaml`   | SSM/Secrets Manager encrypts values at rest and supports rotation                                  |
+| Redis connectivity | Lambda in same VPC as ElastiCache with security groups         | Public Redis endpoint from Lambda       | VPC peering ensures low latency and keeps traffic off the public internet                          |
+
+## Verification Checklist
+
+**Build**
+
+- [ ] `frontmcp build --target lambda` completes without errors
+- [ ] `handler.handler` exists and exports a `handler` function
+
+**SAM / CDK**
+
+- [ ] `sam build` succeeds without errors
+- [ ] `sam deploy --guided` creates the CloudFormation stack
+- [ ] Stack outputs include the API Gateway endpoint URL
+
+**Runtime**
+
+- [ ] `curl https://<api-id>.execute-api.<region>.amazonaws.com/health` returns `{"status":"ok"}`
+- [ ] CloudWatch Logs show successful invocations without errors
+- [ ] `NODE_ENV` is set to `production` in the function configuration
+
+**Production Readiness**
+
+- [ ] Sensitive values use SSM Parameter Store or Secrets Manager
+- [ ] Log retention is configured (e.g., 14 days)
+- [ ] If using Redis, Lambda is in the same VPC as ElastiCache with correct security groups
+- [ ] Provisioned concurrency is enabled for latency-sensitive endpoints (if applicable)
+
 ## Troubleshooting
 
-- **Timeout errors**: Increase `Timeout` in the SAM template. Check if the function is waiting on an unreachable resource.
-- **502 Bad Gateway**: Check CloudWatch logs. Common causes: handler path mismatch, missing environment variables, unhandled exceptions.
-- **Cold starts too slow**: Increase memory allocation, use ARM64, or enable provisioned concurrency.
-- **Redis from Lambda**: Place the Lambda function in the same VPC as your ElastiCache cluster with appropriate security groups.
+| Problem                              | Cause                                                           | Solution                                                                                                  |
+| ------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Timeout errors                       | Function timeout too low or waiting on unreachable resource     | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                       |
+| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler` matches `handler.handler`                                        |
+| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                   | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                |
+| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
+| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
+
+## Reference
+
+- **Docs:** https://docs.agentfront.dev/frontmcp/deployment/serverless
+- **Related skills:** `deploy-to-node`, `deploy-to-vercel`

package/catalog/{deployment/deploy-to-node/references/Dockerfile.example → frontmcp-deployment/references/deploy-to-node-dockerfile.md}

@@ -1,45 +1,54 @@
 # ---- Build Stage ----
-FROM node:22-alpine AS builder
+
+FROM node:24-alpine AS builder
 
 WORKDIR /app
 
 # Install dependencies first for better layer caching
+
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
 
 # Copy source and build
+
 COPY . .
 RUN yarn frontmcp build --target node
 
 # ---- Production Stage ----
-FROM node:22-alpine AS production
+
+FROM node:24-alpine AS production
 
 WORKDIR /app
 
 # Create non-root user for security
+
 RUN addgroup -S frontmcp && adduser -S frontmcp -G frontmcp
 
 # Copy only production artifacts
+
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/package.json ./
 COPY --from=builder /app/yarn.lock ./
 
 # Install production dependencies only
+
 RUN yarn install --frozen-lockfile --production && \
-    yarn cache clean
+ yarn cache clean
 
 # Set ownership
+
 RUN chown -R frontmcp:frontmcp /app
 
 USER frontmcp
 
 # Environment defaults
+
 ENV NODE_ENV=production
 ENV PORT=3000
 
 EXPOSE 3000
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+ CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
 CMD ["node", "dist/main.js"]