@frontmcp/skills 0.0.1 → 1.0.0-beta.11

package/catalog/frontmcp-production-readiness/references/production-cli-daemon.md

@@ -0,0 +1,61 @@
+---
+name: production-cli-daemon
+description: Checklist for deploying FrontMCP as a long-running local daemon with socket transport
+---
+
+# Production Readiness: CLI Daemon (Local MCP Server)
+
+Checklist for deploying FrontMCP as a long-running local MCP server managed by the FrontMCP process manager (`frontmcp start/stop/restart`).
+
+> Run the `common-checklist` first, then use this checklist for daemon-specific items.
+
+## Process Management
+
+- [ ] Server starts via `frontmcp start <name> --entry ./src/main.ts`
+- [ ] `frontmcp stop <name>` cleanly shuts down the daemon
+- [ ] `frontmcp restart <name>` works without orphaned processes
+- [ ] `frontmcp status` shows the daemon as running
+- [ ] `frontmcp logs <name> --follow` streams daemon output
+
+## Socket / Transport
+
+- [ ] Unix socket path is configured: `http: { socketPath: '/tmp/my-app.sock' }`
+- [ ] Socket file is cleaned up on shutdown (no stale `.sock` files)
+- [ ] Stdio transport works as fallback: `frontmcp socket ./src/main.ts`
+- [ ] Socket permissions are restrictive (only the owning user can connect)
+
+## Service Registration
+
+- [ ] `frontmcp service install <name>` registers as a system service (launchd/systemd)
+- [ ] Service starts automatically on boot (if desired)
+- [ ] Service restarts on crash with backoff
+- [ ] Logs are captured by the system journal / log file
+
+## Storage
+
+- [ ] SQLite used for local persistence (session, cache)
+- [ ] Database file location is configurable (not hardcoded)
+- [ ] WAL mode enabled for concurrent reads
+- [ ] Automatic migration on startup (if schema changes)
+- [ ] Redis optional (only if shared state is needed between instances)
+
+## Graceful Shutdown
+
+- [ ] SIGTERM handler completes in-flight requests
+- [ ] Database connections are closed
+- [ ] Socket file is removed
+- [ ] PID file is cleaned up
+
+## Health & Monitoring
+
+- [ ] `/health` endpoint responds on the socket
+- [ ] Startup errors are logged clearly (not swallowed)
+- [ ] `frontmcp doctor` passes all checks
+- [ ] Memory usage is stable over time (no leaks)
+
+## Security
+
+- [ ] Socket file has restrictive permissions
+- [ ] No network exposure (socket-only, not TCP)
+- [ ] Secrets stored in config file with `600` permissions
+- [ ] Config stored in `~/.config/<app>/` or XDG directories

package/catalog/frontmcp-production-readiness/references/production-cloudflare.md

@@ -0,0 +1,52 @@
+---
+name: production-cloudflare
+description: Checklist for deploying FrontMCP to Cloudflare Workers with KV and Durable Objects
+---
+
+# Production Readiness: Cloudflare Workers
+
+Target-specific checklist for deploying FrontMCP to Cloudflare Workers.
+
+> Run the `common-checklist` first, then use this checklist for Cloudflare-specific items.
+
+## Wrangler Configuration
+
+- [ ] `wrangler.toml` is configured with correct routes and bindings
+- [ ] `frontmcp build --target cloudflare` produces the correct output
+- [ ] Environment variables are set via `wrangler secret put` or dashboard
+- [ ] Custom domain or `*.workers.dev` subdomain is configured for CORS
+
+## Workers Runtime
+
+- [ ] No Node.js-only APIs used (Workers use V8 isolates, not Node)
+- [ ] No `node:crypto` or `node:fs` — use `@frontmcp/utils` or Web APIs
+- [ ] Bundle size is within Workers limits (< 10MB compressed)
+- [ ] No `eval()` or dynamic `Function()` (prohibited in Workers)
+- [ ] Async I/O only — no synchronous blocking operations
+
+## Storage
+
+- [ ] Session storage uses Workers KV, Durable Objects, or D1
+- [ ] Cache uses Workers KV or Cache API
+- [ ] No file system access (Workers have no filesystem)
+- [ ] R2 is used for blob/file storage if needed
+
+## Performance
+
+- [ ] Cold start time is within Workers limits (< 50ms)
+- [ ] No heavy initialization at module scope
+- [ ] Lazy-load dependencies
+- [ ] Request handling completes within CPU time limits
+
+## Scaling
+
+- [ ] Stateless design (Workers are ephemeral)
+- [ ] Durable Objects used for stateful coordination (if needed)
+- [ ] No in-memory caching between requests (use KV instead)
+
+## CI/CD
+
+- [ ] `wrangler.toml` environment configs for staging/production
+- [ ] Secrets set via `wrangler secret put`
+- [ ] Deploy with `wrangler deploy` (not manual upload)
+- [ ] Tail logs: `wrangler tail` for production debugging

