@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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

@@ -1,196 +0,0 @@
----
-name: deploy-to-vercel
-description: Deploy a FrontMCP server to Vercel serverless functions. Use when deploying to Vercel, configuring Vercel KV, or setting up serverless MCP.
-tags:
-  - deployment
-  - vercel
-  - serverless
-  - edge
-parameters:
-  - name: region
-    description: Vercel deployment region
-    type: string
-    required: false
-    default: iad1
-  - name: kv-store
-    description: Name of the Vercel KV store to use for session and skill storage
-    type: string
-    required: false
-examples:
-  - scenario: Deploy to Vercel with Vercel KV
-    parameters:
-      kv-store: frontmcp-kv
-    expected-outcome: A FrontMCP server running as Vercel serverless functions with Vercel KV providing persistent storage for sessions and skill state.
-  - scenario: Deploy with custom domain
-    parameters:
-      region: cdg1
-    expected-outcome: A FrontMCP server accessible via a custom domain with automatic TLS, deployed to the Paris region.
-compatibility: Vercel CLI required
-license: Apache-2.0
-visibility: both
-priority: 10
-metadata:
-  category: deployment
-  difficulty: intermediate
-  platform: vercel
-  docs: https://docs.agentfront.dev/frontmcp/deployment/serverless
----
-
-# Deploy a FrontMCP Server to Vercel
-
-This skill guides you through deploying a FrontMCP server to Vercel serverless functions with Vercel KV for persistent storage.
-
-## Prerequisites
-
-- A Vercel account (https://vercel.com)
-- Vercel CLI installed: `npm install -g vercel`
-- A built FrontMCP project
-
-## Step 1: Build for Vercel
-
-```bash
-frontmcp build --target vercel
-```
-
-This produces a Vercel-compatible output structure with an `api/` directory containing the serverless function entry points, optimized bundles for cold-start performance, and a `vercel.json` configuration file.
-
-## Step 2: Configure vercel.json
-
-Create or update `vercel.json` in your project root:
-
-```json
-{
-  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
-  "functions": {
-    "api/frontmcp.ts": {
-      "memory": 1024,
-      "maxDuration": 60
-    }
-  },
-  "regions": ["iad1"],
-  "headers": [
-    {
-      "source": "/(.*)",
-      "headers": [
-        { "key": "X-Content-Type-Options", "value": "nosniff" },
-        { "key": "X-Frame-Options", "value": "DENY" }
-      ]
-    }
-  ]
-}
-```
-
-The rewrite rule sends all requests to the single FrontMCP API handler, which internally routes MCP and HTTP requests.
-
-## Step 3: Configure Vercel KV Storage
-
-Use the `vercel-kv` provider so FrontMCP stores sessions, skill cache, and plugin state in Vercel KV (powered by Upstash Redis):
-
-```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
-
-@App()
-class MyApp {}
-
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [MyApp],
-  redis: { provider: 'vercel-kv' },
-  skillsConfig: {
-    enabled: true,
-    cache: {
-      enabled: true,
-      redis: { provider: 'vercel-kv' },
-      ttlMs: 60000,
-    },
-  },
-})
-class MyServer {}
-```
-
-Provision the KV store in the Vercel dashboard under **Storage > Create Database > KV (Redis)**, then link it to your project. Vercel automatically injects the required environment variables.
-
-## Step 4: Environment Variables
-
-Vercel KV variables are injected automatically when the store is linked. For manual setup or additional configuration, set them in the Vercel dashboard (**Settings > Environment Variables**) or via the CLI:
-
-```bash
-vercel env add KV_REST_API_URL "https://your-kv-store.kv.vercel-storage.com"
-vercel env add KV_REST_API_TOKEN "your-token"
-vercel env add NODE_ENV production
-vercel env add LOG_LEVEL info
-```
-
-| Variable            | Description                    | Required    |
-| ------------------- | ------------------------------ | ----------- |
-| `KV_REST_API_URL`   | Vercel KV REST endpoint        | If using KV |
-| `KV_REST_API_TOKEN` | Vercel KV authentication token | If using KV |
-| `NODE_ENV`          | Runtime environment            | Yes         |
-| `LOG_LEVEL`         | Logging verbosity              | No          |
-
-## Step 5: Deploy
-
-### Preview Deployment
-
-```bash
-vercel
-```
-
-Creates a preview deployment with a unique URL for validation.
-
-### Production Deployment
-
-```bash
-vercel --prod
-```
-
-Deploys to your production domain.
-
-### Custom Domain
-
-```bash
-vercel domains add mcp.example.com
-```
-
-Configure your DNS provider to point the domain to Vercel. TLS certificates are provisioned automatically.
-
-## Step 6: Verify
-
-```bash
-# Health check
-curl https://your-project.vercel.app/health
-
-# Test MCP endpoint
-curl -X POST https://your-project.vercel.app/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
-
-## Cold Start Notes
-
-Vercel serverless functions experience cold starts after periods of inactivity. To minimize impact:
-
-- The `frontmcp build --target vercel` output is optimized for bundle size. Avoid adding unnecessary dependencies.
-- Consider Vercel's **Fluid Compute** for latency-sensitive workloads.
-- Keep function memory at 1024 MB for faster initialization.
-
-### Execution Limits
-
-| Plan       | Max Duration |
-| ---------- | ------------ |
-| Hobby      | 10 seconds   |
-| Pro        | 60 seconds   |
-| Enterprise | 900 seconds  |
-
-Long-running MCP operations should complete within these limits or use streaming responses.
-
-### Statelessness
-
-Serverless functions are stateless between invocations. All persistent state must go through Vercel KV. FrontMCP handles this automatically when `{ provider: 'vercel-kv' }` is configured.
-
-## Troubleshooting
-
-- **Function timeout**: Increase `maxDuration` in `vercel.json` or optimize the operation. Check your Vercel plan limits.
-- **KV connection errors**: Verify the KV store is linked and environment variables are set. Re-link the store in the dashboard if needed.
-- **404 on API routes**: Confirm the rewrite rule in `vercel.json` routes traffic to `/api/frontmcp`.
-- **Bundle too large**: Run `frontmcp build --target vercel --analyze` to inspect the bundle.

package/catalog/deployment/deploy-to-vercel/references/vercel.json.example

@@ -1,60 +0,0 @@
-{
-  "$schema": "https://openapi.vercel.sh/vercel.json",
-  "framework": null,
-  "buildCommand": "frontmcp build --target vercel",
-  "outputDirectory": "dist",
-  "rewrites": [
-    {
-      "source": "/(.*)",
-      "destination": "/api/frontmcp"
-    }
-  ],
-  "functions": {
-    "api/frontmcp.js": {
-      "memory": 512,
-      "maxDuration": 30
-    }
-  },
-  "regions": ["iad1"],
-  "headers": [
-    {
-      "source": "/health",
-      "headers": [
-        {
-          "key": "Cache-Control",
-          "value": "no-store"
-        }
-      ]
-    },
-    {
-      "source": "/mcp",
-      "headers": [
-        {
-          "key": "Cache-Control",
-          "value": "no-store"
-        },
-        {
-          "key": "X-Content-Type-Options",
-          "value": "nosniff"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "headers": [
-        {
-          "key": "X-Frame-Options",
-          "value": "DENY"
-        },
-        {
-          "key": "X-Content-Type-Options",
-          "value": "nosniff"
-        },
-        {
-          "key": "Referrer-Policy",
-          "value": "strict-origin-when-cross-origin"
-        }
-      ]
-    }
-  ]
-}

package/catalog/setup/frontmcp-skills-usage/SKILL.md

@@ -1,200 +0,0 @@
----
-name: frontmcp-skills-usage
-description: Search, install, and manage FrontMCP development skills for Claude Code and Codex. Use when setting up skills for AI-assisted development, choosing between static and dynamic skill delivery, or configuring skill providers.
-tags: [skills, cli, install, claude, codex, search, catalog]
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/skills
----
-
-# FrontMCP Skills — Search, Install, and Usage
-
-FrontMCP ships with a catalog of development skills that teach AI agents (Claude Code, Codex) how to build FrontMCP servers. You can deliver these skills **statically** (copy to disk) or **dynamically** (search on demand via CLI).
-
-## Quick Start
-
-```bash
-# Search for skills about tools
-frontmcp skills search "create tool"
-
-# List all skills
-frontmcp skills list
-
-# Show full skill content
-frontmcp skills show create-tool
-
-# Install a skill for Claude Code
-frontmcp skills install create-tool --provider claude
-
-# Install a skill for Codex
-frontmcp skills install create-tool --provider codex
-```
-
-## CLI Commands
-
-### `frontmcp skills search <query>`
-
-Semantic search through the catalog using weighted text matching (description 3x, tags 2x, name 1x):
-
-```bash
-frontmcp skills search "authentication oauth"
-frontmcp skills search "deploy vercel" --category deployment
-frontmcp skills search "plugin hooks" --tag middleware --limit 5
-```
-
-### `frontmcp skills list`
-
-List all skills, optionally filtered:
-
-```bash
-frontmcp skills list                          # All skills
-frontmcp skills list --category development   # Development skills only
-frontmcp skills list --tag redis              # Skills tagged with redis
-frontmcp skills list --bundle recommended     # Recommended bundle
-```
-
-### `frontmcp skills show <name>`
-
-Print the full SKILL.md content to stdout — useful for piping to AI context:
-
-```bash
-frontmcp skills show create-tool              # Print full skill
-frontmcp skills show configure-auth           # Print auth skill
-```
-
-### `frontmcp skills install <name>`
-
-Copy a skill to a provider-specific directory:
-
-```bash
-# Claude Code — installs to .claude/skills/<name>/SKILL.md
-frontmcp skills install create-tool --provider claude
-
-# Codex — installs to .codex/skills/<name>/SKILL.md
-frontmcp skills install decorators-guide --provider codex
-
-# Custom directory
-frontmcp skills install setup-project --dir ./my-skills
-```
-
-## Two Approaches: Static vs Dynamic
-
-### Static Installation (Copy to Disk)
-
-Install skills once — they live in your project and are always available:
-
-```bash
-# Install for Claude Code
-frontmcp skills install create-tool --provider claude
-frontmcp skills install create-resource --provider claude
-frontmcp skills install configure-auth --provider claude
-
-# Install for Codex
-frontmcp skills install decorators-guide --provider codex
-```
-
-**Directory structure after install:**
-
-```
-my-project/
-├── .claude/
-│   └── skills/
-│       ├── create-tool/
-│       │   ├── SKILL.md
-│       │   └── references/
-│       ├── create-resource/
-│       │   └── SKILL.md
-│       └── configure-auth/
-│           ├── SKILL.md
-│           └── references/
-├── .codex/
-│   └── skills/
-│       └── decorators-guide/
-│           └── SKILL.md
-└── src/
-    └── ...
-```
-
-### Dynamic Search (On-Demand via CLI)
-
-Use the CLI to search and show skills on demand — no installation needed:
-
-```bash
-# Search for what you need
-frontmcp skills search "how to create a tool with zod"
-
-# Pipe skill content directly into context
-frontmcp skills show create-tool
-```
-
-This works because `frontmcp skills show` outputs the full SKILL.md content to stdout.
-
-## Comparison: Static vs Dynamic
-
-| Aspect            | Static Install                        | Dynamic CLI Search                           |
-| ----------------- | ------------------------------------- | -------------------------------------------- |
-| **Setup**         | `frontmcp skills install <name>` once | No setup — just use `frontmcp skills search` |
-| **Availability**  | Always loaded by AI agent             | On-demand, requires CLI invocation           |
-| **Context usage** | Skills in system prompt (uses tokens) | Only loaded when searched (saves tokens)     |
-| **Updates**       | Re-install to update                  | Always uses latest catalog                   |
-| **Offline**       | Works offline after install           | Needs catalog available                      |
-| **Best for**      | Core skills you use daily             | Occasional reference, exploration            |
-| **Token cost**    | Higher (all installed skills loaded)  | Lower (only searched skills loaded)          |
-
-### Recommended Approach
-
-**Install 5-10 core skills statically** for your most common workflows, and use dynamic search for everything else:
-
-```bash
-# Core skills — install statically
-frontmcp skills install setup-project --provider claude
-frontmcp skills install create-tool --provider claude
-frontmcp skills install decorators-guide --provider claude
-frontmcp skills install configure-auth --provider claude
-frontmcp skills install project-structure-standalone --provider claude
-
-# Everything else — search on demand
-frontmcp skills search "deploy to vercel"
-frontmcp skills search "rate limiting"
-frontmcp skills show configure-throttle
-```
-
-## Provider Directories
-
-| Provider    | Install directory                | Auto-loaded by            |
-| ----------- | -------------------------------- | ------------------------- |
-| Claude Code | `.claude/skills/<name>/SKILL.md` | Claude Code system prompt |
-| Codex       | `.codex/skills/<name>/SKILL.md`  | Codex agent context       |
-
-## Bundle Presets
-
-When scaffolding a project, use `--skills` to install a preset bundle:
-
-```bash
-# Recommended bundle (core skills for the deployment target)
-frontmcp create my-app --skills recommended
-
-# Minimal bundle (just project setup + create-tool)
-frontmcp create my-app --skills minimal
-
-# Full bundle (all skills)
-frontmcp create my-app --skills full
-
-# No skills
-frontmcp create my-app --skills none
-```
-
-## Available Categories
-
-```bash
-frontmcp skills list --category setup        # Project setup and configuration
-frontmcp skills list --category config       # Server configuration (transport, HTTP, throttle, elicitation)
-frontmcp skills list --category development  # Creating tools, resources, prompts, agents, skills, providers
-frontmcp skills list --category deployment   # Build and deploy (node, vercel, lambda, cli, browser, sdk)
-frontmcp skills list --category auth         # Authentication and session management
-frontmcp skills list --category plugins      # Official and custom plugins
-frontmcp skills list --category adapters     # OpenAPI and custom adapters
-frontmcp skills list --category testing      # Testing with Jest and @frontmcp/testing
-```

package/catalog/setup/project-structure-nx/SKILL.md

@@ -1,186 +0,0 @@
----
-name: project-structure-nx
-description: Best practices for organizing a FrontMCP Nx monorepo -- apps, libs, servers, generators, and multi-app composition. Use when working with frontmcp create --nx or an Nx workspace.
-tags: [project, structure, nx, monorepo, organization, best-practices]
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/nx-plugin/overview
----
-
-# Nx Monorepo Project Structure
-
-When you scaffold with `frontmcp create --nx` or add FrontMCP to an existing Nx workspace, the recommended layout separates apps, shared libraries, and server entry points:
-
-```
-my-workspace/
-├── apps/                     # @App classes (one app per directory)
-│   ├── billing/
-│   │   ├── src/
-│   │   │   ├── billing.app.ts
-│   │   │   ├── tools/
-│   │   │   ├── resources/
-│   │   │   └── providers/
-│   │   ├── project.json
-│   │   └── tsconfig.json
-│   └── crm/
-│       ├── src/
-│       │   ├── crm.app.ts
-│       │   ├── tools/
-│       │   └── resources/
-│       ├── project.json
-│       └── tsconfig.json
-├── libs/                     # Shared libraries
-│   └── shared-utils/
-│       ├── src/
-│       │   └── index.ts
-│       ├── project.json
-│       └── tsconfig.json
-├── servers/                  # @FrontMcp servers composing apps
-│   └── gateway/
-│       ├── src/
-│       │   └── main.ts       # @FrontMcp default export
-│       ├── project.json
-│       └── tsconfig.json
-├── nx.json
-├── tsconfig.base.json
-├── CLAUDE.md                 # AI config (auto-generated)
-├── AGENTS.md
-├── .mcp.json
-└── .cursorrules
-```
-
-## Directory Roles
-
-### apps/ -- Application Modules
-
-Each directory under `apps/` contains a single `@App` class with its tools, resources, prompts, providers, and plugins:
-
-```typescript
-// apps/billing/src/billing.app.ts
-import { App } from '@frontmcp/sdk';
-import { CreateInvoiceTool } from './tools/create-invoice.tool';
-import { InvoiceResource } from './resources/invoice.resource';
-import { StripeProvider } from './providers/stripe.provider';
-
-@App({
-  name: 'billing',
-  tools: [CreateInvoiceTool],
-  resources: [InvoiceResource],
-  providers: [StripeProvider],
-})
-export class BillingApp {}
-```
-
-Apps are self-contained and independently testable. They do not import from other apps -- shared code goes in `libs/`.
-
-### libs/ -- Shared Libraries
-
-Shared providers, utilities, types, and common logic live under `libs/`:
-
-```typescript
-// libs/shared-utils/src/index.ts
-export { formatCurrency } from './format-currency';
-export { DatabaseProvider } from './database.provider';
-export type { AppConfig } from './app-config.interface';
-```
-
-Apps and servers import from libs using Nx path aliases configured in `tsconfig.base.json`:
-
-```typescript
-import { DatabaseProvider } from '@my-workspace/shared-utils';
-```
-
-### servers/ -- FrontMcp Entry Points
-
-A server composes multiple apps into a single `@FrontMcp` entry point:
-
-```typescript
-// servers/gateway/src/main.ts
-import { FrontMcp } from '@frontmcp/sdk';
-import { BillingApp } from '@my-workspace/billing';
-import { CrmApp } from '@my-workspace/crm';
-
-@FrontMcp({
-  info: { name: 'gateway', version: '1.0.0' },
-  apps: [BillingApp, CrmApp],
-})
-class GatewayServer {}
-
-export default GatewayServer;
-```
-
-You can have multiple servers composing different combinations of apps (e.g., a public-facing server and an internal admin server).
-
-## Nx Generators
-
-The `@frontmcp/nx-plugin` package provides generators for all entity types:
-
-```bash
-# Generate a new app
-nx g @frontmcp/nx-plugin:app crm
-
-# Generate entities within an app
-nx g @frontmcp/nx-plugin:tool lookup-user --project=crm
-nx g @frontmcp/nx-plugin:resource user-profile --project=crm
-nx g @frontmcp/nx-plugin:prompt summarize --project=crm
-nx g @frontmcp/nx-plugin:provider database --project=crm
-nx g @frontmcp/nx-plugin:plugin logging --project=crm
-nx g @frontmcp/nx-plugin:agent research --project=crm
-nx g @frontmcp/nx-plugin:job cleanup --project=crm
-
-# Generate a new server
-nx g @frontmcp/nx-plugin:server gateway
-
-# Generate a shared library
-nx g @frontmcp/nx-plugin:lib shared-utils
-```
-
-## Build and Test Commands
-
-```bash
-# Build a specific server
-nx build gateway
-
-# Test a specific app
-nx test billing
-
-# Run all tests
-nx run-many -t test
-
-# Build all projects
-nx run-many -t build
-
-# Lint everything
-nx run-many -t lint
-```
-
-Nx caches build and test results. Subsequent runs for unchanged projects are instant.
-
-## AI Configuration Files
-
-FrontMCP auto-generates AI configuration files at the workspace root:
-
-| File           | Purpose                                  |
-| -------------- | ---------------------------------------- |
-| `CLAUDE.md`    | Instructions for Claude Code / Claude AI |
-| `AGENTS.md`    | Instructions for agent-based AI tools    |
-| `.mcp.json`    | MCP server configuration for AI IDEs     |
-| `.cursorrules` | Rules for Cursor AI editor               |
-
-These files are regenerated when you run generators or modify your workspace structure. They help AI tools understand your project layout and coding conventions.
-
-## Dependency Graph
-
-Nx enforces a clear dependency hierarchy:
-
-```
-servers/ --> apps/ --> libs/
-```
-
-- **servers** can import from **apps** and **libs**
-- **apps** can import from **libs** only (never from other apps or servers)
-- **libs** can import from other **libs** only
-
-Use `nx graph` to visualize the dependency graph and ensure no circular imports exist.