@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-setup/examples/multi-app-composition/remote-and-esm-apps.md

@@ -0,0 +1,81 @@
+---
+name: remote-and-esm-apps
+reference: multi-app-composition
+level: intermediate
+description: 'Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.'
+tags: [setup, oauth, auth, transport, multi-app, remote]
+features:
+  - '`app.esm()` loads an `@App` class from an npm package with namespace and auto-update'
+  - '`app.remote()` proxies tools from external MCP servers with configurable auth modes'
+  - "`remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), and `'oauth'`"
+  - '`namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)'
+  - '`transportOptions` configure timeout, retries, and SSE fallback for remote connections'
+---
+
+# Remote and ESM App Composition
+
+Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp, App, app } from '@frontmcp/sdk';
+
+@App({
+  id: 'local',
+  name: 'Local Tools',
+  tools: [EchoTool],
+})
+class LocalApp {}
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [
+    // Local app
+    LocalApp,
+
+    // ESM app from npm package
+    app.esm('@acme/crm-tools@^2.0.0', {
+      namespace: 'crm',
+      autoUpdate: { enabled: true, intervalMs: 300_000 },
+    }),
+
+    // Remote MCP server with static auth
+    app.remote('https://slack-mcp.example.com/mcp', {
+      namespace: 'slack',
+      remoteAuth: {
+        mode: 'static',
+        credentials: { type: 'bearer', value: process.env['SLACK_TOKEN']! },
+      },
+      transportOptions: {
+        timeout: 30000,
+        retryAttempts: 3,
+        fallbackToSSE: true,
+      },
+    }),
+
+    // Remote MCP server with forwarded auth
+    app.remote('https://api.internal.com/mcp', {
+      namespace: 'api',
+      remoteAuth: {
+        mode: 'forward',
+      },
+    }),
+  ],
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- `app.esm()` loads an `@App` class from an npm package with namespace and auto-update
+- `app.remote()` proxies tools from external MCP servers with configurable auth modes
+- `remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), and `'oauth'`
+- `namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)
+- `transportOptions` configure timeout, retries, and SSE fallback for remote connections
+
+## Related
+
+- See `multi-app-composition` for scope isolation, per-app auth, and shared plugins

package/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md

@@ -0,0 +1,77 @@
+---
+name: build-test-affected
+reference: nx-workflow
+level: intermediate
+description: 'Use Nx commands for efficient building, testing, and CI with affected-only execution.'
+tags: [setup, nx, workflow, affected]
+features:
+  - '`nx build <server>` resolves the dependency graph and builds with caching'
+  - '`nx affected -t test` only runs tests for changed projects, saving CI time'
+  - '`nx run-many -t build,test,lint` parallelizes multiple targets across all projects'
+  - '`nx graph` visualizes project dependencies to detect circular imports'
+---
+
+# Build, Test, and Affected Commands
+
+Use Nx commands for efficient building, testing, and CI with affected-only execution.
+
+## Code
+
+```bash
+# Build a single server (builds all dependencies in correct order)
+nx build gateway
+
+# Test a single app
+nx test billing
+
+# Run all tests across the workspace
+nx run-many -t test
+
+# Build all projects
+nx run-many -t build
+
+# Lint everything
+nx run-many -t lint
+
+# Run multiple targets at once
+nx run-many -t build,test,lint
+```
+
+```bash
+# CI optimization: only test projects affected by changes
+nx affected -t test
+
+# Only build affected projects
+nx affected -t build
+
+# Visualize the dependency graph
+nx graph
+```
+
+```bash
+# Typical feature development workflow
+# 1. Generate a new tool
+nx g @frontmcp/nx:tool calculate-tax --project=billing
+
+# 2. Implement the tool logic in apps/billing/src/tools/calculate-tax.tool.ts
+
+# 3. Run tests for the affected app
+nx test billing
+
+# 4. Build the server that includes this app
+nx build gateway
+
+# 5. Or test everything affected by your changes
+nx affected -t test
+```
+
+## What This Demonstrates
+
+- `nx build <server>` resolves the dependency graph and builds with caching
+- `nx affected -t test` only runs tests for changed projects, saving CI time
+- `nx run-many -t build,test,lint` parallelizes multiple targets across all projects
+- `nx graph` visualizes project dependencies to detect circular imports
+
+## Related
+
+- See `nx-workflow` for workspace initialization, all generator commands, and troubleshooting

