Built-in AI chat assistant

Overview

A Nuxt module that provides an AI chat interface powered by MCP (Model Context Protocol) tools.

Quick start

Movk Nuxt Docs already includes the AI Chat module. To enable it, apply the following configuration:

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  aiChat: {
    model: 'zai/glm-4.7',
    models: [
      'zai/glm-4.7',
      'anthropic/claude-sonnet-4.6',
      'google/gemini-2.5-flash'
    ],
  }
})

export default defineAppConfig({
  aiChat: {
    floatingInput: true,
    explainWithAi: true,
    faqQuestions: [
      {
        category: 'Quick start',
        items: ['How do I install it?', 'How do I configure it?'],
      },
      {
        category: 'Advanced usage',
        items: ['How do I customize it?'],
      },
    ],
    shortcuts: {
      focusInput: 'meta_i'
    },
    texts: {
      title: 'AI Assistant',
      placeholder: 'Type your question...',
      // ... more text configuration
    }
  }
})

# AI Gateway: a single key proxying multiple providers (recommended)
AI_GATEWAY_API_KEY=your-gateway-key

# Or connect directly to a built-in provider: configure as needed; the matching prefix bypasses the Gateway and uses the official SDK directly
DEEPSEEK_API_KEY=your-deepseek-key
ALIBABA_API_KEY=your-alibaba-key
ZHIPU_API_KEY=your-zhipu-key

Automatic integration

By default, the following features are enabled automatically:

• AI Chat trigger button: shown on the right side of the page; clicking it opens the AI assistant panel
• Floating input: shown at the bottom of documentation pages (controlled via appConfig.aiChat.floatingInput)
• AI explain button: shown in the documentation sidebar (controlled via appConfig.aiChat.explainWithAi)

Manual integration (optional)

If you need to use the AI Chat components on a custom page:

<template>
  <div>
    <AiChat />
    <AiChatPanel />
  </div>
</template>

Floating input

The floating input is integrated at the bottom of documentation pages by default. To use it on a custom page:

<template>
  <div>
    <Teleport to="body">
      <ClientOnly>
        <AiChatPanel />
        <AiChatFloatingInput />
      </ClientOnly>
    </Teleport>
  </div>
</template>

Programmatic control

Use the useAIChat composable to control the chat:

<script setup>
const {
  isEnabled,
  isOpen,
  messages,
  toggleChat,
  open
} = useAIChat()

// Open the chat and send an initial message
open('How do I install this module?')

// Toggle chat visibility
toggle()
</script>

Customization

Custom model providers

import { modelProviderRegistry } from '#ai-chat/server/utils/modelProviders'
import { createAnthropic } from '@ai-sdk/anthropic'

export default defineNitroPlugin(() => {
  // Override the default provider configuration
  modelProviderRegistry.register('anthropic', ({ config, modelId }) => {
    const anthropic = createAnthropic({
      apiKey: config.anthropicApiKey,
      // Custom configuration...
    })
    return anthropic(modelId)
  })
})

Configure the environment variable:

ANTHROPIC_API_KEY=your_api_key

Built-in providers

After configuring the corresponding environment variable, models matching a prefix connect directly to the official SDK; models that do not match any prefix fall back to the AI Gateway. An optional <PROVIDER>_BASE_URL (e.g. ALIBABA_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 to switch to Alibaba Cloud's China endpoint) overrides the endpoint/region. Registering the same prefix with modelProviderRegistry.register(prefix, ...) in server/plugins/ overrides the built-in implementation.

System prompt

To customize the AI's behavior, create or edit the system prompt in the following file: server/api/ai-chat.ts

Styling

The components use Nuxt UI and Tailwind CSS design tokens. You can customize the appearance by modifying the component files or overriding UI properties.

API

AiChat

The simplest way to integrate, showing the assistant button.

AiChatFloatingInput

A floating input at the bottom of the viewport. Requires no props.

Keyboard shortcuts:

• ⌘I / Ctrl+I - focus the input
• Escape - blur the input
• Enter - submit the question

AiChatModelSelect

A model selection dropdown for switching AI models. Requires no props.

AiChatPanel

The complete AI chat panel interface.

Features:

• An expandable/collapsible sidebar panel
• Automatically pushes the main content area
• Built-in message history and streaming responses
• Supports code highlighting and Markdown rendering

AiChatDisabled

The disabled-state component shown when the AI Chat feature is not enabled.

Composables

useAIChat()

Conversation state management, providing state control and message management for the chat interface.

Return values

useModels()

Model configuration management, controlling the list of available AI models and the currently selected model.

Return values

useHighlighter()

Asynchronously loads a Shiki code highlighter instance, used for syntax highlighting of code blocks.

Return value

Returns a Promise that resolves to a configured Shiki Highlighter instance.

const highlighter = await useHighlighter()

// Usage example
const html = highlighter.codeToHtml(code, {
  lang: 'typescript',
  theme: 'material-theme-palenight'
})

useToolCall(state, toolName, input)

An extension point for AI chat tool calls, allowing you to customize the text label and icon shown when a tool is called.

When the AI assistant calls a tool, the AiChatPanel component calls this composable to get the display information for that tool. The default implementation returns an empty object, and the built-in tool labels are handled by the component itself. By overriding this composable in your application layer, you can add display support for custom tools.

Parameters

Return values

Extending with custom tools

Create a composable of the same name in your application layer to override the default implementation:

import type { ToolState } from '#ai-chat/types'

export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
  const searchVerb = state === 'output-available' ? 'Searched' : 'Searching'
  const readVerb = state === 'output-available' ? 'Read' : 'Reading'

  const toolMessage: Record<string, string> = {
    'search-api': `${searchVerb} the API docs`,
    'get-schema': `${readVerb} the ${input.name || ''} type definition`,
  }

  const toolIcon: Record<string, string> = {
    'search-api': 'i-lucide-book-open',
    'get-schema': 'i-lucide-braces',
  }

  return {
    toolMessage,
    toolIcon,
  }
}

Default handling of built-in tools

The following tools are handled internally by AiChatPanel and do not need to be defined in useToolCall. The default handling is tailored to the MCP tools built into the current project, and a single configuration generates both the display text and the icon: