Name	Name	Last commit message	Last commit date
parent directory ..
e2e	e2e
src	src
README.md	README.md
frontmcp.schema.json	frontmcp.schema.json
jest.config.ts	jest.config.ts
package.json	package.json
project.json	project.json
tsconfig.json	tsconfig.json
tsconfig.lib.json	tsconfig.lib.json
tsconfig.spec.json	tsconfig.spec.json

frontmcp

Command-line interface for scaffolding, building, and managing FrontMCP server projects.

Install

npm install -g frontmcp
# or use directly
npx frontmcp create my-app

Requires Node.js >= 22

Commands

Development

Command	Description
`frontmcp dev`	Start in development mode (tsx --watch + async type-check)
`frontmcp build`	Compile entry with TypeScript (tsc)
`frontmcp build --exec`	Build distributable executable bundle (esbuild)
`frontmcp build --exec --cli`	Generate CLI with subcommands per tool
`frontmcp test [patterns...]`	Run E2E tests with auto-injected Jest configuration
`frontmcp init`	Create or fix a tsconfig.json suitable for FrontMCP
`frontmcp doctor`	Check Node/npm versions and tsconfig requirements
`frontmcp inspector`	Launch MCP Inspector UI
`frontmcp create [name]`	Scaffold a new FrontMCP project
`frontmcp socket <entry>`	Start Unix socket daemon for local MCP server

Process Manager

Command	Description
`frontmcp start <name>`	Start a named MCP server with supervisor
`frontmcp stop <name>`	Stop a managed server (graceful by default)
`frontmcp restart <name>`	Restart a managed server
`frontmcp status [name]`	Show process status (detail if name given, table if omitted)
`frontmcp list`	List all managed processes
`frontmcp logs <name>`	Tail log output for a managed server
`frontmcp service <action> [name]`	Install/uninstall systemd/launchd service

Package Manager

Command	Description
`frontmcp install <source>`	Install an MCP app from npm, local path, or git
`frontmcp uninstall <name>`	Remove an installed MCP app
`frontmcp configure <name>`	Re-run setup questionnaire for an installed app

MCP Bundles (MCPB)

Command	Description
`frontmcp build --target mcpb`	Package the server into a `.mcpb` archive (MCPB v0.3 spec)
`frontmcp mcpb validate <path>`	Verify an existing `.mcpb` archive against the MCPB v0.3 specification

Options Reference

General

Flag	Description
`-V, --version`	Print version
`-h, --help`	Print help

Build

Flag	Description	Default
`-o, --out-dir <dir>`	Output directory	`dist`
`-e, --entry <path>`	Entry file path	auto-detected
`-a, --adapter <name>`	Deployment adapter: `node`, `vercel`, `lambda`, `cloudflare`	—
`--exec`	Build distributable executable bundle (esbuild)	`false`
`--cli`	Generate CLI with subcommands per tool (use with `--exec`)	`false`

Start

Flag	Description	Default
`-e, --entry <path>`	Entry file for the server	—
`-p, --port <N>`	Port number	—
`-s, --socket <path>`	Unix socket path	—
`--db <path>`	SQLite database path	—
`--max-restarts <N>`	Maximum auto-restart attempts	`5`

Stop

Flag	Description
`-f, --force`	Force kill (SIGKILL instead of SIGTERM)

Logs

Flag	Description	Default
`-F, --follow`	Follow log output (like `tail -f`)	`false`
`-n, --lines <N>`	Number of lines to show	`50`

Socket

Flag	Description	Default
`-s, --socket <path>`	Unix socket path	`~/.frontmcp/sockets/{app}.sock`
`--db <path>`	SQLite database path for persistence	—
`-b, --background`	Run as background daemon (detached process)	`false`

Install

Flag	Description
`--registry <url>`	npm registry URL for private packages
`-y, --yes`	Silent mode (use defaults, skip questionnaire)
`-p, --port <N>`	Override default port

Create

Flag	Description	Default
`-y, --yes`	Use defaults (non-interactive mode)	`false`
`--target <target>`	Deployment target: `node`, `vercel`, `lambda`, `cloudflare`	`node`
`--redis <setup>`	Redis setup: `docker`, `existing`, `none` (node target only)	`docker`
`--pm <pm>`	Package manager: `npm`, `yarn`, `pnpm`	detected
`--cicd / --no-cicd`	Enable/disable GitHub Actions CI/CD	`true`
`--nx`	Scaffold an Nx monorepo instead of standalone project	`false`

Test

Flag	Description	Default
`-i, --runInBand`	Run tests sequentially (recommended for E2E)	`false`
`-w, --watch`	Run tests in watch mode	`false`
`-v, --verbose`	Show verbose test output	`false`
`-t, --timeout <ms>`	Set test timeout	`60000`
`-c, --coverage`	Collect test coverage	`false`

Examples

Project Scaffolding

npx frontmcp create                           # Interactive mode
npx frontmcp create my-mcp --yes              # Use defaults
npx frontmcp create my-mcp --target vercel    # Vercel deployment
npx frontmcp create my-mcp --nx --pm yarn     # Nx monorepo with yarn