package/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md

@@ -0,0 +1,93 @@
+---
+name: multi-server-deployment
+reference: nx-workflow
+level: advanced
+description: 'Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.'
+tags: [setup, vercel, nx, node, workflow, multi]
+features:
+  - 'Multiple servers composing different combinations of apps from the same workspace'
+  - 'Each server has its own deployment target (`node` vs `vercel`) and storage configuration'
+  - 'Apps are reusable across servers via Nx path aliases'
+  - '`nx build <server>` builds the server and all its app and lib dependencies'
+---
+
+# Multi-Server Deployment Targets
+
+Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.
+
+## Code
+
+```bash
+# Generate apps
+nx g @frontmcp/nx:app billing
+nx g @frontmcp/nx:app crm
+nx g @frontmcp/nx:app admin
+
+# Generate a public gateway (Node.js) composing billing and crm
+nx g @frontmcp/nx:server public-gateway --apps=billing,crm --deploymentTarget=node --redis=docker
+
+# Generate an internal admin server (Vercel) with the admin app
+nx g @frontmcp/nx:server admin-portal --apps=admin --deploymentTarget=vercel
+
+# Generate a shared library for common providers
+nx g @frontmcp/nx:lib shared-db
+```
+
+```typescript
+// servers/public-gateway/src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'public-gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+  http: { port: 3000 },
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: parseInt(process.env['REDIS_PORT'] ?? '6379', 10),
+  },
+})
+class PublicGateway {}
+
+export default PublicGateway;
+```
+
+```typescript
+// servers/admin-portal/src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { AdminApp } from '@my-workspace/admin';
+
+@FrontMcp({
+  info: { name: 'admin-portal', version: '1.0.0' },
+  apps: [AdminApp],
+  transport: { protocol: 'modern' },
+  redis: { provider: 'vercel-kv' },
+})
+class AdminPortal {}
+
+export default AdminPortal;
+```
+
+```bash
+# Build each server independently
+nx build public-gateway
+nx build admin-portal
+
+# Test all projects
+nx run-many -t test
+```
+
+## What This Demonstrates
+
+- Multiple servers composing different combinations of apps from the same workspace
+- Each server has its own deployment target (`node` vs `vercel`) and storage configuration
+- Apps are reusable across servers via Nx path aliases
+- `nx build <server>` builds the server and all its app and lib dependencies
+
+## Related
+
+- See `nx-workflow` for the full generator reference and workspace setup options

package/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md

