### Clarify split-by-app auth setup and examples

Source: https://github.com/agentfront/frontmcp/blob/main/CHANGELOG.md

Documentation has been updated to clarify the setup and provide examples for split-by-app authentication in the 0.3 release.

```markdown
Clarify split-by-app auth setup and examples in the 0.3 documentation.
```

--------------------------------

### Start Development Server

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md

Navigate to the project directory and install dependencies before launching the development server.

```bash
cd my-api
yarn install
yarn dev
```

--------------------------------

### Create and run an application

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/nx-plugin/generators/app.mdx

Example of creating an app with tags and starting it in development mode.

```bash
# Create app with tags
nx g @frontmcp/nx:app analytics --tags "scope:analytics,type:app"

# Start development
nx dev analytics
```

--------------------------------

### Quick Example of @frontmcp/di

Source: https://github.com/agentfront/frontmcp/blob/main/libs/di/README.md

Demonstrates basic setup and usage of the DiContainer, including creating tokens and getting a service instance. Ensure reflect-metadata is imported.

```typescript
import 'reflect-metadata';
import { DiContainer, createTokenFactory, ProviderScope } from '@frontmcp/di';

const tokens = createTokenFactory({ prefix: 'MyApp' });

class DatabaseService {
  static metadata = { name: 'Database', scope: ProviderScope.GLOBAL };
}

const container = new DiContainer([DatabaseService]);
await container.ready;
const db = container.get(DatabaseService);
```

--------------------------------

### Install Dependencies and Run Locally

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md

Install project dependencies using npm and start the local development server for FrontMCP.

```bash
npm install
npm run dev
```

--------------------------------

### Full Example: System Status Resource and Monitoring App

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/resource.mdx

This example demonstrates a complete setup including a SystemStatusResource, a MonitoringApp, and a MonitorServer using the FrontMCP SDK.

```typescript
import { Resource, ResourceContext, App, FrontMcp } from '@frontmcp/sdk';

@Resource({
  name: 'system-status',
  uri: 'status://system',
  title: 'System Status',
  description: 'Current system health and metrics',
  mimeType: 'application/json',
})
class SystemStatusResource extends ResourceContext {
  async execute(uri: string) {
    this.mark('fetching-metrics');

    const metrics = {
      uptime: process.uptime(),
      memory: process.memoryUsage(),
      timestamp: new Date().toISOString(),
    };

    return {
      contents: [{
        uri,
        mimeType: 'application/json',
        text: JSON.stringify(metrics, null, 2),
      }],
    };
  }
}

@App({
  name: 'monitoring',
  resources: [SystemStatusResource],
})
class MonitoringApp {}

@FrontMcp({
  info: { name: 'Monitor', version: '1.0.0' },
  apps: [MonitoringApp],
})
export default class MonitorServer {}
```

--------------------------------

### Development Server Setup with FrontMcpInstance

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/core/frontmcp-instance.mdx

Example of setting up a development server using `FrontMcpInstance.bootstrap`.

```typescript
// src/index.ts
import { FrontMcpInstance } from '@frontmcp/sdk';
import config from './server';

async function main() {
  await FrontMcpInstance.bootstrap(config);
  console.log('Server started');
}

main().catch(console.error);
```

--------------------------------

### CLI creation examples

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/installation.mdx

Various ways to invoke the creation command with flags for non-interactive setup.

```bash
# Interactive mode (default)
npx frontmcp create my-app

# Non-interactive with defaults
npx frontmcp create my-app --yes

# Vercel target with CI/CD
npx frontmcp create my-app --target vercel

# Use pnpm as package manager
npx frontmcp create my-app --pm pnpm --yes

# Docker without Redis
npx frontmcp create my-app --target node --redis none --no-cicd
```

--------------------------------

### Configure Nx project.json

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/setup-project.md

Example configuration for manual Nx project setup.

```json
{
  "name": "<projectName>",
  "root": "apps/<projectName>",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "outputPath": "dist/apps/<projectName>",
        "main": "apps/<projectName>/src/main.ts",
        "tsConfig": "apps/<projectName>/tsconfig.json"
      }
    },
    "serve": {
      "executor": "@nx/js:node",
      "options": { "buildTarget": "<projectName>:build" }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": { "jestConfig": "apps/<projectName>/jest.config.ts" }
    }
  }
}
```

--------------------------------

### Quick Example: FrontMcp Server Setup

Source: https://github.com/agentfront/frontmcp/blob/main/libs/auth/README.md

Demonstrates setting up a FrontMCP server with remote OAuth authentication. Ensure your IdP details are correctly configured.

```typescript
import { FrontMcp, App } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'Secure Server', version: '1.0.0' },
  apps: [MyApp],
  auth: {
    type: 'remote',
    name: 'my-idp',
    baseUrl: 'https://idp.example.com',
  },
})
export default class Server {}
```

--------------------------------

### Quick Example: Basic FrontMCP Server Setup

Source: https://github.com/agentfront/frontmcp/blob/main/libs/sdk/README.md

A minimal FrontMCP server setup demonstrating the use of `@Tool`, `@App`, and `@FrontMcp` decorators to define a greeting tool, an application, and the main server configuration. Ensure `reflect-metadata` is imported.