package/catalog/frontmcp-production-readiness/references/production-lambda.md

@@ -0,0 +1,53 @@
+---
+name: production-lambda
+description: Checklist for deploying FrontMCP to AWS Lambda with SAM, API Gateway, and DynamoDB
+---
+
+# Production Readiness: AWS Lambda
+
+Target-specific checklist for deploying FrontMCP to AWS Lambda.
+
+> Run the `common-checklist` first, then use this checklist for Lambda-specific items.
+
+## SAM / CloudFormation
+
+- [ ] `ci/template.yaml` (SAM template) is configured correctly
+- [ ] `frontmcp build --target lambda` produces the correct handler
+- [ ] Environment variables are set in the SAM template or SSM Parameter Store
+- [ ] API Gateway is configured with correct routes and CORS
+- [ ] Lambda function memory and timeout are set appropriately
+
+## Lambda Runtime
+
+- [ ] Handler exports are correct for the Lambda runtime
+- [ ] No long-lived connections assumed (Lambda freezes between invocations)
+- [ ] No `node:fs` writes to `/tmp` that exceed 512MB
+- [ ] Connection reuse pattern is used for external services
+
+## Storage
+
+- [ ] Session storage uses DynamoDB or ElastiCache (not in-memory)
+- [ ] Cache uses DynamoDB or ElastiCache
+- [ ] Secrets use AWS SSM Parameter Store or Secrets Manager
+- [ ] S3 is used for blob/file storage if needed
+
+## Cold Starts
+
+- [ ] Bundle is tree-shaken to minimize size
+- [ ] Provisioned concurrency is configured for latency-sensitive endpoints
+- [ ] Lazy initialization pattern for database connections
+- [ ] No heavy imports at module scope
+
+## Scaling
+
+- [ ] Concurrency limits are set to prevent downstream overload
+- [ ] Reserved concurrency for critical functions
+- [ ] Dead letter queue (DLQ) configured for failed invocations
+- [ ] Connection pooling accounts for Lambda concurrency (use RDS Proxy if needed)
+
+## CI/CD
+
+- [ ] `sam build && sam deploy` works from CI
+- [ ] Staging and production stages are separate
+- [ ] API Gateway stages are configured correctly
+- [ ] CloudWatch alarms are set for errors and throttling

package/catalog/frontmcp-production-readiness/references/production-node-sdk.md