@@ -0,0 +1,62 @@
+---
+name: scaffold-and-generate
+reference: nx-workflow
+level: basic
+description: 'Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.'
+tags: [setup, nx, workflow, scaffold, generate]
+features:
+  - '`@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`'
+  - 'All primitive generators require `--project=<app-name>` to target the correct app'
+  - 'Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports'
+  - '`@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point'
+---
+
+# Scaffold Workspace and Generate Primitives
+
+Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.
+
+## Code
+
+```bash
+# Option A: New workspace via FrontMCP CLI
+npx frontmcp create my-project --nx
+
+# Option B: Add FrontMCP to existing Nx workspace
+yarn add -D @frontmcp/nx
+nx g @frontmcp/nx:workspace my-workspace
+```
+
+```bash
+# Generate an app
+nx g @frontmcp/nx:app billing
+
+# Generate primitives inside the app
+nx g @frontmcp/nx:tool create-invoice --project=billing
+nx g @frontmcp/nx:resource invoice --project=billing
+nx g @frontmcp/nx:prompt billing-summary --project=billing
+nx g @frontmcp/nx:provider stripe --project=billing
+nx g @frontmcp/nx:plugin audit-log --project=billing
+
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+
+# Generate a server composing the app
+nx g @frontmcp/nx:server gateway --apps=billing --deploymentTarget=node
+```
+
+```bash
+# Verify the generated structure
+nx test billing
+nx build gateway
+```
+
+## What This Demonstrates
+
+- `@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`
+- All primitive generators require `--project=<app-name>` to target the correct app
+- Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports
+- `@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point
+
+## Related
+
+- See `nx-workflow` for the complete generator reference table and CI workflow commands

package/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md

@@ -0,0 +1,73 @@
+---
+name: nx-generator-scaffolding
+reference: project-structure-nx
+level: basic
+description: 'Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.'
+tags: [setup, nx, structure, generator, scaffolding]
+features:
+  - 'All primitive generators require `--project=<app-name>` to target the correct app'
+  - 'Each generator creates the implementation file and a `.spec.ts` test file'
+  - 'Barrel exports (`index.ts`) are updated automatically after each generator run'
+  - 'Files follow the `<name>.<type>.ts` naming convention'
+---
+
+# Nx Generator Scaffolding
+
+Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.
+
+## Code
+
+```bash
+# Generate a tool in the billing app
+nx g @frontmcp/nx:tool create-invoice --project=billing
+
+# Generate a resource in the billing app
+nx g @frontmcp/nx:resource invoice --project=billing
+
+# Generate a provider in the billing app
+nx g @frontmcp/nx:provider stripe --project=billing
+
+# Generate a prompt in the crm app
+nx g @frontmcp/nx:prompt summarize --project=crm
+
+# Generate a plugin in the crm app
+nx g @frontmcp/nx:plugin logging --project=crm
+```
+
+After generation, the app directory looks like:
+
+```text
+apps/billing/
+  src/
+    tools/
+      create-invoice.tool.ts
+      create-invoice.tool.spec.ts
+    resources/
+      invoice.resource.ts
+      invoice.resource.spec.ts
+    providers/
+      stripe.provider.ts
+      stripe.provider.spec.ts
+    billing.app.ts
+    index.ts          # barrel exports updated automatically
+  project.json
+  tsconfig.json
+  jest.config.ts
+```
+
+```bash
+# Build and test the app
+nx test billing
+nx build gateway
+```
+
+## What This Demonstrates
+
+- All primitive generators require `--project=<app-name>` to target the correct app
+- Each generator creates the implementation file and a `.spec.ts` test file
+- Barrel exports (`index.ts`) are updated automatically after each generator run
+- Files follow the `<name>.<type>.ts` naming convention
+
+## Related
+
+- See `project-structure-nx` for the complete generator reference and workspace structure

package/catalog/frontmcp-setup/examples/project-structure-nx/nx-workspace-with-apps.md

@@ -0,0 +1,85 @@
+---
+name: nx-workspace-with-apps
+reference: project-structure-nx
+level: basic
+description: 'Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.'
+tags: [setup, nx, structure, workspace, apps]
+features:
+  - '`apps/` directory holding self-contained `@App` classes with their tools and resources'
+  - '`servers/` directory holding `@FrontMcp` entry points that compose apps'
+  - 'Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo'
+  - 'Apps are independently testable and do not import from each other'
+---
+
+# Nx Workspace with Multiple Apps
+
+Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.
+
+## Code
+
+```bash
+# Scaffold the Nx workspace
+npx frontmcp create my-workspace --nx
+
+cd my-workspace
+
+# Generate two apps
+nx g @frontmcp/nx:app billing
+nx g @frontmcp/nx:app crm
+
+# Generate a server composing both apps
+nx g @frontmcp/nx:server gateway --apps=billing,crm
+```
+
+```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';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+})
+export class BillingApp {}
+```
+
+```typescript
+// apps/crm/src/crm.app.ts
+import { App } from '@frontmcp/sdk';
+import { LookupUserTool } from './tools/lookup-user.tool';
+
+@App({
+  name: 'crm',
+  tools: [LookupUserTool],
+})
+export class CrmApp {}
+```
+
+```typescript
+// servers/gateway/src/main.ts
+import 'reflect-metadata';
+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;
+```
+
+## What This Demonstrates
+
+- `apps/` directory holding self-contained `@App` classes with their tools and resources
+- `servers/` directory holding `@FrontMcp` entry points that compose apps
+- Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo
+- Apps are independently testable and do not import from each other
+
+## Related
+
+- See `project-structure-nx` for the full directory layout, dependency rules, and generator reference

package/catalog/frontmcp-setup/examples/project-structure-nx/shared-library-usage.md

@@ -0,0 +1,89 @@
+---
+name: shared-library-usage
+reference: project-structure-nx
+level: intermediate
+description: 'Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.'
+tags: [setup, nx, database, structure, shared, library]
+features:
+  - 'Shared libraries live in `libs/` with barrel `index.ts` exports'
+  - 'Both apps import `DatabaseProvider` from the shared library, not from each other'
+  - 'Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)'
+  - 'Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)'
+---
+
+# Shared Library Between Apps
+
+Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.
+
+## Code
+
+```bash
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+```
+
+```typescript
+// libs/shared-utils/src/index.ts
+export { formatCurrency } from './format-currency';
+export { DatabaseProvider } from './database.provider';
+export type { AppConfig } from './app-config.interface';
+```
+
+```typescript
+// libs/shared-utils/src/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider({ name: 'database' })
+export class DatabaseProvider {
+  async query(sql: string): Promise<unknown[]> {
+    // shared database access logic
+    return [];
+  }
+}
+```
+
+```typescript
+// libs/shared-utils/src/format-currency.ts
+export function formatCurrency(amount: number, currency: string): string {
+  return `${currency} ${amount.toFixed(2)}`;
+}
+```
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  providers: [DatabaseProvider],
+})
+export class BillingApp {}
+```
+
+```typescript
+// apps/crm/src/crm.app.ts
+import { App } from '@frontmcp/sdk';
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+import { LookupUserTool } from './tools/lookup-user.tool';
+
+@App({
+  name: 'crm',
+  tools: [LookupUserTool],
+  providers: [DatabaseProvider],
+})
+export class CrmApp {}
+```
+
+## What This Demonstrates
+
+- Shared libraries live in `libs/` with barrel `index.ts` exports
+- Both apps import `DatabaseProvider` from the shared library, not from each other
+- Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)
+- Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)
+
+## Related
+
+- See `project-structure-nx` for the full dependency hierarchy and Nx generator commands