```typescript
import 'reflect-metadata';
import { FrontMcp, App, Tool } from '@frontmcp/sdk';
import { z } from 'zod';

@Tool({ name: 'greet', inputSchema: { name: z.string() } })
class GreetTool {
  async execute({ name }: { name: string }) {
    return `Hello, ${name}!`;
  }
}

@App({ id: 'hello', name: 'Hello', tools: [GreetTool] })
class HelloApp {}

@FrontMcp({ info: { name: 'Demo', version: '0.1.0' }, apps: [HelloApp], http: { port: 3000 } })
export default class Server {}

```

--------------------------------

### Skill Directory Structure

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md

Example of the file structure created after installing skills.

```text
my-project/
  .claude/
    skills/
      frontmcp-setup/
        SKILL.md
        references/
      frontmcp-development/
        SKILL.md
        references/
      frontmcp-config/
        SKILL.md
        references/
```

--------------------------------

### Full Example: Approval Plugin System

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/plugin.mdx

This example demonstrates a complete plugin system for tool approval. It includes services, tools, context extensions, and application setup using FrontMcp decorators.

```typescript
import { Plugin, Provider, Token, Tool, ToolContext, App, FrontMcp } from '@frontmcp/sdk';
import { z } from 'zod';

// Tokens
export const ApprovalServiceToken = new Token<ApprovalService>('ApprovalService');
export const ApprovalAccessorToken = new Token<ApprovalAccessor>('ApprovalAccessor');

// Services
@Provider()
class ApprovalService {
  private approvals = new Map<string, boolean>();

  approve(toolName: string) {
    this.approvals.set(toolName, true);
  }

  isApproved(toolName: string): boolean {
    return this.approvals.get(toolName) === true;
  }

  revoke(toolName: string) {
    this.approvals.delete(toolName);
  }
}

@Provider()
class ApprovalAccessor {
  constructor(private service: ApprovalService) {}

  async isApproved(toolName: string): Promise<boolean> {
    return this.service.isApproved(toolName);
  }

  async approve(toolName: string): Promise<void> {
    this.service.approve(toolName);
  }
}

// Module augmentation
declare module '@frontmcp/sdk' {
  interface ExecutionContextBase {
    readonly approval: ApprovalAccessor;
  }
}

// Plugin tool
@Tool({
  name: 'approve_tool',
  description: 'Approve a tool for execution',
  inputSchema: { toolName: z.string() },
})
class ApproveToolTool extends ToolContext {
  async execute(input: { toolName: string }) {
    const accessor = this.get(ApprovalAccessorToken);
    await accessor.approve(input.toolName);
    return { approved: input.toolName };
  }
}

// Plugin definition
@Plugin({
  name: 'approval',
  description: 'Tool approval system',
  providers: [
    { provide: ApprovalServiceToken, useClass: ApprovalService },
    { provide: ApprovalAccessorToken, useClass: ApprovalAccessor },
  ],
  tools: [ApproveToolTool],
  contextExtensions: [
    {
      property: 'approval',
      token: ApprovalAccessorToken,
      errorMessage: 'Approval plugin not installed',
    },
  ],
})
export class ApprovalPlugin {}

// Using the plugin
@Tool({
  name: 'dangerous_operation',
  inputSchema: { data: z.string() },
})
class DangerousOperationTool extends ToolContext {
  async execute(input: { data: string }) {
    // Check approval via context extension
    const isApproved = await this.approval.isApproved('dangerous_operation');

    if (!isApproved) {
      return { error: 'This tool requires approval. Please run approve_tool first.' };
    }

    // Proceed with operation
    return { result: 'Operation completed' };
  }
}

@App({
  name: 'secure-app',
  plugins: [ApprovalPlugin],
  tools: [DangerousOperationTool],
})
class SecureApp {}

@FrontMcp({
  info: { name: 'Secure Server', version: '1.0.0' },
  apps: [SecureApp],
})
export default class SecureServer {}
```

--------------------------------

### Complete Example: Project Onboarding Skill

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-development/references/create-skill.md

An example of a class-based, instruction-only skill named 'project-onboarding'. It provides step-by-step guidance for onboarding new developers, covering environment setup, architecture, testing, and development workflow.

```typescript
import { Skill, SkillContext, FrontMcp, App, skill, skillDir } from '@frontmcp/sdk';

// Class-based instruction-only skill
@Skill({
  name: 'project-onboarding',
  description: 'Step-by-step guide for onboarding new developers to the project',
  instructions: `# Project Onboarding

## Step 1: Environment Setup
1. Clone the repository
2. Install Node.js 24+ and Yarn
3. Run `yarn install` to install dependencies
4. Copy `.env.example` to `.env` and fill in values

## Step 2: Understand the Architecture
- This is an Nx monorepo with libraries in `/libs/*`
- Each library is independently publishable under `@frontmcp/*`
- The SDK is the core package; other packages build on it

## Step 3: Run Tests
- Run `nx run-many -t test` to verify everything works
- Coverage must be 95%+ across all metrics
- All test files use `.spec.ts` extension

## Step 4: Development Workflow
- Create a feature branch from `main`
- Follow conventional commit format
- Run `node scripts/fix-unused-imports.mjs` before committing
- Ensure all tests pass and no TypeScript warnings exist

`,
})
class ProjectOnboardingSkill {
  // Skill implementation would go here if it had logic beyond instructions
}

```

--------------------------------

