agentfront/frontmcp-setup

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 distributed subscriptions (single-server uses in-memory) | | 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 (search, list, install, read, export, publish), bundles, categories, bulk install | | 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/ |

Examples

Each reference has matching examples under examples/<reference>/:

frontmcp-skills-usage

| Example | Level | Description | | ---------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | | bundle-presets-scaffolding | Intermediate | Use --skills flag during project creation to install a skill bundle preset. | | install-and-search-skills | Basic | Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery. |

multi-app-composition

| Example | Level | Description | | -------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | | local-apps-with-shared-tools | Basic | Compose multiple local @App classes into a server with shared tools available to all apps. | | per-app-auth-and-isolation | Advanced | Configure mixed authentication modes and scope isolation for different apps in a single server. | | remote-and-esm-apps | Intermediate | Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway. |

nx-workflow

| Example | Level | Description | | ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | build-test-affected | Intermediate | Use Nx commands for efficient building, testing, and CI with affected-only execution. | | multi-server-deployment | Advanced | Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets. | | scaffold-and-generate | Basic | Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server. |

project-structure-nx

| Example | Level | Description | | ----------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | | nx-generator-scaffolding | Basic | Use @frontmcp/nx generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates. | | nx-workspace-with-apps | Basic | Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway. | | shared-library-usage | Intermediate | Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports. |

project-structure-standalone

| Example | Level | Description | | ------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | dev-workflow-commands | Basic | Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests. | | feature-folder-organization | Intermediate | Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories. | | minimal-standalone-layout | Basic | Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point. |

readme-guide

| Example | Level | Description | | --------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ | | node-server-readme | Basic | Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources. | | vercel-deployment-readme | Intermediate | Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage. |

setup-project

| Example | Level | Description | | ---------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | basic-node-server | Basic | Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport. | | cli-scaffold-with-flags | Basic | Use the frontmcp create CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager. | | vercel-serverless-server | Intermediate | Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol. |

setup-redis

| Example | Level | Description | | ---------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | docker-redis-local-dev | Basic | Provision Redis with Docker Compose and connect a FrontMCP server for local session storage. | | hybrid-vercel-kv-with-pubsub | Advanced | Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments. | | vercel-kv-serverless | Intermediate | Configure a FrontMCP server with Vercel KV as the session store for serverless deployment. |

setup-sqlite

| Example | Level | Description | | --------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- | | basic-sqlite-setup | Basic | Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled. | | encrypted-sqlite-storage | Intermediate | Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite. | | unix-socket-daemon | Advanced | Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage. |

Accessing This Skill

Skills are distributed as plain SKILL.md files plus a sibling references/ and examples/ tree, so consumers can pick whichever access mode fits:

| Mode | How it works | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | | 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. | | 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. |

The catalog itself is not an MCP server. The skill:// URIs only resolve when a server has been configured to host this skill.

Reference

• Getting Started
• Domain routers: frontmcp-development, frontmcp-deployment, frontmcp-testing, frontmcp-config, frontmcp-guides