---
title: "Building an MCP Server for Nuxt"
description: "我们如何构建 Nuxt MCP 服务器，使 AI 助手能够通过结构化数据和可组合工具访问我们的文档。"
canonical_url: "https://nuxt.zhcndoc.com/blog/building-nuxt-mcp"
---
# Building an MCP Server for Nuxt

> 我们如何构建 Nuxt MCP 服务器，使 AI 助手能够通过结构化数据和可组合工具访问我们的文档。

AI 助手正日益成为开发者体验中不可或缺的一部分。为了帮助它们提供关于 Nuxt 的准确且最新的信息，我们构建了一个 MCP 服务器，以结构化的方式公开我们的文档、博客文章和部署指南。以下是我们如何使用 [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev) 来实现这一目标，以及你如何能构建自己的 MCP 服务器。

::callout{icon="i-lucide-bot"}
想要试用 Nuxt MCP 服务器？跳转到 [Nuxt MCP 服务器文档](https://nuxt.zhcndoc.com/docs/4.x/guide/ai/mcp)。
::

## 什么是 MCP，以及为什么我们要构建它？

[模型上下文协议（Model Context Protocol，MCP）](https://modelcontextprotocol.io/) 是一个开放标准，允许 AI 助手安全地访问数据和工具。你可以将其视为专为 AI 助手设计的 API：它不是返回 HTML 或通用 JSON，而是提供结构化且语义化的数据，便于大型语言模型（LLMs）轻松理解和使用。

MCP 定义了三种主要原语：

- **资源（Resources）**：允许服务器共享为语言模型提供上下文的数据，如文件、数据库模式或应用特定信息。每个资源通过唯一 URI 标识。
- **工具（Tools）**：使 AI 模型能够与外部系统交互并执行操作（例如搜索或 API 调用）
- **提示（Prompts）**：可复用的提示模板，带参数，供用户调用

### 为什么选择 MCP 而非 RAG？

我们观察到，使用 MCP 服务器的 AI 助手相比传统的 RAG（检索增强生成）方法，能够提供**显著更好的响应**：

- **输入输出皆为结构化数据**：工具接受定义良好的参数，返回类型化数据，有效避免幻觉
- **可组合的工具**：AI 助手可以将多个工具串联使用，使用一个工具的输出作为另一个工具的输入（例如先搜索主题，再获取完整内容）
- **速度更快且更精准**：无需在查询时处理和拆分大型文档
- **始终保持最新**：直接访问内容层，无需重新索引
- **上下文感知导航**：AI 能够智能地在内容之间导航关系

现在，[Nuxt](https://nuxt.com/mcp) 和 [Nuxt UI](https://ui.nuxt.com/mcp) 都拥有类似架构的 MCP 服务器，使 AI 助手更轻松地帮助开发者使用这些框架。

## 技术架构

我们的 MCP 服务器直接内置于 [nuxt.com](http://nuxt.com)，使用了 [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev) 模块。该模块自动从服务器目录发现工具、资源和提示：

```
nuxt.com/
├── server/
│   └── mcp/
│       ├── tools/
│       │   ├── list-documentation-pages.ts
│       │   ├── get-documentation-page.ts
│       │   └── ...
│       ├── resources/
│       │   ├── nuxt-documentation-pages.ts
│       │   └── ...
│       └── prompts/
│           ├── find-documentation-for-topic.ts
│           └── ...
└── nuxt.config.ts
```

架构十分简单：你只需将工具、资源和提示定义为独立文件，模块会自动注册它们并公开一个 HTTP 端点供 MCP 客户端连接。无需手动设置服务器或配置传输，只需在正确目录中创建文件，即可立即使用。

## 实现深度解析

### 模块设置

入门只需将模块添加到 Nuxt 配置中：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'Nuxt',
  }
})
```

就这么简单。模块会自动扫描你的 `server/mcp/` 目录并注册发现的内容。

### 工具：提供给 AI 模型的操作

工具使语言模型可以通过接受参数并执行操作与外部系统交互。以下是我们实现的 `list_documentation_pages` 工具示例：

```ts [server/mcp/tools/list-documentation-pages.ts]
import { z } from 'zod'
import { queryCollection } from '@nuxt/content/server'

export default defineMcpTool({
  description: `列出所有可用的 Nuxt 文档页面及其分类和基础信息。

使用时机：当你需要探索或搜索某个主题的文档，但不知道具体页面路径时，使用此工具。

不适用时机：如果你已知具体页面路径，请直接使用 get_documentation_page。`,
  inputSchema: {
    version: z.enum(['3.x', '4.x', 'all']).optional().default('4.x').describe('要获取的文档版本')
  },
  cache: '1h',
  async handler({ version }) {
    const event = useEvent()

    const allDocs = await queryCollection(event, 'docsv4')
      .select('title', 'path', 'description')
      .all()

    return jsonResult(allDocs.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      url: `https://nuxt.com${doc.path}`
    })))
  }
})
```

请留意以下关键点：

- **`defineMcpTool`** 会被自动导入，无需手动导入
- **`inputSchema`** 使用 Zod 进行参数验证
- **`cache: '1h'`** 启用内置响应缓存
- **`jsonResult()`** 是一个帮助函数，用于正确格式化响应

工具名称会自动从文件名派生（`list-documentation-pages.ts` 会变为 `list_documentation_pages`）。

### 资源：为语言模型提供上下文

资源允许服务器共享给予语言模型上下文的数据，比如文件、数据库结构或应用特定信息。每个资源都有唯一 URI 识别。

暴露文件的最简单方式是使用 `file` 属性，它自动处理 URI 生成、MIME 类型检测和文件读取：

```ts [server/mcp/resources/readme.ts]
export default defineMcpResource({
  name: 'readme',
  description: '项目 README 文件',
  file: 'README.md' // 相对于项目根目录
})
```

对于动态资源，可以使用自定义处理函数：

```ts [server/mcp/resources/nuxt-documentation-pages.ts]
import { queryCollection } from '@nuxt/content/server'