### Build and Start FrontMCP with PM2

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md

Commands to build the application, install PM2, and start the server in cluster mode with auto-restart enabled.

```bash
# Build the server
frontmcp build --target node

# Install PM2 globally
npm install -g pm2

# Start with cluster mode (one instance per CPU core)
pm2 start dist/main.js --name frontmcp-server -i max

# Save the process list for auto-restart on reboot
pm2 save
pm2 startup
```

--------------------------------

### Verify Elicitation Setup

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-config/references/configure-elicitation.md

Command to start the development server with elicitation enabled for testing.

```bash
# Enable elicitation and start
frontmcp dev

# Test with an MCP client that supports elicitation
# The tool should pause and request user input
```

--------------------------------

### Example File Metadata

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/README.md

YAML frontmatter required for standalone example files within the examples directory.

```yaml
---
name: example-name
reference: parent-reference-name
level: basic
description: One sentence describing the exact scenario this example covers.
tags: [keyword1, keyword2, keyword3]
features:
  - Concrete API or pattern this example demonstrates
  - Another concrete behavior shown in the code
---
```

--------------------------------

### Complete FrontMcp Application Setup with RememberPlugin

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/plugins/remember-plugin.mdx

This example demonstrates a full FrontMcp application setup, including configuring the `RememberPlugin` with Redis, defining a tool that uses memory (`SetPreferencesTool`), and registering them within the `App` and `FrontMcp` decorators.

```typescript
import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
import { RememberPlugin } from '@frontmcp/plugin-remember';
import { z } from 'zod';

// Configure with Redis
const rememberPlugin = RememberPlugin.init({
  type: 'redis',
  defaultTTL: 86400, // 1 day
  encryption: { enabled: true },
  config: {
    host: process.env.REDIS_HOST || 'localhost',
    port: parseInt(process.env.REDIS_PORT || '6379'),
    password: process.env.REDIS_PASSWORD,
  },
});

// Tool using memory
@Tool({
  name: 'set-preferences',
  description: 'Set user preferences',
  inputSchema: {
    theme: z.enum(['light', 'dark']),
    language: z.string(),
  },
})
class SetPreferencesTool extends ToolContext {
  async execute(input: { theme: string; language: string }) {
    await this.remember.set('theme', input.theme, { scope: 'user' });
    await this.remember.set('language', input.language, { scope: 'user' });

    return { success: true, message: 'Preferences saved' };
  }
}

@App({
  id: 'user-management',
  name: 'User Management',
  plugins: [rememberPlugin],
  tools: [SetPreferencesTool],
})
class UserManagementApp {}

@FrontMcp({
  info: { name: 'User Server', version: '1.0.0' },
  apps: [UserManagementApp],
  http: { port: 3000 },
})
export default class Server {}
```

--------------------------------

### Testing Tools with SDK

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/core/direct-client.mdx

Example of setting up a test environment using the SDK to list and call tools. Includes setup and teardown for the client connection.

```typescript
import { connect } from '@frontmcp/sdk';
import config from './server';

describe('Tools', () => {
  let client: DirectClient;

  beforeAll(async () => {
    client = await connect(config);
  });

  afterAll(async () => {
    await client.close();
  });

  test('list tools', async () => {
    const tools = await client.listTools();
    expect(tools.length).toBeGreaterThan(0);
  });

  test('call tool', async () => {
    const result = await client.callTool('get_user', { userId: '123' });
    expect(result.id).toBe('123');
  });
});
```

--------------------------------

### Usage Example

Source: https://github.com/agentfront/frontmcp/blob/main/libs/guard/src/partition-key/README.md

Provides a practical example of how to use `resolvePartitionKey` and `buildStorageKey` in your application.

```APIDOC
## Usage

```typescript
import { resolvePartitionKey, buildStorageKey } from '@frontmcp/guard';

const pk = resolvePartitionKey('session', { sessionId: 'sess-42' });
// 'sess-42'

const storageKey = buildStorageKey('my-tool', pk, 'rl');
// 'my-tool:sess-42:rl'
```
```

--------------------------------

### Full FrontMcp Application Example

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/provider.mdx

This example demonstrates a complete FrontMcp application setup, including configuration, notification services, request tracking, and a tool that utilizes these providers. It showcases `useClass`, `useFactory`, and scoped providers.

