Article·  

为 Nuxt 构建 MCP 服务器

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

Hugo Richard

@hugorcd

Sébastien Chopin

Sébastien Chopin

@Atinux

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

想要试用 Nuxt MCP 服务器？跳转到 Nuxt MCP 服务器文档。

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

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

MCP 定义了三种主要原语：

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

为什么选择 MCP 而非 RAG？

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

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

现在，Nuxt 和 Nuxt UI 都拥有类似架构的 MCP 服务器，使 AI 助手更轻松地帮助开发者使用这些框架。

技术架构

我们的 MCP 服务器直接内置于 nuxt.com，使用了 Nuxt MCP Toolkit 模块。该模块自动从服务器目录发现工具、资源和提示：

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 配置中：

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

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

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

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

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 类型检测和文件读取：

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

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

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 执行具体工作流程：

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：

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

然后即可访问 H3 事件，并使用来自 Nuxt Content 的 queryCollection 等 Nuxt 服务器组合式函数。

构建你自己的 MCP 服务器

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

1. 安装模块

Terminal
npx nuxi module add mcp-toolkit

2. 配置模块

向 Nuxt 配置添加基础配置：

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

3. 创建你的第一个工具

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

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. 添加资源和提示（可选）

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

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

有关更高级的配置选项，请查看 Nuxt MCP Toolkit 文档。

立即开始使用 Nuxt MCP 服务器

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

Cursor 快速安装

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

在 Cursor 中安装 Nuxt MCP 服务器

其他 AI 助手

Nuxt MCP 服务器支持 Claude Desktop、Windsurf、Visual Studio Code、ChatGPT 及诸多其他兼容 MCP 的 AI 助手。有关所有平台的完整设置说明，请查阅我们的 MCP 文档。

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

我们的 MCP 服务器完整源代码托管于 GitHub 的 server/mcp/ 目录，欢迎取用作为你自己的实现灵感！

← 返回博客
Nuxt on LinkedInNuxt on BlueskyNuxt on X