@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md

@@ -0,0 +1,111 @@
+---
+name: feature-folder-organization
+reference: project-structure-standalone
+level: intermediate
+description: 'Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.'
+tags: [setup, structure, standalone, feature, folder, organization]
+features:
+  - 'Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain'
+  - 'Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder'
+  - 'One class per file across tools, resources, and providers'
+  - 'Feature folders scale better than flat `src/tools/` directories for larger projects'
+---
+
+# Feature Folder Organization
+
+Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.
+
+## Code
+
+```typescript
+// src/billing/create-invoice.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'create_invoice',
+  description: 'Create a new invoice',
+  inputSchema: {
+    customerId: z.string(),
+    amount: z.number(),
+    currency: z.string().default('USD'),
+  },
+})
+export default class CreateInvoiceTool extends ToolContext {
+  async execute(input: { customerId: string; amount: number; currency: string }) {
+    return {
+      content: [{ type: 'text', text: `Invoice created for ${input.customerId}: ${input.currency} ${input.amount}` }],
+    };
+  }
+}
+```
+
+```typescript
+// src/billing/invoice.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  uri: 'invoice://latest',
+  name: 'Latest Invoice',
+  mimeType: 'application/json',
+})
+export default class InvoiceResource extends ResourceContext {
+  async read() {
+    return { contents: [{ uri: 'invoice://latest', text: '{"id":"INV-001","amount":100}' }] };
+  }
+}
+```
+
+```typescript
+// src/billing/billing.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider({ name: 'billing-service' })
+export class BillingProvider {
+  getBalance(customerId: string): number {
+    return 500;
+  }
+}
+```
+
+```typescript
+// src/my-app.app.ts
+import { App } from '@frontmcp/sdk';
+import CreateInvoiceTool from './billing/create-invoice.tool';
+import InvoiceResource from './billing/invoice.resource';
+import { BillingProvider } from './billing/billing.provider';
+
+@App({
+  name: 'my-app',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+  providers: [BillingProvider],
+})
+export class MyApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+## What This Demonstrates
+
+- Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain
+- Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder
+- One class per file across tools, resources, and providers
+- Feature folders scale better than flat `src/tools/` directories for larger projects
+
+## Related
+
+- See `project-structure-standalone` for flat layout vs feature folder comparison and naming conventions

package/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md

@@ -0,0 +1,73 @@
+---
+name: minimal-standalone-layout
+reference: project-structure-standalone
+level: basic
+description: 'Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.'
+tags: [setup, structure, standalone, minimal, layout]
+features:
+  - '`<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)'
+  - '`main.ts` with a default-exported `@FrontMcp` server class'
+  - 'One class per file pattern'
+  - '`@App` grouping tools and registered in the server `apps` array'
+---
+
+# Minimal Standalone Project Layout
+
+Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.
+
+## Code
+
+```typescript
+// src/tools/fetch-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'fetch_weather',
+  description: 'Fetch current weather for a city',
+  inputSchema: { city: z.string() },
+})
+export default class FetchWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    return { content: [{ type: 'text', text: `Weather in ${input.city}: 22C, sunny` }] };
+  }
+}
+```
+
+```typescript
+// src/my-app.app.ts
+import { App } from '@frontmcp/sdk';
+import FetchWeatherTool from './tools/fetch-weather.tool';
+
+@App({
+  name: 'my-app',
+  tools: [FetchWeatherTool],
+})
+export class MyApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  info: { name: 'my-project', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+## What This Demonstrates
+
+- `<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)
+- `main.ts` with a default-exported `@FrontMcp` server class
+- One class per file pattern
+- `@App` grouping tools and registered in the server `apps` array
+
+## Related
+
+- See `project-structure-standalone` for the full file layout, naming conventions, and development workflow

package/catalog/frontmcp-setup/examples/readme-guide/node-server-readme.md