```typescript
import { Provider, Tool, ToolContext, App, FrontMcp, Token } from '@frontmcp/sdk';
import { z } from 'zod';

// Token for interface
export const NOTIFICATION_TOKEN = new Token<NotificationService>('NotificationService');

// Interface
interface NotificationService {
  send(to: string, message: string): Promise<void>;
}

// Provider implementations
@Provider()
class ConfigService {
  private env = process.env;

  get(key: string): string | undefined {
    return this.env[key];
  }

  require(key: string): string {
    const value = this.get(key);
    if (!value) throw new Error(`Missing config: ${key}`);
    return value;
  }
}

@Provider()
class EmailNotificationService implements NotificationService {
  constructor(private config: ConfigService) {}

  async send(to: string, message: string) {
    const apiKey = this.config.require('EMAIL_API_KEY');
    // Send email...
    console.log(`Sending email to ${to}: ${message}`);
  }
}

@Provider({ scope: 'scoped' })
class RequestTracker {
  private startTime = Date.now();
  private events: string[] = [];

  track(event: string) {
    this.events.push(`[${Date.now() - this.startTime}ms] ${event}`);
  }

  getTimeline() {
    return this.events;
  }
}

// Tool using providers
@Tool({
  name: 'send_notification',
  inputSchema: {
    recipient: z.string(),
    message: z.string(),
  },
})
class SendNotificationTool extends ToolContext {
  async execute(input) {
    const tracker = this.get(RequestTracker);
    tracker.track('Tool started');

    const notification = this.get(NOTIFICATION_TOKEN);
    await notification.send(input.recipient, input.message);

    tracker.track('Notification sent');

    return {
      success: true,
      timeline: tracker.getTimeline(),
    };
  }
}

@App({
  name: 'notifications',
  providers: [
    ConfigService,
    RequestTracker,
    { provide: NOTIFICATION_TOKEN, useClass: EmailNotificationService },
  ],
  tools: [SendNotificationTool],
})
class NotificationsApp {}

@FrontMcp({
  info: { name: 'Notification Service', version: '1.0.0' },
  apps: [NotificationsApp],
})
export default class NotificationServer {}

```

--------------------------------

### File-Based Instructions Example

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/contexts/skill-context.mdx

An example demonstrating how to load skill instructions from a file.

```APIDOC
## File-Based Instructions

```typescript
import { Skill, SkillContext } from '@frontmcp/sdk';
import { readFile } from '@frontmcp/utils';
import { resolve } from 'path';

@Skill({
  name: 'code-review',
  description: 'Code review workflow',
  instructions: { file: './skills/code-review.md' },
  tools: ['github_get_pr', 'github_comment'],
})
class CodeReviewSkill extends SkillContext {
  async loadInstructions() {
    const source = this.metadata.instructions;

    if (typeof source === 'string') {
      return source;
    }

    if ('file' in source) {
      const filePath = resolve(process.cwd(), source.file);
      return readFile(filePath, 'utf-8');
    }

    throw new Error('Unknown instruction source');
  }

  async build() {
    return {
      id: this.skillId,
      name: this.metadata.name,
      description: this.metadata.description,
      instructions: await this.loadInstructions(),
      tools: this.getToolRefs().map(ref => ({
        name: ref.name,
        purpose: ref.purpose,
        required: ref.required !== false,
      })),
      parameters: this.metadata.parameters,
      examples: this.metadata.examples,
    };
  }
}
```
```

--------------------------------

### Example File Structure

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/TEMPLATE.md

Template for creating standalone, copy-pasteable example files.

```markdown
---
name: example-name
reference: parent-reference-name
level: basic | intermediate | advanced
description: One sentence describing the exact scenario this example covers.
tags: [keyword1, keyword2, keyword3]
features:
  - Concrete API or pattern this example demonstrates
  - Another concrete behavior shown in the code
---

# Example Title

One sentence expanding slightly on the frontmatter description.

## Code

```typescript
// src/path/to/file.ts
import { ... } from '@frontmcp/sdk';
// Complete, self-contained code
```

## What This Demonstrates

- Key pattern or API shown

## Related

- See `reference-name` for the full API reference
```

--------------------------------

### Install @frontmcp/plugins

Source: https://github.com/agentfront/frontmcp/blob/main/libs/plugins/README.md

Use this command to install the meta-package. Note that this package is deprecated and individual plugins should be installed directly.

```bash
npm install @frontmcp/plugins
```

--------------------------------

### Vercel Deployment README: Instructions and Configuration

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/readme-guide.md

Markdown for the 'Vercel' deployment target, including Vercel CLI installation, build command, deployment, and environment variable setup.

```markdown
## Deploy to Vercel

npm i -g vercel
frontmcp build --target vercel
vercel deploy --prebuilt

## Configuration

See `vercel.json` for route configuration and environment variables.
Set secrets via: `vercel env add REDIS_URL`
```

--------------------------------

### Install from GitHub

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/cli-reference.mdx

Installs an MCP application directly from a GitHub repository.

```bash
frontmcp install github:user/repo
```

--------------------------------

### Install @frontmcp/react

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/react/getting-started.mdx

Install the necessary packages using npm or yarn.

```bash
npm install @frontmcp/react react react-dom
```

```bash
yarn add @frontmcp/react react react-dom
```

--------------------------------

### Install Redis Locally

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/deployment/redis-setup.mdx

Commands to install and start Redis on macOS and Ubuntu/Debian systems.

```bash
# macOS
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis
```

--------------------------------

### Define Skill Usage Examples

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/skill.mdx

Include scenario-based examples within the @Skill decorator to guide agent behavior.

```typescript
@Skill({
  name: 'data-analysis',
  description: 'Analyze data sets',
  instructions: '...',
  tools: ['query_database', 'generate_chart'],
  examples: [
    {
      scenario: 'Analyze monthly sales',
      parameters: { table: 'sales', period: 'monthly' },
      expectedOutcome: 'Sales trends chart and summary report',
    },
  ],
})
```

--------------------------------

### Install @frontmcp/uipack

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/ui/overview.mdx

Install the UI package for HTML component support.

```bash
# For HTML components only (no React)
npm install @frontmcp/uipack
```

--------------------------------

### Start Server Method

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/core/server.mdx

Starts the HTTP server on the configured port.

```typescript
start(): void
```

--------------------------------

### Recommended Workflow

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