package/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md

@@ -0,0 +1,64 @@
+---
+name: dev-workflow-commands
+reference: project-structure-standalone
+level: basic
+description: 'Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.'
+tags: [setup, e2e, structure, standalone, dev, workflow]
+features:
+  - '`frontmcp dev` for hot-reloading development server'
+  - '`frontmcp build --target <target>` for production builds targeting different runtimes'
+  - 'Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention'
+  - 'E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming'
+---
+
+# Development Workflow Commands
+
+Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.
+
+## Code
+
+```bash
+# Start the development server with hot reload
+frontmcp dev
+```
+
+```bash
+# Build for different deployment targets
+frontmcp build --target node
+frontmcp build --target vercel
+frontmcp build --target lambda
+frontmcp build --target cloudflare
+```
+
+```bash
+# Run unit tests (test files use .spec.ts extension)
+jest
+```
+
+```bash
+# Run E2E tests from the e2e/ directory
+jest --config e2e/jest.config.ts
+```
+
+```bash
+# Start the dev server with HTTP transport on a specific port
+PORT=3000 frontmcp dev
+```
+
+```bash
+# Test the running server with an MCP initialize request
+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
+
+- `frontmcp dev` for hot-reloading development server
+- `frontmcp build --target <target>` for production builds targeting different runtimes
+- Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention
+- E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming
+
+## Related
+
+- See `project-structure-standalone` for the full project layout and file naming conventions