@@ -0,0 +1,89 @@
+---
+name: node-server-readme
+reference: readme-guide
+level: basic
+description: 'Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.'
+tags: [setup, docker, readme, node]
+features:
+  - 'Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables'
+  - 'Docker-specific deployment section with build and run commands'
+  - 'Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspect`'
+  - 'Tool and resource tables generated from source code decorators'
+---
+
+# Node.js Server README
+
+Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.
+
+## Code
+
+```markdown
+# My MCP Server
+
+A FrontMCP-based MCP server providing calculator and weather tools.
+
+## Features
+
+- `add` -- Add two numbers together
+- `fetch_weather` -- Fetch current weather for a city
+- `config://app` -- Application configuration resource
+
+## Quick Start
+
+### Docker
+
+docker compose up
+
+### Manual
+
+npm install
+npm run dev
+
+## Tools
+
+| Tool            | Description           | Input                      |
+| --------------- | --------------------- | -------------------------- |
+| `add`           | Add two numbers       | `{ a: number, b: number }` |
+| `fetch_weather` | Fetch current weather | `{ city: string }`         |
+
+## Resources
+
+| URI            | Description               |
+| -------------- | ------------------------- |
+| `config://app` | Application configuration |
+
+## Environment Variables
+
+| Variable     | Required | Description                     |
+| ------------ | -------- | ------------------------------- |
+| `PORT`       | No       | HTTP port (default: 3000)       |
+| `REDIS_HOST` | No       | Redis host (default: localhost) |
+| `REDIS_PORT` | No       | Redis port (default: 6379)      |
+| `LOG_LEVEL`  | No       | Log level (default: info)       |
+
+## Development
+
+frontmcp dev # Start dev server with hot reload
+frontmcp test # Run tests
+frontmcp inspect # Inspect MCP server capabilities
+
+## Docker Deployment
+
+docker build -f ci/Dockerfile -t my-server:latest .
+docker run -p 3000:3000 my-server:latest
+
+## License
+
+MIT
+```
+
+## What This Demonstrates
+
+- Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables
+- Docker-specific deployment section with build and run commands
+- Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspect`
+- Tool and resource tables generated from source code decorators
+
+## Related
+
+- See `readme-guide` for target-specific sections (Vercel, Lambda, Cloudflare, CLI, npm package)

package/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md

@@ -0,0 +1,90 @@
+---
+name: vercel-deployment-readme
+reference: readme-guide
+level: intermediate
+description: 'Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.'
+tags: [setup, vercel-kv, vercel, readme, deployment]
+features:
+  - 'Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`'
+  - 'Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected'
+  - '`vercel.json` configuration reference for route setup'
+  - 'Consistent README structure adapted to the Vercel deployment target'
+---
+
+# Vercel Deployment README
+
+Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.
+
+## Code
+
+```markdown
+# My Vercel MCP Server
+
+A serverless FrontMCP MCP server running on Vercel with Vercel KV for session storage.
+
+## Features
+
+- `lookup_user` -- Look up a user by email
+- `create_ticket` -- Create a support ticket
+- `tickets://open` -- List of open support tickets
+
+## Quick Start
+
+### Deploy to Vercel
+
+npm i -g vercel
+frontmcp build --target vercel
+vercel deploy --prebuilt
+
+### Local Development
+
+npm install
+npm run dev
+
+## Tools
+
+| Tool            | Description             | Input                             |
+| --------------- | ----------------------- | --------------------------------- |
+| `lookup_user`   | Look up a user by email | `{ email: string }`               |
+| `create_ticket` | Create a support ticket | `{ title: string, body: string }` |
+
+## Resources
+
+| URI              | Description          |
+| ---------------- | -------------------- |
+| `tickets://open` | Open support tickets |
+
+## Configuration
+
+See `vercel.json` for route configuration and environment variables.
+
+Set secrets via: `vercel env add REDIS_URL`
+
+## Environment Variables
+
+| Variable            | Required | Description                              |
+| ------------------- | -------- | ---------------------------------------- |
+| `KV_REST_API_URL`   | Yes      | Vercel KV REST API URL (auto-injected)   |
+| `KV_REST_API_TOKEN` | Yes      | Vercel KV REST API token (auto-injected) |
+
+## Development
+
+frontmcp dev # Start dev server
+frontmcp build --target vercel # Build for Vercel
+vercel deploy --prebuilt # Deploy to Vercel
+
+## License
+
+MIT
+```
+
+## What This Demonstrates
+
+- Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`
+- Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected
+- `vercel.json` configuration reference for route setup
+- Consistent README structure adapted to the Vercel deployment target
+
+## Related
+
+- See `readme-guide` for all deployment target README templates and update guidelines

package/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md

@@ -0,0 +1,99 @@
+---
+name: basic-node-server
+reference: setup-project
+level: basic
+description: 'Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.'
+tags: [setup, transport, node]
+features:
+  - 'Minimal `@FrontMcp` server with `info` and `apps` fields'
+  - '`@App` decorator grouping a single tool'
+  - '`@Tool` decorator with Zod input/output schemas extending `ToolContext`'
+  - 'Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`'
+  - '`reflect-metadata` imported as the first line of the entry point'
+---
+
+# Basic Node.js Server Setup
+
+Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.
+
+## Code
+
+```typescript
+// src/tools/add.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'add',
+  description: 'Add two numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: { result: z.number() },
+})
+export default class AddTool extends ToolContext {
+  async execute(input: { a: number; b: number }) {
+    return {
+      result: input.a + input.b,
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/calc.app.ts
+import { App } from '@frontmcp/sdk';
+import AddTool from '../tools/add.tool';
+
+@App({
+  name: 'Calculator',
+  tools: [AddTool],
+})
+export class CalcApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { CalcApp } from './apps/calc.app';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '0.1.0' },
+  apps: [CalcApp],
+  http: { port: 3000 },
+})
+export default class Server {}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## What This Demonstrates
+
+- Minimal `@FrontMcp` server with `info` and `apps` fields
+- `@App` decorator grouping a single tool
+- `@Tool` decorator with Zod input/output schemas extending `ToolContext`
+- Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`
+- `reflect-metadata` imported as the first line of the entry point
+
+## Related
+
+- See `setup-project` for the full scaffolding guide with CLI flags and deployment targets