Combine static installation for core skills with dynamic search for occasional references.

```bash
# Core skills — install statically
frontmcp skills install frontmcp-setup --provider claude
frontmcp skills install frontmcp-development --provider claude
frontmcp skills install frontmcp-config --provider claude

# Everything else — search on demand
frontmcp skills search "deploy to vercel"
frontmcp skills search "rate limiting"
frontmcp skills read frontmcp-deployment
```

--------------------------------

### Initialize API Request Example

Source: https://github.com/agentfront/frontmcp/blob/main/libs/auth/docs/REQUIREMENTS.md

Example payload for the POST /initialize API endpoint, used to start the MCP client session.

```json
{
  "providers": [],
  "allowAnonymous": true,
  "transparentAuth": false,
  "consentEnabled": true
}
```

--------------------------------

### Provide Examples for AI Guidance

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-development/references/create-skill.md

Examples demonstrate expected outcomes for specific scenarios to guide the AI's application of the skill.

```typescript
@Skill({
  name: 'error-handling-guide',
  description: 'Error handling patterns and best practices',
  instructions: '...',
  examples: [
    {
      scenario: 'Adding error handling to a new API endpoint',
      expectedOutcome:
        'Endpoint uses specific error classes with MCP error codes, validates input, and returns structured error responses',
    },
    {
      scenario: 'Refactoring try-catch blocks in existing code',
      expectedOutcome: 'Generic catches replaced with specific error types, proper error propagation chain established',
    },
  ],
})
class ErrorHandlingGuideSkill extends SkillContext {}
```

--------------------------------

### Build and serve

Source: https://github.com/agentfront/frontmcp/blob/main/libs/nx-plugin/README.md

Compile and start the development server for a project.

```bash
nx build my-server
nx serve my-server
```

--------------------------------

### Adjust quick start code

Source: https://github.com/agentfront/frontmcp/blob/main/CHANGELOG.md

This fix modifies the code provided in the quick start guide to ensure accuracy and clarity for new users.

```typescript
docs: adjust quick start code ([#8](https://github.com/agentfront/frontmcp/pull/8))
```

--------------------------------

### Spin up UI Demo Server

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/ui/getting-started.mdx

Use this command to start the UI demo server. This server provides access to various UI tools with different configurations.

```bash
pnpm nx serve demo-e2e-ui --port 3003
```

--------------------------------

### Define a Parameterized Skill with Examples

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md

Uses the @Skill decorator to define parameters, usage examples, and visibility settings for a REST API design guide skill.

```typescript
// src/skills/api-design-guide.skill.ts
import { Skill, SkillContext } from '@frontmcp/sdk';

@Skill({
  name: 'api-design-guide',
  description: 'REST API design guidelines',
  instructions: `# API Design Guide

Design APIs following these conventions.
Adapt the versioning strategy based on the api-style parameter.
Use the auth-required parameter to determine if authentication sections apply.`,
  parameters: [
    { name: 'api-style', description: 'API style to follow', type: 'string', default: 'rest' },
    { name: 'auth-required', description: 'Whether to include auth guidelines', type: 'boolean', default: true },
    { name: 'version-strategy', description: 'API versioning approach', type: 'string', default: 'url-path' },
  ],
  examples: [
    {
      scenario: 'Adding error handling to a new API endpoint',
      expectedOutcome:
        'Endpoint uses specific error classes with MCP error codes, validates input, and returns structured error responses',
    },
    {
      scenario: 'Refactoring try-catch blocks in existing code',
      expectedOutcome: 'Generic catches replaced with specific error types, proper error propagation chain established',
    },
  ],
  tags: ['api', 'design', 'standards'],
  visibility: 'both',
})
class ApiDesignGuideSkill extends SkillContext {}
```

--------------------------------

### Complete Server Configuration Example

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/authentication/local.mdx

A comprehensive example demonstrating the integration of various configuration options, including authentication, consent, token storage, refresh tokens, signing keys, and incremental authentication.

```APIDOC
## Complete Example

```typescript
import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'local',
    consent: { enabled: true },
    tokenStorage: {
      redis: {
        host: process.env.REDIS_HOST!,
        port: parseInt(process.env.REDIS_PORT || '6379'),
        password: process.env.REDIS_PASSWORD,
      },
    },
    refresh: {
      enabled: true,
      skewSeconds: 60,
    },
    local: {
      signKey: JSON.parse(process.env.JWT_SIGNING_KEY!),
    },
    incrementalAuth: {
      enabled: true,
      allowSkip: true,
      skippedAppBehavior: 'require-auth',
    },
  },
})
export class Server {}
```
```

--------------------------------

### Install and Initialize frontmcp

Source: https://github.com/agentfront/frontmcp/blob/main/libs/cli/README.md

Install the CLI globally or execute it directly via npx to scaffold a new project.

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

--------------------------------

### Full Tool and Server Implementation

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/tool.mdx

A complete example showing tool definition, context implementation, app registration, and server export.

