Nuxt MCP Toolkit

https://mcp-toolkit.nuxt.dev
Admin
The Nuxt MCP Toolkit enables Nuxt applications to expose their features and data to AI clients using...
Tokens:54,896
Snippets:653
Trust Score:7.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Define a Setup Guide Prompt

Source: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced

Creates a static prompt to assist new developers with project onboarding and environment setup.

```typescript
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Provide complete setup instructions for this project',
  handler: async () => `You are setting up this Nuxt project. Here's what you need to know:

1. Install dependencies: \`pnpm install\`
2. Start dev server: \`pnpm dev\`
3. Project structure follows Nuxt conventions
4. MCP tools are available in server/mcp/

Ask me what you'd like to build!`,
})
```

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

### Include Examples in Prompts

Source: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced

Provide output format examples within the handler to ensure consistent AI responses.

```typescript
handler: async () => `Generate a commit message following this format:

type(scope): description

Example:
feat(auth): add OAuth2 login support

Types: feat, fix, docs, style, refactor, test, chore`
```

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

### Custom Badge Examples

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Examples demonstrating customization of labels, colors, and icon visibility.

```markdown
[![Add to Cursor](https://your-app.com/mcp/badge.svg?label=Add%20to%20Cursor)](https://your-app.com/mcp/deeplink)
```

```markdown
[![Install](https://your-app.com/mcp/badge.svg?color=0ea5e9&borderColor=0284c7)](https://your-app.com/mcp/deeplink)
```

```markdown
[![Install](https://your-app.com/mcp/badge.svg?icon=false)](https://your-app.com/mcp/deeplink)
```

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

### Manual Dependency Installation

Source: https://mcp-toolkit.nuxt.dev/getting-started/installation

Install the toolkit and its required peer dependency, zod, using your preferred package manager.

```bash
pnpm add @nuxtjs/mcp-toolkit zod
```

```bash
npm install @nuxtjs/mcp-toolkit zod
```

```bash
yarn add @nuxtjs/mcp-toolkit zod
```

```bash
bun add @nuxtjs/mcp-toolkit zod
```

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

### Install Evalite and AI SDK dependencies

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Install the necessary packages for running evaluations with Evalite and the AI SDK.

```bash
pnpm add -D evalite vitest @ai-sdk/mcp ai
```

```bash
npm install -D evalite vitest @ai-sdk/mcp ai
```

```bash
yarn add -D evalite vitest @ai-sdk/mcp ai
```

```bash
bun add -D evalite vitest @ai-sdk/mcp ai
```

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

### Custom Version and Redirect Example

Source: https://mcp-toolkit.nuxt.dev/handlers/default-and-custom

Example of overriding the server name, version, and browser redirect URL.

```typescript
export default defineMcpHandler({
  name: 'My Documentation MCP',
  version: '1.2.0',
  browserRedirect: '/getting-started',
})
```

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

### Automatic Module Installation

Source: https://mcp-toolkit.nuxt.dev/getting-started/installation

Use the Nuxt CLI to automatically install the module and update the configuration.

```bash
npx nuxt add mcp
```

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

### Install NuxtMCP Toolkit

Source: https://mcp-toolkit.nuxt.dev/

Command to initialize the MCP toolkit in a Nuxt project.

```bash
$ npx skills add https://mcp-toolkit.nuxt.dev
```

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

### Project Structure Example

Source: https://mcp-toolkit.nuxt.dev/getting-started/installation

The expected directory layout for a project using the Nuxt MCP toolkit.

```text
your-project/
├── server/
│   └── mcp/
│       ├── tools/
│       │   └── echo.ts          # Your tool definitions
│       ├── resources/
│       │   └── readme.ts       # Your resource definitions
│       └── prompts/
│           └── greeting.ts     # Your prompt definitions
├── nuxt.config.ts
└── package.json
```

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

### Basic README Badge Integration

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Standard implementation for a Cursor installation badge.

```markdown
[![Install in Cursor](https://your-app.com/mcp/badge.svg)](https://your-app.com/mcp/deeplink)
```

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

### Install secure-exec dependency

Source: https://mcp-toolkit.nuxt.dev/advanced/code-mode

Install the required secure-exec package using your preferred package manager.

```shell
pnpm add secure-exec
```

```shell
npm install secure-exec
```

```shell
yarn add secure-exec
```

```shell
bun add secure-exec
```

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

### Define an MCP handler with all options

Source: https://mcp-toolkit.nuxt.dev/handlers/structure-and-options

A comprehensive example showing all available configuration options for an MCP handler.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler-name',
  version: '1.0.0',              // Handler version
  description: 'Admin tools',    // serverInfo description shown by clients
  instructions: 'Always …',      // System-prompt guidance for LLMs
  icons: [ ... ],                 // Server icons shown in client UIs
  route: '/mcp/custom',          // Custom route
  browserRedirect: '/',          // Browser redirect URL
  middleware: async (event) => { ... }, // Request interception
  tools: [ ... ],                 // Array of tools
  resources: [ ... ],            // Array of resources
  prompts: [ ... ],               // Array of prompts
  experimental_codeMode: true,    // Enable code mode (experimental)
})
```

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

### Project file organization layout

Source: https://mcp-toolkit.nuxt.dev/resources/organization

Example of a supported file system layout for resources within the server directory.

```text
server/
└── mcp/
    └── resources/
        ├── readme.ts
        ├── file.ts
        └── config/
            └── app-settings.ts
```

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

### Path Resolution Examples

Source: https://mcp-toolkit.nuxt.dev/advanced/custom-paths

Demonstrates how to push relative paths from the server directory or absolute paths from the project root.

```typescript
// Relative to server/
paths.tools.push('custom/tools')

// Absolute from project root
paths.tools.push('/absolute/path/to/tools')
```

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

### Run MCP Server

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Commands to start the MCP server development environment.

```bash
pnpm dev
```

```bash
npm run dev
```

```bash
yarn dev
```

```bash
bun dev
```

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

### GET /mcp/deeplink

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Redirects the user to the IDE deeplink to initiate the installation of the MCP server.

```APIDOC
## GET /mcp/deeplink

### Description
Redirects the user to the IDE deeplink to initiate the installation of the MCP server.

### Method
GET

### Endpoint
/mcp/deeplink

### Parameters
#### Query Parameters
- **ide** (string) - Optional - Target IDE (cursor or vscode)
```

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

### Define MCP Tool with Input Examples

Source: https://mcp-toolkit.nuxt.dev/tools/annotations

Provides concrete, type-safe usage examples to help AI models understand parameter requirements.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Create a new todo',
  inputSchema: {
    title: z.string().describe('The title of the todo'),
    content: z.string().optional().describe('Optional description'),
  },
  inputExamples: [
    { title: 'Buy groceries', content: 'Milk, eggs, bread' },
    { title: 'Fix login bug' },  // content is optional
  ],
  handler: async ({ title, content }) => {
    // ...
  },
})
```

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

### ChatGPT Prompt Syntax

Source: https://mcp-toolkit.nuxt.dev/apps/testing-publishing

Example of mentioning an MCP app in a ChatGPT prompt to trigger the connector.

```text
@Weather App What is the weather in London?
```

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

### Install evlog dependency

Source: https://mcp-toolkit.nuxt.dev/advanced/logging

Install the evlog package using your preferred package manager to enable server-side wide events.

```bash
pnpm add evlog
```

```bash
npm install evlog
```

```bash
yarn add evlog
```

```bash
bun add evlog
```

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

### LLM Search Workflow

Source: https://mcp-toolkit.nuxt.dev/advanced/code-mode

Example of the LLM searching for tools by keyword before execution.

```javascript
LLM calls: search({ query: "user" })

→ Found 2/12 tools matching "user":
  codemode.get_user: (input: { id: string }) => Promise<unknown>; // Get user by ID
  codemode.list_users: () => Promise<unknown>; // List all users
```

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

### Launch Evalite UI

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Commands to start the Evalite visual interface for reviewing test results.

```bash
pnpm eval:ui
```

```bash
npm run eval:ui
```

```bash
yarn eval:ui
```

```bash
bun eval:ui
```

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

### Return different content types

Source: https://mcp-toolkit.nuxt.dev/resources/content-metadata-errors

Examples for returning text, JSON, or binary data from a resource handler.

```javascript
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'text/markdown',
    text: '# Markdown content',
  }],
}
```

```javascript
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'application/json',
    text: JSON.stringify({ key: 'value' }),
  }],
}
```

```javascript
return {
  contents: [{
    uri: uri.toString(),
    mimeType: 'image/png',
    blob: Buffer.from(binaryData),
  }],
}
```

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

### Project Directory Structure Example

Source: https://mcp-toolkit.nuxt.dev/advanced/custom-paths

A visual representation of a project layout sharing definitions across multiple Nuxt layers.

```text
project/
├── shared/
│   ├── tools/
│   │   └── common-tool.ts
│   └── resources/
│       └── common-resource.ts
└── apps/
    ├── web/
    │   └── server/
    │       └── mcp/
    │           └── tools/
    │               └── web-tool.ts
    └── api/
        └── server/
            └── mcp/
                └── tools/
                    └── api-tool.ts