package/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md

@@ -0,0 +1,77 @@
+---
+name: cli-scaffold-with-flags
+reference: setup-project
+level: basic
+description: 'Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.'
+tags: [setup, redis, cli, nx, scaffold, flags]
+features:
+  - 'Non-interactive scaffolding with `--yes` to accept all defaults'
+  - 'Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags'
+  - 'Nx monorepo scaffolding with `--nx`'
+  - 'Verifying the server responds to MCP `initialize` requests after startup'
+---
+
+# CLI Scaffold with Non-Interactive Flags
+
+Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.
+
+## Code
+
+```bash
+# Scaffold a Node.js server with Docker Redis and yarn
+npx frontmcp create my-api \
+  --target node \
+  --redis docker \
+  --pm yarn \
+  --skills recommended \
+  --cicd \
+  --yes
+```
+
+```bash
+# Scaffold a Vercel serverless project with no Redis
+npx frontmcp create my-vercel-app \
+  --target vercel \
+  --redis none \
+  --pm npm \
+  --skills minimal \
+  --no-cicd \
+  --yes
+```
+
+```bash
+# Scaffold an Nx monorepo workspace
+npx frontmcp create my-workspace \
+  --nx \
+  --target node \
+  --redis docker \
+  --pm yarn \
+  --yes
+```
+
+After scaffolding, start the development server:
+
+```bash
+cd my-api
+yarn install
+yarn dev
+```
+
+Test the server with an MCP initialize request:
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
+```
+
+## What This Demonstrates
+
+- Non-interactive scaffolding with `--yes` to accept all defaults
+- Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags
+- Nx monorepo scaffolding with `--nx`
+- Verifying the server responds to MCP `initialize` requests after startup
+
+## Related
+
+- See `setup-project` for the full list of CLI flags and manual setup instructions

package/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md

@@ -0,0 +1,89 @@
+---
+name: vercel-serverless-server
+reference: setup-project
+level: intermediate
+description: 'Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.'
+tags: [setup, vercel-kv, redis, vercel, session, transport]
+features:
+  - "`transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel"
+  - "`redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning"
+  - 'Building with `frontmcp build --target vercel` for serverless output'
+  - 'Vercel KV credentials are auto-injected via environment variables'
+---
+
+# Vercel Serverless Deployment Setup
+
+Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.
+
+## Code
+
+```typescript
+// src/tools/lookup-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup_user',
+  description: 'Look up a user by email',
+  inputSchema: { email: z.string().email() },
+})
+export default class LookupUserTool extends ToolContext {
+  async execute(input: { email: string }) {
+    return { content: [{ type: 'text', text: `User: ${input.email}` }] };
+  }
+}
+```
+
+```typescript
+// src/apps/users.app.ts
+import { App } from '@frontmcp/sdk';
+import LookupUserTool from '../tools/lookup-user.tool';
+
+@App({
+  name: 'Users',
+  tools: [LookupUserTool],
+})
+export class UsersApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { UsersApp } from './apps/users.app';
+
+@FrontMcp({
+  info: { name: 'my-vercel-server', version: '0.1.0' },
+  apps: [UsersApp],
+  transport: { protocol: 'modern' },
+  redis: { provider: 'vercel-kv' },
+})
+export default class Server {}
+```
+
+Build and deploy:
+
+```bash
+# Build for Vercel target
+frontmcp build --target vercel
+
+# Deploy
+vercel deploy --prebuilt
+```
+
+```env
+# .env.local (Vercel auto-injects KV_REST_API_URL and KV_REST_API_TOKEN)
+# No manual Redis config needed for Vercel KV
+```
+
+## What This Demonstrates
+
+- `transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel
+- `redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning
+- Building with `frontmcp build --target vercel` for serverless output
+- Vercel KV credentials are auto-injected via environment variables
+
+## Related
+
+- See `setup-project` for all deployment target configurations (Lambda, Cloudflare)
+- See `setup-redis` for detailed Vercel KV setup and hybrid pub/sub configuration