```typescript
import { Tool, ToolContext, App, FrontMcp } from '@frontmcp/sdk';
import { z } from 'zod';

const inputSchema = {
  operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
  a: z.number(),
  b: z.number(),
};

const outputSchema = z.object({
  result: z.number(),
  operation: z.string(),
});

@Tool({
  name: 'calculate',
  description: 'Perform arithmetic operations',
  inputSchema,
  outputSchema,
  annotations: {
    readOnlyHint: true,
    idempotentHint: true,
  },
  examples: [
    { input: { operation: 'add', a: 2, b: 3 }, output: { result: 5, operation: 'add' } },
  ],
})
class CalculateTool extends ToolContext<typeof inputSchema, typeof outputSchema> {
  async execute(input) {
    await this.notify(`Calculating ${input.operation}(${input.a}, ${input.b})`, 'debug');

    let result: number;
    switch (input.operation) {
      case 'add': result = input.a + input.b; break;
      case 'subtract': result = input.a - input.b; break;
      case 'multiply': result = input.a * input.b; break;
      case 'divide':
        if (input.b === 0) this.fail(new Error('Division by zero'));
        result = input.a / input.b;
        break;
    }

    return { result, operation: input.operation };
  }
}

@App({ name: 'calculator', tools: [CalculateTool] })
class CalculatorApp {}

@FrontMcp({
  info: { name: 'Calculator', version: '1.0.0' },
  apps: [CalculatorApp],
})
export default class CalculatorServer {}
```

--------------------------------

### Configure SQLite for a unix-socket daemon

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md

Example setup for a server running as a unix-socket daemon.

```typescript
@FrontMcp({
  info: { name: 'frontmcp-daemon', version: '0.1.0' },
  apps: [
    /* ... */
  ],
  sqlite: {
    path: '/var/lib/frontmcp/daemon.sqlite',
    walMode: true,
  },
  transport: {
    protocol: 'modern', // 'modern' preset enables streamable HTTP + strict sessions
  },
  http: {
    unixSocket: '/tmp/frontmcp.sock',
  },
})
```

--------------------------------

### Serve FrontMCP Server in Development

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md

Use 'nx serve my-server' to start the development server for 'my-server'. Alternatively, 'nx dev my-server' can be used.

```bash
nx serve my-server
```

```bash
nx dev my-server
```

--------------------------------

### Manage Process with PM2

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node.md

Installs PM2 and starts the server in cluster mode for bare-metal deployments.

```bash
# Install PM2 globally
npm install -g pm2

# Start the server with cluster mode (one instance per CPU core)
pm2 start dist/main.js --name frontmcp-server -i max
```

--------------------------------

### Define Skill Examples

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-development/references/create-skill-with-tools.md

Provide scenarios and expected outcomes to guide the AI on how to use the skill effectively.

```typescript
@Skill({
  name: 'database-migration',
  description: 'Run database migrations safely',
  instructions: '...',
  tools: ['generate_migration', 'run_migration', 'rollback_migration', 'backup_database'],
  examples: [
    {
      scenario: 'Add a new column to the users table',
      expectedOutcome: 'Migration generated, backup created, migration applied, verified',
    },
    {
      scenario: 'Rollback a failed migration',
      expectedOutcome: 'Failed migration identified, rolled back, database restored to previous state',
    },
  ],
})
class DatabaseMigrationSkill extends SkillContext {}
```

--------------------------------

### Install and manage MCP apps

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/cli-reference.mdx

The package manager commands allow you to install, uninstall, and configure MCP applications. Use `install <source>` to add apps from npm, local paths, or git repositories. `uninstall <name>` removes an app, and `configure <name>` re-runs its setup questionnaire.

```bash
install <source>
```

```bash
uninstall <name>
```

```bash
configure <name>
```

--------------------------------

### Start development server

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md

Launches the hot-reloading development server.

```bash
# Start the development server with hot reload
frontmcp dev
```

--------------------------------

### Quick Start CLI Commands

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

Basic commands for listing, reading, and installing skills for Claude Code and Codex.

```bash
# List all skills
frontmcp skills list

# List skills by category
frontmcp skills list --category development

# Show full skill content
frontmcp skills read frontmcp-development

# Install a skill for Claude Code
frontmcp skills install frontmcp-development --provider claude

# Install a skill for Codex
frontmcp skills install frontmcp-setup --provider codex
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md

Commands to clone the repository and prepare the workspace for development.

```bash
git clone https://github.com/agentfront/frontmcp.git
cd frontmcp
corepack enable
yarn install
```

--------------------------------

### Manual Project Initialization

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/setup-project.md

Manually set up a new FrontMCP project by creating a directory structure and initializing a `package.json` file. This is an alternative to using the CLI scaffolder.

```bash
mkdir -p <projectName>/src
cd <projectName>
```

--------------------------------

### Launch the FrontMCP Inspector

Source: https://github.com/agentfront/frontmcp/blob/main/CHANGELOG.md

Starts the Inspector tool for debugging and inspecting FrontMCP components without requiring any setup.

```bash
frontmcp inspector
```

--------------------------------

### Add to existing project

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/installation.mdx

Install the necessary dependencies and initialize FrontMCP in an existing project root.

```bash
npm i -D frontmcp @types/node@^24
```

```bash
pnpm add -D frontmcp @types/node@^24
```

```bash
yarn add -D frontmcp @types/node@^24
```

```bash
npx frontmcp init
```

--------------------------------

### Verify SQLite Setup

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md

Commands and logs to verify the SQLite database initialization and file creation.

```bash
frontmcp dev
```

```text
[SessionStoreFactory] Creating SQLite session store
```

```bash
ls -la ~/.frontmcp/data/sessions.sqlite
```

```bash
ls -la ~/.frontmcp/data/sessions.sqlite-wal
ls -la ~/.frontmcp/data/sessions.sqlite-shm
```

```bash
sqlite3 ~/.frontmcp/data/sessions.sqlite ".tables"
sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv_store LIMIT 5;"
```

--------------------------------

### E2E Server Test Setup and Assertions

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md

This snippet sets up an E2E test environment using TestServer and McpTestClient. It includes setup and teardown logic with `beforeAll` and `afterAll`, and demonstrates assertions for listing tools, resources, and getting prompts.

```typescript
// src/__tests__/server.e2e.spec.ts
import { McpTestClient, TestServer } from '@frontmcp/testing';
import Server from '../src/main';