@@ -0,0 +1,66 @@
+---
+name: production-node-sdk
+description: Checklist for publishing FrontMCP as an embedded npm package used as a direct client SDK
+---
+
+# Production Readiness: Node.js Direct Client (SDK)
+
+Checklist for publishing FrontMCP as an npm package used as a direct client SDK — embedded in someone else's Node.js application, not running as a standalone server.
+
+> Run the `common-checklist` first, then use this checklist for SDK-specific items.
+
+## API Surface
+
+- [ ] `create()` function is exported and documented
+- [ ] Server's `connect()` method returns a typed client with `listTools`, `callTool`, etc.
+- [ ] Client provides `close()` method to terminate the connection
+- [ ] Server `dispose()` and client `close()` must completely release all resources (connections, timers, listeners)
+- [ ] TypeScript declarations (`.d.ts`) are included in the published package
+- [ ] `package.json` has correct `main`, `module`, `types`, and `exports` fields (CJS + ESM entry points)
+
+## Initialization & Lifecycle
+
+- [ ] `create()` does not bind a port (SDK mode, not server mode)
+- [ ] `serve: false` is set in the FrontMCP config (or uses direct API)
+- [ ] Initialization is async and returns a promise
+- [ ] No side effects at import time (no top-level `await`, no global state)
+- [ ] Multiple instances can coexist without conflicts
+
+## Memory & Cleanup
+
+- [ ] `client.close()` and `server.dispose()` are called in the host app's shutdown handler
+- [ ] No event listener leaks (all listeners are removed on dispose)
+- [ ] No dangling timers or intervals after dispose
+- [ ] Provider lifecycle `dispose()` is implemented for all resources
+- [ ] Memory usage is bounded (no unbounded caches or queues)
+
+## npm Publishing
+
+- [ ] Package name is available on npm
+- [ ] `package.json` has `name`, `version`, `description`, `keywords`, `license`
+- [ ] `files` field includes only: `dist/`, `README.md`, `LICENSE`
+- [ ] `peerDependencies` are declared for shared packages (e.g., `zod`)
+- [ ] `engines.node` matches required Node.js version
+- [ ] `README.md` has usage examples with `create()` and `connect()` API
+
+## Testing
+
+- [ ] Unit tests cover tool execution via direct client
+- [ ] Integration tests verify `create()` → `connect()` → `callTool()` → `close()` → `dispose()`
+- [ ] No tests depend on a running HTTP server
+- [ ] Tests clean up (dispose) after each test case
+
+## Example Usage in README
+
+```typescript
+import { create } from 'my-mcp-package';
+
+const server = await create();
+const client = await server.connect();
+
+const tools = await client.listTools();
+const result = await client.callTool('my_tool', { input: 'value' });
+
+await client.close();
+await server.dispose();
+```

package/catalog/frontmcp-production-readiness/references/production-node-server.md