```

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

### LLM Execution Workflow

Source: https://mcp-toolkit.nuxt.dev/advanced/code-mode

Example of the LLM executing code using tools discovered in the search step.

```javascript
LLM calls: code({ code: "..." })

→ Executes code using the discovered tools
```

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

### VS Code Badge Integration

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Implementation for a VS Code specific installation badge.

```markdown
[![Install in VS Code](https://your-app.com/mcp/badge.svg?ide=vscode)](https://your-app.com/mcp/deeplink?ide=vscode)
```

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

### Instrument the low-level SDK server

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Example of accessing the underlying SDK server to attach custom event listeners.

```typescript
import { getSdkServer } from '@nuxtjs/mcp-toolkit/server'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:server:created', ({ server }) => {
    const sdkServer = getSdkServer(server)
    sdkServer.oninitialized = () => {
      console.log('Client initialized')
    }
  })
})
```

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

### Define an MCP Resource

Source: https://mcp-toolkit.nuxt.dev/

Example of exposing a file as an MCP resource with metadata annotations.

```typescript
// server/mcp/resources/readme.ts
export default defineMcpResource({
  file: 'README.md',
  description: 'The project documentation',
  annotations: {
    audience: ['user', 'assistant'],
    lastModified: new Date().toISOString(),
  }
})
```

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

### Install Agent Skills via CLI

Source: https://mcp-toolkit.nuxt.dev/getting-started/agent-skills

Use the skills CLI to add the MCP toolkit skills to your project from the production URL.

```bash
npx skills add https://mcp-toolkit.nuxt.dev
```

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

### InstallButton Component

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

The InstallButton component provides a standardized way to offer one-click installation for MCP servers. It supports configuration via props for the target URL, IDE type, and display labels.

```APIDOC
## InstallButton Component