describe('Server E2E', () => {
  let client: McpTestClient;
  let server: TestServer;

  beforeAll(async () => {
    server = await TestServer.create(Server);
    client = await server.connect();
  });

  afterAll(async () => {
    await client.close();
    await server.dispose();
  });

  it('should list all tools', async () => {
    const { tools } = await client.listTools();
    expect(tools.length).toBeGreaterThan(0);
    expect(tools).toContainTool('add_numbers');
  });

  it('should list resources', async () => {
    const { resources } = await client.listResources();
    expect(resources.length).toBeGreaterThanOrEqual(0);
  });

  it('should list prompts', async () => {
    const result = await client.getPrompt('summarize', { topic: 'testing' });
    expect(result.messages).toBeDefined();
    expect(result.messages.length).toBeGreaterThan(0);
  });
});

```

--------------------------------

### Router Integration Setup

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/react/router.mdx

Steps to install React Router, wire the bridge, and register router entries with the MCP server.

```APIDOC
## Router Integration Setup

### Description
This section details the setup process for integrating React Router with MCP, including installation, wiring the bridge component, and registering router-specific tools and resources with the MCP server.

### Installation

Install `react-router-dom` as a peer dependency:

```bash
npm install react-router-dom
```

### Wiring the Bridge

Call `useRouterBridge()` within your React Router tree. This component should be placed within your `FrontMcpProvider`.

```tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { FrontMcpProvider } from '@frontmcp/react';
import { useRouterBridge } from '@frontmcp/react/router';

function RouterBridge() {
  useRouterBridge();
  return null;
}

function App() {
  return (
    <BrowserRouter>
      <FrontMcpProvider server={server}>
        <RouterBridge />
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </FrontMcpProvider>
    </BrowserRouter>
  );
}
```

### Registering Router Entries

Use `createRouterEntries()` to obtain router tools and resources, then spread them into your MCP server configuration.

```ts
import { create } from '@frontmcp/sdk';
import { createRouterEntries } from '@frontmcp/react/router';

const { tools, resources } = createRouterEntries();

const server = await create({
  info: { name: 'my-app', version: '1.0.0' },
  tools: [...tools, ...myOtherTools],
  resources: [...resources, ...myOtherResources],
});
```
```

--------------------------------

### Create a new FrontMCP project

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/quickstart.mdx

Initialize a new project using the interactive CLI. Use the --yes flag to skip prompts and use default settings.

```npm
npx frontmcp create my-mcp-server
cd my-mcp-server
npm run dev
```

```pnpm
pnpm dlx frontmcp create my-mcp-server
cd my-mcp-server
pnpm dev
```

```yarn
npx frontmcp create my-mcp-server
cd my-mcp-server
yarn dev
```

--------------------------------

### Installing LLM Provider SDKs

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/servers/agents.mdx

Install the necessary SDKs before using the shorthand provider configuration.

```bash
# For OpenAI
npm install openai

# For Anthropic
npm install @anthropic-ai/sdk
```

--------------------------------

### Debugging Guide

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/plugins/codecall/api-reference.mdx

Provides strategies and examples for debugging AgentScript code, including using `console.log` and interpreting error messages.

```APIDOC
## Debugging Guide

### Using console.log

```ts
// Enable in config
CodeCallPlugin.init({
  vm: { allowConsole: true }
});

// In script
const users = await callTool('users:list', { limit: 10 });
console.log('Fetched users:', users.length);

for (const user of users) {
  console.log('Processing:', user.id, user.email);
}

// Logs appear in response.logs array
```

### Interpreting Error Messages

<AccordionGroup>
  <Accordion title="Maximum iteration limit exceeded">
    **Cause:** Loop ran more than `maxIterations` times
    **Fix:** Use pagination or filter data before looping

    ```ts
    // Bad: looping over potentially large dataset
    for (const item of items) { ... }

    // Good: paginate or limit
    const page = items.slice(0, 100);
    for (const item of page) { ... }
    ```

  </Accordion>

  <Accordion title="Maximum tool call limit exceeded">
    **Cause:** Script called more than `maxToolCalls` tools
    **Fix:** Batch operations or use `__safe_parallel`

    ```ts
    // Bad: one tool call per item
    for (const id of ids) {
      await callTool('users:get', { id });
    }

    // Good: batch fetch
    const users = await callTool('users:getBatch', { ids });
    ```

  </Accordion>

  <Accordion title="Script execution timed out">
    **Cause:** Script ran longer than `timeoutMs`
    **Fix:** Optimize, use less data, or increase timeout

    ```ts
    // Check preset timeout
    // locked_down: 2s, secure: 3.5s, balanced: 5s
    CodeCallPlugin.init({
      vm: { preset: 'balanced', timeoutMs: 8000 }
    });
    ```

  </Accordion>

  <Accordion title="Identifier 'X' is not allowed">
    **Cause:** Used a blocked identifier (eval, require, etc.)
    **Fix:** Use allowed alternatives

    ```ts
    // Blocked
    eval('code');
    require('module');
    setTimeout(fn, 100);

    // Allowed
    // Use callTool for external operations
    await callTool('code:run', { script: 'code' });
    ```

  </Accordion>