export default defineMcpResource({
  uri: 'resource://nuxt-com/documentation-pages',
  description: '完整的 Nuxt 文档页面列表（默认为 v4.x）',
  cache: '1h',
  async handler(uri: URL) {
    const event = useEvent()

    const allDocs = await queryCollection(event, 'docsv4')
      .select('title', 'path', 'description')
      .all()

    const result = allDocs.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      version: '4.x',
      url: `https://nuxt.com${doc.path}`
    }))

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

与工具不同，资源由应用驱动，宿主应用会根据用户需求决定如何整合它们，例如通过显式选择的 UI 元素或自动包含上下文。

### 提示：可复用模板

提示是带参数的可复用模板，用户调用后返回对话格式，引导 AI 执行具体工作流程：

```ts [server/mcp/prompts/find-documentation-for-topic.ts]
import { z } from 'zod'
import { queryCollection } from '@nuxt/content/server'

export default defineMcpPrompt({
  description: '查找特定主题或功能的最佳 Nuxt 文档',
  inputSchema: {
    topic: z.string().describe('描述你想了解的内容'),
    version: z.enum(['3.x', '4.x']).optional().describe('要搜索的文档版本')
  },
  async handler({ topic, version = '4.x' }) {
    const event = useEvent()
    const docsVersion = version === '4.x' ? 'docsv4' : 'docsv3'

    const allDocs = await queryCollection(event, docsVersion)
      .select('title', 'path', 'description')
      .all()

    const allPages = allDocs?.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      url: `https://nuxt.com${doc.path}`
    })) || []

    return {
      messages: [{
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: `帮我找到这个主题的最佳 Nuxt 文档："${topic}"。以下是所有可用的文档页面：${JSON.stringify(allPages, null, 2)}`
        }
      }]
    }
  }
})
```

提示与工具不同：提示由用户调用并返回对话消息；工具由模型控制，返回结构化数据。

### 内置助手函数

该模块提供了若干自动导入的助手函数以简化常见模式：

- **`defineMcpTool`**、**`defineMcpResource`**、**`defineMcpPrompt`**：定义你的 MCP 原语
- **`jsonResult(data)`**：格式化工具的 JSON 响应
- **`errorResult(message)`**：从工具返回错误响应

### 使用 Nuxt 服务器工具函数

在处理函数中使用如 `useEvent()` 等 Nuxt 服务器工具，需要在 Nuxt 配置中启用 `asyncContext`：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})
```

然后即可访问 H3 事件，并使用来自 [Nuxt Content](https://content.nuxt.com) 的 `queryCollection` 等 Nuxt 服务器组合式函数。

## 构建你自己的 MCP 服务器

准备为你自己的应用构建 MCP 服务器了吗？借助 Nuxt MCP Toolkit，只需几分钟即可完成。

### 1. 安装模块

```bash [Terminal]
npx nuxi module add mcp-toolkit
```

### 2. 配置模块

向 Nuxt 配置添加基础配置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'my-app'
  }
})
```

### 3. 创建你的第一个工具

在 `server/mcp/tools/` 下创建文件：

```ts [server/mcp/tools/search.ts]
import { z } from 'zod'

export default defineMcpTool({
  description: '搜索我的内容',
  inputSchema: {
    query: z.string().describe('搜索查询')
  },
  async handler({ query }) {
    // 你的搜索逻辑
    const results = await searchContent(query)
    return jsonResult(results)
  }
})
```

就这样！你的 MCP 服务器现在可通过 `https://your-domain.com/mcp` 访问。

### 4. 添加资源和提示（可选）

你也可以按照同样的模式添加资源和提示：

```ts [server/mcp/resources/readme.ts]
export default defineMcpResource({
  name: 'readme',
  description: '项目 README 文件',
  file: 'README.md'
})
```

有关更高级的配置选项，请查看 [Nuxt MCP Toolkit 文档](https://mcp-toolkit.nuxt.dev)。

## 立即开始使用 Nuxt MCP 服务器

准备好体验 Nuxt MCP 的强大功能了吗？我们的服务器已上线，提供对所有 Nuxt 文档、博客文章和部署指南的访问。

### Cursor 快速安装

最简单方式是通过 Cursor 一键安装：

::u-button
```yaml [props]
to: cursor://anysphere.cursor-deeplink/mcp/install?name=nuxt&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbnV4dC5jb20vbWNwIn0%3D
label: 在 Cursor 中安装 Nuxt MCP 服务器
color: neutral
icon: i-custom-cursor
```
::

### 其他 AI 助手

Nuxt MCP 服务器支持 Claude Desktop、Windsurf、Visual Studio Code、ChatGPT 及诸多其他兼容 MCP 的 AI 助手。有关所有平台的完整设置说明，请查阅我们的 [MCP 文档](https://nuxt.zhcndoc.com/docs/4.x/guide/ai/mcp)。

我们鼓励你为自己的应用构建 MCP 服务器。无论是文档、API 参考还是领域知识，MCP 都让 AI 助手轻松为用户提供准确、有用的信息。

我们的 MCP 服务器完整源代码托管于 [GitHub](https://github.com/nuxt/nuxt.com) 的 [`server/mcp/`](https://github.com/nuxt/nuxt.com/tree/main/server/mcp) 目录，欢迎取用作为你自己的实现灵感！


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.