### Description
A Vue component that renders a button to install an MCP server into a supported IDE.

### Props
- **url** (string) - Required - The URL of the MCP server endpoint.
- **ide** ('cursor' | 'vscode') - Optional - The target IDE. Defaults to 'cursor'.
- **label** (string) - Optional - Custom text for the button label.
- **showIcon** (boolean) - Optional - Whether to display the IDE icon. Defaults to true.

### Usage (Vue Template)
<InstallButton url="https://my-app.com/mcp" ide="vscode" />

### Usage (MDC Syntax)
::install-button
---
url: "https://my-app.com/mcp"
ide: "vscode"
---
::
```

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

### Define an MCP Tool

Source: https://mcp-toolkit.nuxt.dev/getting-started/installation

Create a test tool using defineMcpTool to verify the installation.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'test',
  description: 'A simple test tool',
  inputSchema: {
    message: z.string(),
  },
  handler: async ({ message }) => `Test successful: ${message}`,
})
```

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

### Dual IDE Badge Integration

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Displaying both Cursor and VS Code installation badges simultaneously.

```markdown
[![Install in Cursor](https://your-app.com/mcp/badge.svg)](https://your-app.com/mcp/deeplink)
[![Install in VS Code](https://your-app.com/mcp/badge.svg?ide=vscode)](https://your-app.com/mcp/deeplink?ide=vscode)
```

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

### ngrok Forwarding Output

Source: https://mcp-toolkit.nuxt.dev/apps/testing-publishing

Example output format provided by ngrok showing the public forwarding URL.

```text
Forwarding https://your-subdomain.ngrok-free.dev -> http://localhost:3000
```

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

### Register a tool dynamically

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Example of registering a new tool on the server instance during the mcp:server:created hook.

```typescript
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:server:created', ({ server, event }) => {
    server.registerTool(
      'whoami',
      { description: 'Return the current user id' },
      async () => ({
        content: [{
          type: 'text',
          text: String(event.context.userId ?? 'anonymous'),
        }],
      }),
    )
  })
})
```

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

### Rebrand MCP server per request

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Example of dynamically updating server name and instructions based on tenant context.

```typescript
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:config:resolved', ({ config, event }) => {
    const tenant = event.context.tenant?.name
    if (tenant) {
      config.name = `${tenant} MCP`
      config.instructions = `You are connected to ${tenant}'s MCP server.`
    }
  })
})
```

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

### Define a Custom MCP Handler

Source: https://mcp-toolkit.nuxt.dev/handlers/examples-routing

A comprehensive example showing the definition of tools, resources, and prompts within a single handler file.

```typescript
import { z } from 'zod'
import { defineMcpTool, defineMcpResource, defineMcpPrompt, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const getUserTool = defineMcpTool({
  name: 'get-user',
  description: 'Get user information',
  inputSchema: {
    userId: z.string(),
  },
  handler: async ({ userId }) => {
    const user = await db.users.find(userId)
    return user
  },
})

const createUserTool = defineMcpTool({
  name: 'create-user',
  description: 'Create a new user',
  inputSchema: {
    name: z.string(),
    email: z.string().email(),
  },
  handler: async ({ name, email }) => {
    const user = await db.users.create({ name, email })
    return `User created: ${user.id}`
  },
})

// Define resources for this handler
const userResource = defineMcpResource({
  name: 'user',
  uri: 'api://users/{id}',
  handler: async (uri, variables) => {
    const id = variables.id as string
    const user = await db.users.find(id)
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: 'application/json',
        text: JSON.stringify(user),
      }],
    }
  },
})

// Define prompts for this handler
const userPrompt = defineMcpPrompt({
  name: 'user-help',
  description: 'Get help with user operations',
  handler: async () => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: 'How can I manage users?',
        },
      }],
    }
  },
})

// Export the handler
export default defineMcpHandler({
  name: 'api',
  version: '1.0.0',
  route: '/mcp/api',
  tools: [getUserTool, createUserTool],
  resources: [userResource],
  prompts: [userPrompt],
  browserRedirect: '/docs/api',
})
```

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

### Tool metadata response format

Source: https://mcp-toolkit.nuxt.dev/tools/groups-organization

Example of how groups and tags appear in the _meta field of a tools/list response.

```json
{
  "name": "delete-user",
  "_meta": {
    "group": "admin",
    "tags": ["destructive", "user-management"]
  }
}
```

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

### Define a basic MCP tool

Source: https://mcp-toolkit.nuxt.dev/tools/overview

A simple example of an echo tool using Zod for input validation and defineMcpTool for registration.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'echo',
  description: 'Echo back a message',
  inputSchema: {
    message: z.string().describe('The message to echo back'),
  },
  handler: async ({ message }) => `Echo: ${message}`,
})
```

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

### Test Tool Selection

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Example of verifying that the model selects the correct tools based on input prompts.

```typescript
evalite('Tool Selection', {
  data: async () => [
    {
      input: 'List all available documentation pages',
      expected: [{ toolName: 'list-pages' }],
    },
    {
      input: 'Show me the installation guide',
      expected: [{ toolName: 'get-page', input: { path: '/getting-started/installation' } }],
    },
  ],
  task: async (input) => {
    const mcp = await createMCPClient({ transport: { type: 'http', url: MCP_URL } })
    try {
      const result = await generateText({
        model,
        prompt: input,
        tools: await mcp.tools(),
      })
      return result.toolCalls ?? []
    }
    finally {
      await mcp.close()
    }
  },
  scorers: [({ output, expected }) => toolCallAccuracy({ actualCalls: output, expectedCalls: expected })],
})
```

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

### View Log Output in Terminal

Source: https://mcp-toolkit.nuxt.dev/advanced/logging

Example of the structured log output displayed in the development terminal during an MCP tool call.

```text
INFO [my-app/mcp] POST /mcp 200 in 18ms
├─ mcp: transport=streamable-http route=/mcp method=tools/call tool=charge_card
├─ user: id=user-42 email=alice@example.com
├─ billing: amount=1000
└─ requestLogs: 0={"level":"info","message":"charge_completed",...}
```

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

### GET /mcp/badge.svg

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Returns a customizable SVG badge image representing the MCP server installation link.

```APIDOC
## GET /mcp/badge.svg

### Description
Returns a customizable SVG badge image representing the MCP server installation link.

### Method
GET

### Endpoint
/mcp/badge.svg

### Parameters
#### Query Parameters
- **ide** (string) - Optional - Target IDE (cursor or vscode). Default: cursor
- **label** (string) - Optional - Badge text. Default: Auto-generated
- **color** (string) - Optional - Background color (hex without #). Default: 171717
- **textColor** (string) - Optional - Text color (hex without #). Default: ffffff
- **borderColor** (string) - Optional - Border color (hex without #). Default: 404040
- **icon** (boolean) - Optional - Show IDE icon (true or false). Default: true
```

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

### Document MCP registration for users

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Provide this command in your documentation or README to allow users to quickly register your production MCP server.

```bash
npx add-mcp https://your-product.com/mcp
```

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

### Registering a Tool Mid-Session

Source: https://mcp-toolkit.nuxt.dev/advanced/dynamic-definitions

Demonstrates using useMcpServer to dynamically register a new tool within an existing session.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Create a shortcut tool for a specific query',
  inputSchema: {
    name: z.string().describe('Name for the shortcut tool'),
    query: z.string().describe('The query this shortcut runs'),
  },
  handler: async ({ name, query }) => {
    const mcp = useMcpServer()
    mcp.registerTool(name, {
      description: `Shortcut: ${query}`,
    }, async () => {
      const result = await runQuery(query)
      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
    })
    return `Shortcut "${name}" created`
  },
})
```

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

### Implement InstallButton in Markdown (MDC)

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Use MDC syntax for the InstallButton component within Nuxt Content files.

```markdown
<!-- Cursor (default) -->
::install-button
---
url: "https://my-app.com/mcp"
---
::

<!-- VS Code -->
::install-button
---
url: "https://my-app.com/mcp"
ide: "vscode"
---
::

<!-- With custom label -->
::install-button
---
url: "https://my-app.com/mcp"
label: "Add to Cursor"
---
::
```

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

### Implement InstallButton in Vue Templates

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Use the component in Vue templates with optional IDE and label props.

```vue
<template>
  <!-- Cursor (default) -->
  <InstallButton url="https://my-app.com/mcp" />

  <!-- VS Code -->
  <InstallButton url="https://my-app.com/mcp" ide="vscode" />

  <!-- Custom label -->
  <InstallButton url="https://my-app.com/mcp" label="Add to Cursor" />