Development Workflow

frontmcp dev                        # Start dev server with hot reload
frontmcp build --out-dir build      # Production build
frontmcp test --runInBand           # Run E2E tests sequentially
frontmcp doctor                     # Verify environment setup
frontmcp inspector                  # Launch MCP Inspector UI

Executable Builds

frontmcp build --exec               # Single-file executable bundle
frontmcp build --exec --cli         # CLI with subcommands per tool

MCP Bundles (`.mcpb`)

The mcpb target produces a ZIP archive that can be loaded directly into Claude Desktop (and other MCPB-aware clients) without any install step — the host app extracts the archive and starts the server via stdio.

frontmcp build --target mcpb                         # basic node bundle
frontmcp build --target mcpb --sea                   # include a SEA binary for this OS/arch
frontmcp build --target mcpb --merge-from ./ci-bins  # merge pre-built cross-platform binaries
frontmcp build --target mcpb --stage-only            # leave the staging directory for inspection
frontmcp mcpb validate dist/mcpb/myapp-1.0.0.mcpb    # verify an archive

frontmcp.config:

import { defineConfig } from 'frontmcp';

export default defineConfig({
  name: 'my-server',
  version: '1.2.3',
  deployments: [
    {
      target: 'mcpb',
      displayName: 'My Server',
      author: { name: 'Acme', email: 'hello@acme.dev' },
      license: 'Apache-2.0',
      homepage: 'https://acme.dev/my-server',
      repository: 'https://github.com/acme/my-server',
      icon: 'assets/icon.png',
      compatibility: {
        claude_desktop: '>=1.0.0',
        platforms: ['darwin', 'linux', 'win32'],
        runtimes: { node: '>=22.0.0' },
      },
      sea: { enabled: true },
    },
  ],
});

Fields not declared in the deployment fall back to the project package.json (name, version, description, author, license, homepage, repository, keywords). FrontMCP setup.steps are automatically translated to MCPB user_config and exposed as environment variables at runtime via ${user_config.KEY} substitution in mcp_config.env. Conditional visibility / branching steps (showWhen, next) have no MCPB equivalent — the generator logs a warning and renders them unconditionally.

Cross-platform SEA binaries require a CI matrix build (Node SEA only builds for the host OS/arch in a single pass). Use --merge-from <dir> to assemble pre-built binaries organized as {mergeFromDir}/{platform}/{appName}[.exe].

Generated CLI Features

When built with --exec --cli, the output is a standalone executable with auto-generated commands derived from your MCP server's tools, resources, prompts, and templates. The CLI groups commands into five categories visible in --help output:

Tool subcommands — each MCP tool becomes a kebab-case subcommand with flags generated from its input schema:

./myapp search-users --query "alice" --limit 10
./myapp send-email --to "bob@example.com" --body '{"html": true}'

Object-typed parameters accept JSON strings that are automatically parsed.

Resources & Prompts:

./myapp resource list                          # List available resources
./myapp resource read "file://config.json"     # Read a resource by URI
./myapp template list                          # List resource templates
./myapp template user-profile --user-id 42     # Read a template with parameters
./myapp prompt list                            # List available prompts
./myapp prompt greeting --name "Alice"         # Execute a prompt with arguments

Auth & Sessions:

./myapp login --server https://auth.example.com   # OAuth PKCE login
./myapp logout --all                               # Clear all stored credentials
./myapp sessions list                              # List saved sessions
./myapp sessions switch production                 # Switch active session
./myapp connect --token <TOKEN>                    # Connect with a bearer token

Subscriptions:

./myapp subscribe resource "file://config.json"   # Stream resource updates
./myapp subscribe notification "db/changed"        # Stream named notifications

System:

./myapp serve                     # Start MCP server (stdio transport)
./myapp daemon start              # Start as background daemon
./myapp daemon stop               # Stop the daemon
./myapp daemon status             # Show daemon status
./myapp daemon logs               # Tail daemon logs
./myapp doctor                    # Check runtime dependencies
./myapp install                   # Install shell completions
./myapp uninstall                 # Remove shell completions

Global option: --output <text|json> controls the output format for all commands (default set by cli.outputDefault in config).

Tool name conflict resolution: if a tool name collides with a built-in command (e.g., login, serve), the tool subcommand is automatically suffixed with -tool (e.g., login-tool).

Auth token injection: when cli.authRequired is true in config, an active OAuth token is automatically injected into tool/resource/prompt calls.

`frontmcp.config.js` — CLI Options

The cli block in your config controls CLI generation:

// frontmcp.config.js
module.exports = {
  name: 'myapp',
  version: '1.0.0',
  cli: {
    enabled: true,
    outputDefault: 'text', // 'text' | 'json'
    authRequired: false, // inject OAuth tokens into calls
    description: 'My MCP CLI',
    excludeTools: [], // tool names to hide from CLI
    nativeDeps: {
      // checked by `doctor` command
      brew: [],
      apt: [],
      npm: [],
    },
    oauth: {
      serverUrl: 'https://auth.example.com',
      clientId: 'my-app',
      defaultScope: 'read write',
      portRange: [17830, 17850], // local callback port range
      timeout: 120000, // login timeout (ms)
    },
  },
};