@@ -0,0 +1,61 @@
+---
+name: production-node-server
+description: Checklist for deploying FrontMCP as a long-running Node.js server with Docker
+---
+
+# Production Readiness: Node.js / Docker
+
+Target-specific checklist for deploying FrontMCP as a long-running Node.js server (with or without Docker).
+
+> Run the `common-checklist` first, then use this checklist for Node-specific items.
+
+## Docker
+
+- [ ] Dockerfile uses multi-stage build (separate build and runtime stages)
+- [ ] Base image is minimal (`node:24-slim`, not full `node` image)
+- [ ] Non-root user is configured: `USER node`
+- [ ] `.dockerignore` excludes: `node_modules`, `.git`, `.env`, `dist`, `coverage`
+- [ ] Container health check is defined: `HEALTHCHECK CMD curl -f http://localhost:3000/health`
+- [ ] Resource limits (memory, CPU) are set in docker-compose or k8s deployment
+- [ ] `NODE_ENV=production` is set in the container
+
+## Process Management
+
+- [ ] SIGTERM handler is configured for graceful shutdown
+- [ ] In-flight requests complete before process exit
+- [ ] Redis/database connections are closed on shutdown
+- [ ] Health check returns unhealthy during shutdown drain period
+- [ ] `/health` endpoint is implemented and monitored
+- [ ] Health check verifies downstream dependencies (Redis, databases)
+- [ ] Readiness probe is separate from liveness probe (if using K8s)
+
+## Storage
+
+- [ ] Redis is used for session storage (not in-memory)
+- [ ] Redis connection pooling is configured
+- [ ] Database connections use connection pools with limits
+- [ ] Connection timeouts are set (don't hang indefinitely)
+- [ ] Cache uses Redis (not in-memory) for multi-instance consistency
+
+## Scaling
+
+- [ ] Server is stateless (session state in Redis, not memory)
+- [ ] Multiple instances can run behind a load balancer
+- [ ] WebSocket/SSE connections use sticky sessions or Redis pub/sub
+- [ ] Auto-scaling is configured based on CPU/memory/request metrics
+
+## CI/CD
+
+- [ ] Tests run on every PR (unit + E2E)
+- [ ] `frontmcp build --target node` produces optimized output
+- [ ] Docker image is built and pushed automatically
+- [ ] Deployment is automated with rollback capability
+- [ ] Database migrations run as a separate step
+
+## Environment
+
+- [ ] `NODE_ENV=production` is set
+- [ ] All required env vars are documented in `.env.example`
+- [ ] Env vars are validated at startup (fail fast on missing config)
+- [ ] Port binding uses `process.env.PORT`
+- [ ] No dev dependencies installed in production image

package/catalog/frontmcp-production-readiness/references/production-vercel.md

@@ -0,0 +1,52 @@
+---
+name: production-vercel
+description: Checklist for deploying FrontMCP to Vercel serverless or edge functions with Vercel KV
+---
+
+# Production Readiness: Vercel / Edge
+
+Target-specific checklist for deploying FrontMCP to Vercel serverless or edge functions.
+
+> Run the `common-checklist` first, then use this checklist for Vercel-specific items.
+
+## Vercel Configuration
+
+- [ ] `vercel.json` is configured with correct function routes
+- [ ] `frontmcp build --target vercel` produces the correct output
+- [ ] Environment variables are set in Vercel dashboard (not `.env`)
+- [ ] `VERCEL_URL` or custom domain is configured for CORS origins
+
+## Edge Runtime
+
+- [ ] No Node.js-only APIs used (no `fs`, `child_process`, `net`)
+- [ ] No `node:crypto` direct imports — use `@frontmcp/utils` (cross-platform)
+- [ ] No large npm packages that exceed edge bundle size limits
+- [ ] Streaming responses work correctly on the edge runtime
+
+## Session & Storage
+
+- [ ] Session storage uses Vercel KV (not in-memory or Redis)
+- [ ] Cache uses Vercel KV or edge-compatible store
+- [ ] No file system access (serverless is ephemeral)
+- [ ] SQLite is NOT used (not available on serverless)
+
+## Cold Starts
+
+- [ ] Server startup time is minimal (< 1s target for cold starts)
+- [ ] Lazy-load expensive dependencies
+- [ ] No heavy initialization in module scope
+- [ ] OpenAPI spec is cached (not fetched on every invocation)
+
+## Scaling
+
+- [ ] Stateless design (no in-memory state between invocations)
+- [ ] Connection pooling accounts for serverless concurrency
+- [ ] Function timeout is set appropriately in vercel.json
+- [ ] Memory allocation matches workload
+
+## CI/CD
+
+- [ ] `vercel.json` routes are correct
+- [ ] Environment variables are set in Vercel project settings
+- [ ] Preview deployments test the full MCP flow
+- [ ] Production deployment uses `npx vercel --prod`

package/catalog/frontmcp-setup/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: frontmcp-setup
+description: "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'."
+tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
+category: setup
+targets: [all]
+bundle: [recommended, minimal, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/getting-started/quickstart
+---
+
+# FrontMCP Setup Router
+
+Entry point for project setup and scaffolding. This skill helps you find the right setup guide based on your project needs — from initial scaffolding to storage backends, project structure, and multi-app composition.
+
+## When to Use This Skill
+
+### Must Use
+
+- Starting a new FrontMCP project from scratch and need to choose between standalone vs Nx monorepo
+- Setting up storage backends (Redis, SQLite) for session or state management
+- Organizing an existing project and need canonical directory layout guidance
+
+### Recommended
+
+- Onboarding to the FrontMCP project structure and naming conventions
+- Setting up multi-app composition within a single server
+- Understanding the skills system and how to browse, install, and manage skills
+
+### Skip When
+
+- You need to build specific components like tools or resources (see `frontmcp-development`)
+- You need to configure transport, auth, or throttling (see `frontmcp-config`)
+- You need to deploy or build for a target platform (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill when you need to CREATE or ORGANIZE a project. Use other routers when you need to build, configure, deploy, or test.
+
+## Prerequisites
+
+- Node.js 24+ and npm/yarn installed
+- `frontmcp` CLI available globally (`npm install -g frontmcp`)
+
+## Steps
+
+1. Use the Scenario Routing Table below to find the right setup guide for your task
+2. Scaffold your project with `frontmcp create` (standalone) or `frontmcp create --nx` (monorepo)
+3. Configure storage and project structure per the relevant reference files
+4. Follow the Recommended Reading Order for a complete setup walkthrough
+
+## Scenario Routing Table
+
+| Scenario                                      | Reference                                    | Description                                                                                  |
+| --------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`) |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                       |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                  |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                                           |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                      |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                             |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                                                    |
+| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                              |
+
+## Recommended Reading Order
+
+1. **`references/setup-project.md`** — Start here for any new project
+2. **`references/project-structure-standalone.md`** or **`references/project-structure-nx.md`** — Choose your layout
+3. **`references/setup-redis.md`** or **`references/setup-sqlite.md`** — Add storage if needed
+4. **`references/multi-app-composition.md`** — Scale to multiple apps (when needed)
+5. **`references/nx-workflow.md`** — Nx-specific build and CI commands (if using Nx)
+6. **`references/frontmcp-skills-usage.md`** — Learn the skills system
+7. **`references/readme-guide.md`** — Generate README for your deployment target
+
+## Cross-Cutting Patterns
+
+| Pattern        | Rule                                                                             |
+| -------------- | -------------------------------------------------------------------------------- |
+| Project type   | Standalone for single-app projects; Nx for multi-app or team projects            |
+| File naming    | `<name>.<type>.ts` (e.g., `fetch-weather.tool.ts`) everywhere                    |
+| Test naming    | `.spec.ts` extension (not `.test.ts`)                                            |
+| Entry point    | `main.ts` must `export default` the `@FrontMcp` class                            |
+| Storage choice | Redis for production/serverless; SQLite for local dev/CLI; memory for tests only |
+| App boundaries | Each `@App` is a self-contained module; shared logic goes in providers           |
+
+## Common Patterns
+
+| Pattern               | Correct                                         | Incorrect                                    | Why                                                               |
+| --------------------- | ----------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| Project scaffolding   | `frontmcp create` or `frontmcp create --nx`     | Manual setup from scratch                    | CLI sets up correct structure, dependencies, and config files     |
+| Entry point           | `export default class MyServer` in `main.ts`    | Named export or no default export            | FrontMCP loads the default export at startup                      |
+| Storage in production | Redis or platform-native (Vercel KV, DynamoDB)  | Memory store or SQLite                       | Memory is lost on restart; SQLite doesn't work on serverless      |
+| Multi-app composition | Separate `@App` classes composed in `@FrontMcp` | One giant `@App` with all components         | Separate apps enable independent testing and modular architecture |
+| File organization     | Feature folders for 10+ components              | Flat `tools/` directory with dozens of files | Feature folders make domain boundaries visible                    |
+
+## Verification Checklist
+
+### Project Structure
+
+- [ ] `main.ts` exists with `export default` of `@FrontMcp` class
+- [ ] At least one `@App` class registered in the server
+- [ ] Files follow `<name>.<type>.ts` naming convention
+- [ ] Test files use `.spec.ts` extension
+
+### Storage
+
+- [ ] Storage backend chosen and configured (Redis/SQLite/memory)
+- [ ] Connection string in environment variables, not hardcoded
+- [ ] Storage accessible from the server process
+
+### Build and Dev
+
+- [ ] `frontmcp dev` starts successfully with file watching
+- [ ] `frontmcp build --target <target>` completes without errors
+- [ ] Tests pass with `frontmcp test` or `nx test`
+
+## Troubleshooting
+
+| Problem                  | Cause                            | Solution                                                              |
+| ------------------------ | -------------------------------- | --------------------------------------------------------------------- |
+| `frontmcp create` fails  | Missing Node.js 24+ or npm/yarn  | Install Node.js 24+ and ensure npm/yarn is available                  |
+| Server fails to start    | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts`                       |
+| Redis connection refused | Redis not running or wrong URL   | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var    |
+| Nx generator not found   | `@frontmcp/nx` not installed     | Run `npm install -D @frontmcp/nx`                                     |
+| Skills not loading       | Skills placed in wrong directory | Catalog skills go in top-level `skills/`, app skills in `src/skills/` |
+
+## Reference
+
+- [Getting Started](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
+- Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`, `frontmcp-guides`