</AccordionGroup>

### Development Mode

For easier debugging during development:

```ts
CodeCallPlugin.init({
  vm: {
    preset: 'experimental',  // Longer timeouts, more iterations
    allowConsole: true,
  },
});
```
```

--------------------------------

### Platform Examples

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/react/ai-integration.mdx

Examples demonstrating how to integrate FrontMCP tools with specific AI platforms.

```APIDOC
## Platform Examples

### OpenAI Example
```tsx
import { useTools } from '@frontmcp/react/ai';
import OpenAI from 'openai';

function OpenAIChat() {
  const { tools, processToolCalls } = useTools('openai');
  // ⚠️ dangerouslyAllowBrowser exposes your API key in client-side code.
  // In production, proxy requests through your backend instead.
  const openai = new OpenAI({ apiKey: '...', dangerouslyAllowBrowser: true });

  async function chat(message: string) {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: message }],
      tools: tools ?? undefined,
    });

    const toolCalls = response.choices[0].message.tool_calls;
    if (toolCalls) {
      const results = await processToolCalls(toolCalls);
      // Continue the conversation with tool results...
    }
  }
}
```

### Vercel AI SDK Example
```tsx
import { useTools } from '@frontmcp/react/ai';
import { useChat } from 'ai/react';

function VercelAIChat() {
  const { tools, processToolCalls } = useTools('vercel-ai');

  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat',
    // Pass tools to the chat configuration
  });
}
```

### Claude (Anthropic) Example
```tsx
import { useTools } from '@frontmcp/react/ai';

function ClaudeChat() {
  const { tools, processToolCalls } = useTools('claude');

  // `tools` is formatted as Claude tool_use blocks
  // Each tool has: { name, description, input_schema }
}
```
```

--------------------------------

### Start MCP Inspector

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/cli-reference.mdx

Launch the MCP Inspector tool to aid in debugging and inspecting your MCP server. This command requires the `@modelcontextprotocol/inspector` package to be installed.

```bash
inspector
```

--------------------------------

### FrontMcpInstance.bootstrap

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/sdk-reference/decorators/frontmcp.mdx

Method to manually bootstrap and start the MCP server instance.

```APIDOC
## FrontMcpInstance.bootstrap

### Description
Starts the HTTP server using the provided configuration.

### Parameters
- **config** (Object) - Required - The server configuration object defined by @FrontMcp

### Request Example
import { FrontMcpInstance } from '@frontmcp/sdk';
import config from './server';

await FrontMcpInstance.bootstrap(config);
```

--------------------------------

### FrontMcp Complete Configuration Example

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/authentication/cimd.mdx

Use this complete example to configure all available options for FrontMcp, including detailed CIMD, security, cache, and network settings. Ensure all paths and domains are correctly specified for your environment.

```typescript
import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
name: 'my-mcp-server',
auth: {
mode: 'local',
cimd: {
// Enable/disable CIMD support
enabled: true,

      // Cache settings
      cache: {
        defaultTtlMs: 3600_000,   // 1 hour default
        maxTtlMs: 86400_000,      // 24 hours max
        minTtlMs: 60_000,         // 1 minute min
      },

      // Security settings
      security: {
        blockPrivateIPs: true,
        allowedDomains: ['trusted.com'],
        blockedDomains: ['blocked.com'],
        warnOnLocalhostRedirects: true,
      },

      // Network settings
      network: {
        timeoutMs: 5000,
        maxResponseSizeBytes: 65536,
      },
    }

}
})
class MyServer {}

```

--------------------------------

### Verification Commands

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-config/references/configure-http.md

Example bash commands to verify HTTP configuration. These include starting the server with a custom port and testing CORS or Unix socket connections.

```bash
# Start with custom port
PORT=8080 frontmcp dev

# Test CORS
curl -v -H "Origin: https://myapp.com" http://localhost:8080/ 

# Test unix socket
curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
```

--------------------------------

### Install as System Service

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/getting-started/cli-reference.mdx

Installs a server process as a system service for automatic startup and management.

```bash
frontmcp service install my-app
```

--------------------------------

### Initialize a new Nx workspace with FrontMCP

Source: https://github.com/agentfront/frontmcp/blob/main/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md

Creates a complete Nx workspace with the plugin pre-installed and sample configuration.

```bash
npx frontmcp create my-project --nx
```

--------------------------------

### Generate Server with Deployment Target and Redis

Source: https://github.com/agentfront/frontmcp/blob/main/docs/frontmcp/nx-plugin/generators/server.mdx

Example of generating a Node.js server with Docker Redis integration. Specify the deployment target and Redis setup options.

```bash
nx g @frontmcp/nx:server production --apps crm,analytics --deploymentTarget node --redis docker
```