Process Management

frontmcp start my-app --entry ./src/main.ts --port 3005
frontmcp status                     # Table of all processes
frontmcp status my-app              # Detail for one process
frontmcp logs my-app --follow       # Tail logs
frontmcp restart my-app
frontmcp stop my-app
frontmcp stop my-app --force        # SIGKILL
frontmcp service install my-app     # Install systemd/launchd service
frontmcp service uninstall my-app

Package Management

frontmcp install @company/my-mcp --registry https://npm.company.com
frontmcp install ./my-local-app     # Install from local path
frontmcp install github:user/repo   # Install from git
frontmcp configure my-app           # Re-run setup questionnaire
frontmcp uninstall my-app

Unix Socket

frontmcp socket ./src/main.ts --socket /tmp/my-app.sock
frontmcp socket ./src/main.ts --background --db ./data.db

Docs

Topic	Link
Installation & setup	Installation
CLI reference	CLI Reference
Local development	Local Dev Server
Production builds	Production Build

Related Packages

@frontmcp/sdk — core framework
@frontmcp/testing — E2E testing (used by frontmcp test)
@frontmcp/uipack — UI template rendering
@frontmcp/adapters — framework adapters (Express, Fastify, etc.)

Contributing

Architecture

libs/cli/src/
├── core/               # CLI entry, program factory, args, help, bridge
│   ├── cli.ts          # Entry point (bin)
│   ├── program.ts      # Commander program factory
│   ├── bridge.ts       # Commander options → ParsedArgs adapter
│   ├── args.ts         # ParsedArgs type definitions
│   └── help.ts         # Custom grouped help formatter
├── commands/
│   ├── build/          # build, build --exec, build --exec --cli
│   │   └── exec/
│   │       ├── cli-runtime/            # Generated CLI runtime modules
│   │       │   ├── generate-cli-entry.ts   # Code-gen for Commander CLI entry
│   │       │   ├── oauth-helper.ts         # OAuth PKCE login/logout helpers
│   │       │   ├── output-formatter.ts     # Text/JSON output formatting
│   │       │   ├── credential-store.ts     # Token persistence
│   │       │   ├── session-manager.ts      # Multi-session management
│   │       │   ├── schema-extractor.ts     # MCP schema → CLI metadata
│   │       │   ├── schema-to-commander.ts  # Schema → Commander options
│   │       │   ├── cli-bundler.ts          # esbuild bundling for CLI
│   │       │   └── index.ts               # Barrel exports
│   │       ├── config.ts               # frontmcp.config.js loader
│   │       ├── manifest.ts             # Build manifest generation
│   │       └── index.ts                # Exec build orchestrator
│   ├── dev/            # dev, test, init, doctor, inspector
│   ├── pm/             # start, stop, restart, status, list, logs, service, socket
│   ├── package/        # install, uninstall, configure
│   └── scaffold/       # create
├── shared/             # env loading, fs utils, prompts
└── index.ts            # Public API exports

Each command group has a register.ts that defines commands, flags, and descriptions using the Commander API. The bridge.ts module converts Commander's parsed options into the ParsedArgs shape used by handlers.

Adding a New Command

Create the handler in the appropriate commands/<group>/ directory

Add registration in commands/<group>/register.ts:

program
  .command('my-command')
  .description('What it does')
  .option('-f, --flag <value>', 'Description')
  .action(async (options) => {
    const { runMyCommand } = await import('./my-command.js');
    await runMyCommand(toParsedArgs('my-command', [], options));
  });

The bridge in core/bridge.ts maps Commander options to ParsedArgs — add any new flags there
Add the command name to the appropriate group in core/help.ts

Testing

nx test cli              # Unit tests
nx run cli:test:e2e      # E2E tests

Build

nx build cli

License

Apache-2.0 — see LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

frontmcp

Install

Commands

Development

Process Manager

Package Manager

MCP Bundles (MCPB)

Options Reference

General

Build

Start

Stop

Logs

Socket

Install

Create

Test

Examples

Project Scaffolding

Development Workflow

Executable Builds

MCP Bundles (`.mcpb`)

Generated CLI Features

`frontmcp.config.js` — CLI Options

Process Management

Package Management

Unix Socket

Docs

Related Packages

Contributing

Architecture

Adding a New Command

Testing

Build

License

FilesExpand file tree

cli

Directory actions

More options

Directory actions

More options

Latest commit

History

cli

Folders and files

parent directory

README.md

frontmcp

Install

Commands

Development

Process Manager

Package Manager

MCP Bundles (MCPB)

Options Reference

General

Build

Start

Stop

Logs

Socket

Install

Create

Test

Examples

Project Scaffolding

Development Workflow

Executable Builds

MCP Bundles (.mcpb)

Generated CLI Features

frontmcp.config.js — CLI Options

Process Management

Package Management

Unix Socket

Docs

Related Packages

Contributing

Architecture

Adding a New Command

Testing

Build

License

MCP Bundles (`.mcpb`)

`frontmcp.config.js` — CLI Options