1---2name: frontmcp-setup3description: Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.4license: Apache-2.05---67# FrontMCP Setup Router89Entry 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.1011## When to Use This Skill1213### Must Use1415- Starting a new FrontMCP project from scratch and need to choose between standalone vs Nx monorepo16- Setting up storage backends (Redis, SQLite) for session or state management17- Organizing an existing project and need canonical directory layout guidance1819### Recommended2021- Onboarding to the FrontMCP project structure and naming conventions22- Setting up multi-app composition within a single server23- Understanding the skills system and how to browse, install, and manage skills2425### Skip When2627- You need to build specific components like tools or resources (see `frontmcp-development`)28- You need to configure transport, auth, or throttling (see `frontmcp-config`)29- You need to deploy or build for a target platform (see `frontmcp-deployment`)3031> **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.3233## Prerequisites3435- Node.js 24+ and npm/yarn installed36- `frontmcp` CLI available globally (`npm install -g frontmcp`)3738## Steps39401. Use the Scenario Routing Table below to find the right setup guide for your task412. Scaffold your project with `frontmcp create` (standalone) or `frontmcp create --nx` (monorepo)423. Configure storage and project structure per the relevant reference files434. Follow the Recommended Reading Order for a complete setup walkthrough4445## Scenario Routing Table4647| Scenario | Reference | Description |48| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |49| Scaffold a new project with `frontmcp create` | `references/setup-project.md` | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`) |50| Organize a standalone (non-Nx) project | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy |51| Organize an Nx monorepo | `references/project-structure-nx.md` | apps/, libs/, servers/ layout, generators, dependency rules |52| Set up Redis for production storage | `references/setup-redis.md` | Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory) |53| Set up SQLite for local development | `references/setup-sqlite.md` | WAL mode, migration helpers, encryption |54| Compose multiple apps into one server | `references/multi-app-composition.md` | `@FrontMcp` with multiple `@App` classes, cross-app providers |55| Use Nx build, test, and CI commands | `references/nx-workflow.md` | `nx build`, `nx test`, `nx run-many`, caching, affected commands |56| Browse, install, and manage skills | `references/frontmcp-skills-usage.md` | CLI commands (search, list, install, read, export, publish), bundles, categories, bulk install |57| Generate or update project README.md | `references/readme-guide.md` | Deployment-target-aware README for npm, CLI, Docker, serverless |5859## Recommended Reading Order60611. **`references/setup-project.md`** — Start here for any new project622. **`references/project-structure-standalone.md`** or **`references/project-structure-nx.md`** — Choose your layout633. **`references/setup-redis.md`** or **`references/setup-sqlite.md`** — Add storage if needed644. **`references/multi-app-composition.md`** — Scale to multiple apps (when needed)655. **`references/nx-workflow.md`** — Nx-specific build and CI commands (if using Nx)666. **`references/frontmcp-skills-usage.md`** — Learn the skills system677. **`references/readme-guide.md`** — Generate README for your deployment target6869## Cross-Cutting Patterns7071| Pattern | Rule |72| -------------- | -------------------------------------------------------------------------------- |73| Project type | Standalone for single-app projects; Nx for multi-app or team projects |74| File naming | `<name>.<type>.ts` (e.g., `fetch-weather.tool.ts`) everywhere |75| Test naming | `.spec.ts` extension (not `.test.ts`) |76| Entry point | `main.ts` must `export default` the `@FrontMcp` class |77| Storage choice | Redis for production/serverless; SQLite for local dev/CLI; memory for tests only |78| App boundaries | Each `@App` is a self-contained module; shared logic goes in providers |7980## Common Patterns8182| Pattern | Correct | Incorrect | Why |83| --------------------- | ----------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |84| Project scaffolding | `frontmcp create` or `frontmcp create --nx` | Manual setup from scratch | CLI sets up correct structure, dependencies, and config files |85| Entry point | `export default class MyServer` in `main.ts` | Named export or no default export | FrontMCP loads the default export at startup |86| 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 |87| Multi-app composition | Separate `@App` classes composed in `@FrontMcp` | One giant `@App` with all components | Separate apps enable independent testing and modular architecture |88| File organization | Feature folders for 10+ components | Flat `tools/` directory with dozens of files | Feature folders make domain boundaries visible |8990## Verification Checklist9192### Project Structure9394- [ ] `main.ts` exists with `export default` of `@FrontMcp` class95- [ ] At least one `@App` class registered in the server96- [ ] Files follow `<name>.<type>.ts` naming convention97- [ ] Test files use `.spec.ts` extension9899### Storage100101- [ ] Storage backend chosen and configured (Redis/SQLite/memory)102- [ ] Connection string in environment variables, not hardcoded103- [ ] Storage accessible from the server process104105### Build and Dev106107- [ ] `frontmcp dev` starts successfully with file watching108- [ ] `frontmcp build --target <target>` completes without errors109- [ ] Tests pass with `frontmcp test` or `nx test`110111## Troubleshooting112113| Problem | Cause | Solution |114| ------------------------ | -------------------------------- | --------------------------------------------------------------------- |115| `frontmcp create` fails | Missing Node.js 24+ or npm/yarn | Install Node.js 24+ and ensure npm/yarn is available |116| Server fails to start | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts` |117| Redis connection refused | Redis not running or wrong URL | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var |118| Nx generator not found | `@frontmcp/nx` not installed | Run `npm install -D @frontmcp/nx` |119| Skills not loading | Skills placed in wrong directory | Catalog skills go in top-level `skills/`, app skills in `src/skills/` |120121## Examples122123Each reference has matching examples under [`examples/<reference>/`](./examples/):124125### `frontmcp-skills-usage`126127| Example | Level | Description |128| ---------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |129| [`bundle-presets-scaffolding`](./examples/frontmcp-skills-usage/bundle-presets-scaffolding.md) | Intermediate | Use `--skills` flag during project creation to install a skill bundle preset. |130| [`install-and-search-skills`](./examples/frontmcp-skills-usage/install-and-search-skills.md) | Basic | Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery. |131132### `multi-app-composition`133134| Example | Level | Description |135| -------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |136| [`local-apps-with-shared-tools`](./examples/multi-app-composition/local-apps-with-shared-tools.md) | Basic | Compose multiple local `@App` classes into a server with shared tools available to all apps. |137| [`per-app-auth-and-isolation`](./examples/multi-app-composition/per-app-auth-and-isolation.md) | Advanced | Configure mixed authentication modes and scope isolation for different apps in a single server. |138| [`remote-and-esm-apps`](./examples/multi-app-composition/remote-and-esm-apps.md) | Intermediate | Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway. |139140### `nx-workflow`141142| Example | Level | Description |143| ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- |144| [`build-test-affected`](./examples/nx-workflow/build-test-affected.md) | Intermediate | Use Nx commands for efficient building, testing, and CI with affected-only execution. |145| [`multi-server-deployment`](./examples/nx-workflow/multi-server-deployment.md) | Advanced | Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets. |146| [`scaffold-and-generate`](./examples/nx-workflow/scaffold-and-generate.md) | Basic | Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server. |147148### `project-structure-nx`149150| Example | Level | Description |151| ----------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |152| [`nx-generator-scaffolding`](./examples/project-structure-nx/nx-generator-scaffolding.md) | Basic | Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates. |153| [`nx-workspace-with-apps`](./examples/project-structure-nx/nx-workspace-with-apps.md) | Basic | Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway. |154| [`shared-library-usage`](./examples/project-structure-nx/shared-library-usage.md) | Intermediate | Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports. |155156### `project-structure-standalone`157158| Example | Level | Description |159| ------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- |160| [`dev-workflow-commands`](./examples/project-structure-standalone/dev-workflow-commands.md) | Basic | Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests. |161| [`feature-folder-organization`](./examples/project-structure-standalone/feature-folder-organization.md) | Intermediate | Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories. |162| [`minimal-standalone-layout`](./examples/project-structure-standalone/minimal-standalone-layout.md) | Basic | Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point. |163164### `readme-guide`165166| Example | Level | Description |167| --------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |168| [`node-server-readme`](./examples/readme-guide/node-server-readme.md) | Basic | Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources. |169| [`vercel-deployment-readme`](./examples/readme-guide/vercel-deployment-readme.md) | Intermediate | Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage. |170171### `setup-project`172173| Example | Level | Description |174| ---------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |175| [`basic-node-server`](./examples/setup-project/basic-node-server.md) | Basic | Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport. |176| [`cli-scaffold-with-flags`](./examples/setup-project/cli-scaffold-with-flags.md) | Basic | Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager. |177| [`vercel-serverless-server`](./examples/setup-project/vercel-serverless-server.md) | Intermediate | Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol. |178179### `setup-redis`180181| Example | Level | Description |182| ---------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |183| [`docker-redis-local-dev`](./examples/setup-redis/docker-redis-local-dev.md) | Basic | Provision Redis with Docker Compose and connect a FrontMCP server for local session storage. |184| [`hybrid-vercel-kv-with-pubsub`](./examples/setup-redis/hybrid-vercel-kv-with-pubsub.md) | Advanced | Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments. |185| [`vercel-kv-serverless`](./examples/setup-redis/vercel-kv-serverless.md) | Intermediate | Configure a FrontMCP server with Vercel KV as the session store for serverless deployment. |186187### `setup-sqlite`188189| Example | Level | Description |190| --------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |191| [`basic-sqlite-setup`](./examples/setup-sqlite/basic-sqlite-setup.md) | Basic | Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled. |192| [`encrypted-sqlite-storage`](./examples/setup-sqlite/encrypted-sqlite-storage.md) | Intermediate | Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite. |193| [`unix-socket-daemon`](./examples/setup-sqlite/unix-socket-daemon.md) | Advanced | Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage. |194195## Accessing This Skill196197Skills are distributed as plain SKILL.md files plus a sibling `references/`198and `examples/` tree, so consumers can pick whichever access mode fits:199200| Mode | How it works |201| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |202| **Filesystem** | Read `libs/skills/catalog/frontmcp-setup/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point. |203| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-setup`, `frontmcp skills read frontmcp-setup:references/<file>.md`, `frontmcp skills install frontmcp-setup` — no server required. |204| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-setup/SKILL.md`, `skill://frontmcp-setup/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |205206The catalog itself is **not** an MCP server. The `skill://` URIs only resolve207when a server has been configured to host this skill.208209## Reference210211- [Getting Started](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)212- Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`, `frontmcp-guides`
agentfront