</template>
```

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

### Implement Conversation Flow

Source: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced

Use role-based messages to establish context and guide the interaction.

```typescript
// Effective: User provides context, assistant acknowledges
messages: [
  { role: 'user', content: { type: 'text', text: 'You are an expert in accessibility. Review this HTML for a11y issues.' } },
  { role: 'assistant', content: { type: 'text', text: 'I\'ll analyze the HTML for accessibility issues.' } },
]
```

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

### Configure environment variables

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Set the required AI provider key and MCP endpoint in a .env file.

```text
# AI provider (AI Gateway example)
AI_GATEWAY_API_KEY=your_key

# MCP endpoint exposed by your dev server
MCP_URL=http://localhost:3000/mcp
```

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

### Standard tool directory structure

Source: https://mcp-toolkit.nuxt.dev/tools/groups-organization

Recommended layout for organizing tools in the server/mcp/tools directory.

```text
server/
└── mcp/
    └── tools/
        ├── echo.ts
        ├── calculator.ts
        ├── admin/
        │   ├── delete-user.ts
        │   └── stats.ts
        └── content/
            └── list-pages.ts
```

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

### Define an MCP Tool

Source: https://mcp-toolkit.nuxt.dev/

Example of defining a tool with Zod schema validation, caching, and a handler function.

```typescript
// server/mcp/tools/weather.ts
import { z } from 'zod'

export default defineMcpTool({
  description: 'Get current weather for a location',
  inputSchema: {
    city: z.string().describe('City name'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius')
  },
  annotations: { readOnlyHint: true },
  cache: '1h',
  handler: async ({ city, unit }) => {
    const data = await fetchWeather(city)
    return { temperature: data.temp, unit, city }
  }
})
```

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

### Define a simple file resource

Source: https://mcp-toolkit.nuxt.dev/resources/static-and-structure

Expose a local file by providing the file path; the toolkit handles URI generation, MIME type detection, and reading.

```typescript
import { defineMcpResource } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpResource({
  name: 'readme',
  description: 'Project README file',
  file: 'README.md', // Relative to project root
})
```

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

### Filter tools based on authentication

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Example of hiding admin tools from anonymous clients by mutating the config.

```typescript
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('mcp:config:resolved', ({ config, event }) => {
    if (!event.context.user) {
      config.tools = config.tools.filter(
        tool => !tool.tags?.includes('admin'),
      )
    }
  })
})
```

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

### Configure handler instructions

Source: https://mcp-toolkit.nuxt.dev/handlers/structure-and-options

Provides operational guidance for AI agents via the system prompt.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'admin',
  instructions: 'Always call list-users before delete-user. Confirm with the operator before any destructive action.',
})
```

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

### LLM-generated code patterns

Source: https://mcp-toolkit.nuxt.dev/advanced/code-mode

Examples of JavaScript code generated by the LLM using the codemode object to interact with tools.

```javascript
const user = await codemode.get_user({ id: "123" });
const todos = await codemode.list_todos({ userId: user.id });

if (todos.length === 0) {
  await codemode.create_todo({
    title: "Welcome task",
    userId: user.id,
  });
}

return { user, todos };
```

```javascript
const [users, products, orders] = await Promise.all([
  codemode.list_users(),
  codemode.list_products(),
  codemode.list_orders({ status: "pending" }),
]);

return {
  userCount: users.length,
  productCount: products.length,
  pendingOrders: orders.length,
};
```

```javascript
const users = await codemode.list_users();
const results = [];

for (const user of users) {
  const todos = await codemode.list_todos({ userId: user.id });
  if (todos.some(t => t.overdue)) {
    await codemode.send_reminder({ userId: user.id });
    results.push(user.name);
  }
}

return { reminded: results };
```

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

### Define a Documentation Generation Prompt

Source: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced

Implements dynamic template selection based on the provided documentation type input.

```typescript
import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  description: 'Generate documentation in team format',
  inputSchema: {
    type: z.enum(['api', 'component', 'function']).describe('What to document'),
  },
  handler: async ({ type }) => {
    const templates = {
      api: 'Document this API endpoint with: endpoint, method, parameters, response format, and examples.',
      component: 'Document this Vue component with: props, emits, slots, and usage examples.',
      function: 'Document this function with: parameters, return value, and usage examples.',
    }

    return templates[type]
  },
})
```

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

### Hook Error Log Output

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Example of the error message format displayed in the console when a hook throws an exception.

```text
[error] [mcp-toolkit] Hook "mcp:server:created" threw — request continues
```

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

### Folder structure for multi-handler organization

Source: https://mcp-toolkit.nuxt.dev/handlers/organization

Demonstrates the directory layout where files under specific handler folders are automatically associated with that handler.

```text
server/mcp/
├── tools/                          # → default handler
├── resources/                      # → default handler
├── prompts/                        # → default handler
└── handlers/
    ├── admin/
    │   ├── index.ts                # defineMcpHandler({ middleware: requireAdmin })
    │   ├── tools/
    │   │   └── delete-user.ts      # → handler 'admin' (auto)
    │   └── prompts/
    │       └── help.ts             # → handler 'admin' (auto)
    └── widgets/
        ├── index.ts                # defineMcpHandler({})
        └── tools/
            └── carousel.ts         # → handler 'widgets' (auto)
```

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

### Create an MCP App

Source: https://mcp-toolkit.nuxt.dev/getting-started/introduction

Develop interactive UI widgets as Vue components that render inline within AI host interfaces.

```vue
<script setup lang="ts">
import { z } from 'zod'

defineMcpApp({
  description: 'Pick a colour and preview a palette.',
  inputSchema: { base: z.string().describe('Hex colour, e.g. #2563eb') },
  handler: async ({ base }) => ({ structuredContent: await $fetch('/api/palette', { query: { base } }) }),
})

const { data } = useMcpApp()
</script>

<template>
  <ul v-if="data" class="swatches">
    <li v-for="s in data.swatches" :key="s.hex" :style="{ background: s.hex }">{{ s.name }}</li>
  </ul>
</template>
```

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

### Configure Axiom Environment Variables

Source: https://mcp-toolkit.nuxt.dev/advanced/logging

Required environment variables for the Axiom adapter configuration.

```text
NUXT_AXIOM_TOKEN=xaat-...
NUXT_AXIOM_DATASET=mcp-server
```

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

### Server API Endpoint

Source: https://mcp-toolkit.nuxt.dev/apps/authoring

Example of a server-side API endpoint that utilizes shared types for type-safe data handling.

```typescript
export default defineEventHandler(async (event): Promise<PalettePayload> => {
  const { base } = getQuery(event)
  return { base: String(base), swatches: buildPalette(String(base)) }
})
```

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

### Project Structure

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Recommended directory layout for MCP projects with evaluations.

```text
your-project/
├── server/
│   └── mcp/
│       ├── tools/
│       │   └── calculate-bmi.ts
│       ├── resources/
│       └── prompts/
├── test/
│   └── mcp.eval.ts          # Your MCP eval tests
├── nuxt.config.ts
└── package.json
```

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

### Test Multi-Step Workflows

Source: https://mcp-toolkit.nuxt.dev/advanced/evals

Example of testing workflows requiring multiple tool calls by setting the maxSteps parameter.

```typescript
evalite('Multi-Step Workflows', {
  data: async () => [
    {
      input: 'Find the installation page and show me its content',
      expected: [
        { toolName: 'list-pages' },
        { toolName: 'get-page', input: { path: '/getting-started/installation' } },
      ],
    },
  ],
  task: async (input) => {
    const mcp = await createMCPClient({ transport: { type: 'http', url: MCP_URL } })
    try {
      const result = await generateText({
        model,
        prompt: input,
        tools: await mcp.tools(),
        maxSteps: 5, // Allow multiple tool calls
      })
      return result.toolCalls ?? []
    }
    finally {
      await mcp.close()
    }
  },
  scorers: [({ output, expected }) => toolCallAccuracy({ actualCalls: output, expectedCalls: expected })],
})
```

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

### Customize Inspector Ports

Source: https://mcp-toolkit.nuxt.dev/getting-started/inspector

Override default inspector ports by setting environment variables before starting the development server.

```bash
CLIENT_PORT=8080 SERVER_PORT=9000 pnpm dev
```

```bash
CLIENT_PORT=8080 SERVER_PORT=9000 npm run dev
```

```bash
CLIENT_PORT=8080 SERVER_PORT=9000 yarn dev
```

```bash
CLIENT_PORT=8080 SERVER_PORT=9000 bun dev
```

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

### useMcpSession()

Source: https://mcp-toolkit.nuxt.dev/advanced/sessions

The useMcpSession() server utility provides a typed, per-session key-value store. It is auto-imported and supports both typed and untyped session data.

```APIDOC
## useMcpSession()

### Description
Provides a per-session key-value store for server-side tools. Methods are asynchronous and return a Promise.

### Methods
- **get(key)**: Retrieve a value by key (returns null if missing).
- **set(key, value)**: Store a value for the given key.
- **remove(key)**: Delete a key from the session.
- **has(key)**: Check if a key exists.
- **keys()**: List all keys in the session.
- **clear()**: Remove all data from the session.
- **storage**: Access the underlying unstorage instance.

### Usage Example
```typescript
const session = useMcpSession<CounterSession>()
const count = await session.get('counter') ?? 0
await session.set('counter', count + 1)
```
```

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

### Manual MCP server configuration

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Provide this JSON structure for users to manually configure their IDEs, replacing the URL with your live production endpoint.

```json
{
  "url": "https://your-product.com/mcp"
}
```

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

### Register MCP server with add-mcp CLI

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Use the add-mcp command to register your MCP server with coding agents. Choose the local development URL or the production URL based on your environment.

```bash
npx add-mcp http://localhost:3000/mcp
```

```bash
npx add-mcp https://your-app.example.com/mcp
```

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

### Implement Request Logging Middleware

Source: https://mcp-toolkit.nuxt.dev/advanced/middleware

Logs request start and end events with a unique request ID and duration tracking.

```typescript
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  middleware: async (event, next) => {
    const requestId = crypto.randomUUID()
    const startTime = Date.now()

    event.context.requestId = requestId

    console.log(JSON.stringify({
      type: 'mcp_request_start',
      requestId,
      path: event.path,
      method: event.method,
      timestamp: new Date().toISOString(),
    }))

    const response = await next()

    console.log(JSON.stringify({
      type: 'mcp_request_end',
      requestId,
      duration: Date.now() - startTime,
      timestamp: new Date().toISOString(),
    }))

    return response
  },
})
```

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

### MCP App Project Layout

Source: https://mcp-toolkit.nuxt.dev/advanced/mcp-apps-internals

Standard directory structure for sharing logic between UI components and server endpoints.

```text
app/mcp/color-picker.vue          # UI + handler that calls $fetch('/api/palette')
server/api/palette.get.ts         # The actual data endpoint (callable by humans + tools)
server/utils/palette.ts           # Shared generators / helpers
shared/types/palette.ts           # Types auto-imported by both the SFC and the endpoint
```

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

### mcp:server:created

Source: https://mcp-toolkit.nuxt.dev/advanced/hooks

Fired after the McpServer instance is created and definitions are registered, but before transport connection. Use this to register definitions late or access the low-level SDK server.

```APIDOC
## mcp:server:created

### Description
Fired after `createMcpServer` has registered every tool / resource / prompt and before the server is connected to the transport. Receives the SDK `McpServer` instance.

### Hook Signature
```typescript
nitroApp.hooks.hook('mcp:server:created', (ctx: {
  server: McpServer
  event: H3Event
}) => {
  // Reach into the SDK
})
```
```

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

### Override InstallButton CSS Styles

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Apply custom styles by overriding the .mcp-install-button CSS class.

```css
/* Override default styles */
.mcp-install-button {
  background-color: #your-brand-color;
  border-radius: 9999px;
}
```

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

### Initialize useMcpApp()

Source: https://mcp-toolkit.nuxt.dev/apps/use-mcp-app

The primary composable for accessing host communication methods and reactive state within an MCP App.

```typescript
const {
  initialData,  // Ref<T | null>          — snapshot of the handler payload at mount, never updated
  data,         // Ref<T | null>          — hydrated from structuredContent, refreshed by callTool
  loading,      // Ref<boolean>           — true until first payload arrives
  error,        // Ref<Error | null>      — bridge / transport / payload errors
  pending,      // Ref<boolean>           — true while a callTool() is in flight
  hostContext,  // Ref<HostContext | null> — theme, displayMode, locale, …
  callTool,     // (name, params?) => Promise<T | null> — re-invoke any MCP tool
  sendPrompt,   // (prompt: string) => void              — push a message into the chat
  openLink,     // (url: string) => void                 — ask the host to open a URL
} = useMcpApp<MyPayload>()
```

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

### MCP Handler File Structure

Source: https://mcp-toolkit.nuxt.dev/handlers/examples-routing

Recommended directory layout for organizing multiple MCP handlers and default resources.

```text
server/
└── mcp/
    ├── migration.ts          # Migration handler
    ├── api-handler.ts        # API handler
    ├── admin-handler.ts      # Admin handler
    ├── tools/
    │   └── echo.ts           # Default handler tools
    ├── resources/
    │   └── readme.ts         # Default handler resources
    └── prompts/
        └── greeting.ts       # Default handler prompts
```

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

### Define an MCP Prompt with Tags

Source: https://mcp-toolkit.nuxt.dev/prompts/patterns-advanced

Use defineMcpPrompt to create a prompt definition with metadata like tags and descriptions.

```typescript
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  tags: ['getting-started'],
  description: 'Help new developers set up the project',
  handler: async () => 'You are setting up this project...',
})
```

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

### Configure MCP Server Metadata

Source: https://mcp-toolkit.nuxt.dev/getting-started/configuration

Define server description and operational instructions within the Nuxt configuration.

```typescript
export default defineNuxtConfig({
  mcp: {
    description: 'Read and update todos for the current user.',
    instructions: 'Always call list-todos before create-todo. Group results by status.',
  },
})
```

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

### Expose Local Server with ngrok

Source: https://mcp-toolkit.nuxt.dev/apps/testing-publishing

Command to create a public HTTPS tunnel to a local Nuxt server running on port 3000.

```bash
ngrok http 3000
```

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

### Implement skeleton UI during tool calls

Source: https://mcp-toolkit.nuxt.dev/apps/patterns-reference

Use the pending state to provide visual feedback during in-flight tool execution without clearing existing data.

```vue
<button :disabled="pending" @click="callTool('color-picker', { base: nextBase })">
  {{ pending ? 'Mixing…' : 'Try this colour' }}
</button>
```

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

### sendPrompt(prompt)

Source: https://mcp-toolkit.nuxt.dev/apps/use-mcp-app

Sends a prompt to the host as if the user had typed it.

```APIDOC
## sendPrompt(prompt)

### Description
Push a message into the chat as if the user had typed it. The LLM routes this request, potentially invoking other tools or apps.

### Parameters
- **prompt** (string) - The message string to send to the chat.
```

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

