> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Dev Server

Run your FrontMCP server locally with hot-reload and verify it with the **FrontMCP Inspector** (zero setup).

## Prerequisites

* **Node.js**:
  * **Minimum**: Version 22 (LTS Maintenance)
  * **Recommended**: Version 24 (Active LTS)
  * *FrontMCP is developed and tested on Node.js 24*
* **npm ≥ 10** (pnpm/yarn also supported)

***

## Quick start

### Option A — New project

Creates a folder and scaffolds everything for you.

<CodeGroup>
  ```bash universal theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
  npx frontmcp create my-app
  ```
</CodeGroup>

<Info>
  The `create` command is interactive by default. Use `--yes` for non-interactive mode with defaults (Docker target, Redis via Docker Compose, GitHub Actions enabled).
</Info>

### Option B — Existing project

Install and initialize in your current repo:

<CodeGroup>`bash universal npm i -D frontmcp @types/node@^24 npx frontmcp init `</CodeGroup>

`init` adds the required scripts and updates **tsconfig.json** automatically.

***

## Package scripts

After `create` or `init`, your `package.json` will include:

```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "scripts": {
    "dev": "frontmcp dev",
    "build": "frontmcp build",
    "inspect": "frontmcp inspector",
    "doctor": "frontmcp doctor"
  }
}
```

* `frontmcp dev` — run in watch mode with type-checks
* `frontmcp build` — compile to `./dist` (override with `--out-dir`)
* `frontmcp inspector` — launches **@modelcontextprotocol/inspector** with zero setup
* `frontmcp doctor` — verifies Node/npm versions and project configuration

### Docker scripts (Docker target only)

If you created your project with the Docker target (`--target node`), you'll also have:

```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "scripts": {
    "docker:up": "docker compose -f ci/docker-compose.yml up",
    "docker:down": "docker compose -f ci/docker-compose.yml down",
    "docker:build": "docker compose -f ci/docker-compose.yml build"
  }
}
```

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Start the full stack (app + Redis if configured)
npm run docker:up

# Stop containers
npm run docker:down

# Rebuild the Docker image
npm run docker:build
```

***

## Recommended tsconfig

`init` writes this for you, but if you prefer to manage it manually:

```json title="tsconfig.json" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "compilerOptions": {
    "target": "es2021",
    "module": "esnext",
    "lib": ["es2021"],
    "moduleResolution": "bundler",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.test.ts", "**/__tests__/**"]
}
```

***

## Minimal app

> You can import from `@frontmcp/sdk` directly; no extra install needed.

**src/main.ts**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import 'reflect-metadata';
import { FrontMcp, Log Level } from '@frontmcp/sdk';
import HelloApp from './hello.app';

@FrontMcp({
  info: { name: 'Hello MCP', version: '0.1.0' },
  apps: [HelloApp],
  http: { port: Number(process.env.PORT) || 3000 },
  logging: { level: LogLevel.Info },
})
export default class Server {}
```

**src/hello.app.ts**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { App } from '@frontmcp/sdk';
import Greet from './tools/greet.tool';

@App({ id: 'hello', name: 'Hello', tools: [Greet] })
export default class HelloApp {}
```

**src/tools/greet.tool.ts**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { tool } from '@frontmcp/sdk';
import { z } from 'zod';

export default tool({
  name: 'greet',
  description: 'Greets a user by name',
  // New style: pass Zod fields directly (no z.object wrapper)
  inputSchema: { name: z.string() },
})(({ name }) => `Hello, ${name}!`);
```

***

## Run the dev server

<CodeGroup>`bash universal npm run dev `</CodeGroup>

Your server will start (default `http://localhost:3000`). The console will print the MCP endpoint.

***

## Inspect locally (zero setup)

Launch the **FrontMCP Inspector** to exercise tools and messages in a friendly UI:

<CodeGroup>`bash universal npm run inspect `</CodeGroup>

* This runs `npx @modelcontextprotocol/inspector` behind the scenes.
* Point it at your local server URL printed by `dev` (e.g., `http://localhost:3000`).
* Try calling `greet` and watch responses stream back in real time.

***

## Troubleshooting

* **Check configuration**

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
npm run doctor
```

Ensures Node/npm versions, entry detection, and `tsconfig.json` are correct.

* **Entry detection**
  The CLI looks for `package.json.main`; if missing, it falls back to `src/main.ts`. If no entry is found, it will tell you how to create one.

* **Type errors in dev**
  The `dev` command performs async type-checks while watching your files, so you’ll see issues immediately without stopping the server.