### Manage initialData and data

Source: https://mcp-toolkit.nuxt.dev/apps/use-mcp-app

Demonstrates using initialData for static bootstrap values and data for reactive tool results.

```typescript
<script setup lang="ts">
const { initialData, data, callTool } = useMcpApp<{ listId: string }>()

async function refresh() {
  const result = await callTool('list_todos', { listId: initialData.value!.listId })
  // `data` now holds the latest tool result; `initialData` still has `{ listId }`
}
</script>
```

```html
<template>
  <section v-if="loading" class="skeleton" />
  <section v-else-if="data" class="content">
    {{ data.swatches.length }} swatches from {{ data.base }}
  </section>
</template>
```

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

### Configure MCP Clients

Source: https://mcp-toolkit.nuxt.dev/examples/authentication

Configuration templates for connecting MCP clients to the server using Bearer token authentication.

```json
{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}
```

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

### Define MCP Tool with Annotations

Source: https://mcp-toolkit.nuxt.dev/tools/annotations

Configures behavioral hints for a tool to inform MCP clients about its safety and state-modifying characteristics.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete-user',
  description: 'Delete a user account',
  inputSchema: {
    userId: z.string(),
  },
  annotations: {
    readOnlyHint: false,    // Tool modifies state
    destructiveHint: true,  // Tool performs destructive updates
    idempotentHint: true,   // Deleting the same user twice has no additional effect
    openWorldHint: false,   // Tool does not interact with external systems
  },
  handler: async ({ userId }) => {
    // ...
  },
})
```

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

### Expose MCP definitions via server card

Source: https://mcp-toolkit.nuxt.dev/advanced/listing-definitions

Expose the toolkit's catalog as a server-card.json file for agent discovery.

```typescript
import { listMcpDefinitions } from '@nuxtjs/mcp-toolkit/server'

export default defineEventHandler(async (event) => {
  const { tools, resources, prompts } = await listMcpDefinitions({ event })
  return {
    name: 'My MCP Server',
    description: 'Tools, resources and prompts exposed by my Nuxt app.',
    tools: tools.map(t => ({ name: t.name, description: t.description })),
    resources: resources.map(r => ({ name: r.name, uri: r.uri, description: r.description })),
    prompts: prompts.map(p => ({ name: p.name, description: p.description })),
  }
})
```

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

### Configure MCP Server Icons

Source: https://mcp-toolkit.nuxt.dev/getting-started/configuration

Provide a list of icons for the MCP server, specifying source, MIME type, and theme.

```typescript
export default defineNuxtConfig({
  mcp: {
    icons: [
      { src: 'https://example.com/icon-light.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'light' },
      { src: 'https://example.com/icon-dark.png', mimeType: 'image/png', sizes: ['64x64'], theme: 'dark' },
    ],
  },
})
```

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

### Multi-Step Wizard Tool

Source: https://mcp-toolkit.nuxt.dev/advanced/sessions

Manages a multi-step process by tracking the current step and previous inputs in the session.

```typescript
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

interface WizardSession {
  step: number
  projectName: string
  framework: string
}

export default defineMcpTool({
  name: 'wizard_next',
  description: 'Advance to the next step of the project setup wizard',
  inputSchema: {
    answer: z.string().describe('Answer for the current step'),
  },
  handler: async ({ answer }) => {
    const session = useMcpSession<WizardSession>()
    const step = await session.get('step') ?? 1

    if (step === 1) {
      await session.set('projectName', answer)
      await session.set('step', 2)
      return `Project name set to "${answer}". Step 2: Choose a framework (nuxt, next, svelte).`
    }

    if (step === 2) {
      await session.set('framework', answer)
      await session.set('step', 3)
      const name = await session.get('projectName')
      return `Creating "${name}" with ${answer}. Setup complete!`
    }

    return 'Wizard already completed. Use session.clear() to restart.'
  },
})
```

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

### Configure Cursor MCP Server

Source: https://mcp-toolkit.nuxt.dev/getting-started/connection

Manual configuration for the Cursor IDE by editing the ~/.cursor/mcp.json file.

```json
{
  "mcpServers": {
    "my-nuxt-app": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

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

### Media Result Helpers

Source: https://mcp-toolkit.nuxt.dev/tools/schema-handler

Use imageResult and audioResult helpers to return base64-encoded binary media.

```typescript
import { z } from 'zod'
import { defineMcpTool, imageResult, audioResult } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Generate chart',
  inputSchema: { data: z.array(z.number()) },
  handler: async ({ data }) => {
    const base64 = await generateChart(data)
    return imageResult(base64, 'image/png')
  },
})
```

```typescript
import { z } from 'zod'
import { defineMcpTool, audioResult } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Text to speech',
  inputSchema: { text: z.string() },
  handler: async ({ text }) => {
    const base64 = await synthesizeSpeech(text)
    return audioResult(base64, 'audio/mp3')
  },
})
```
Tokens:
Raw