MCP Server

每个文档站默认在 /mcp 提供 Model Context Protocol 服务。本页列出内置的工具、资源与提示词,说明如何在 Claude Code、Cursor、VS Code 等客户端接入,以及如何关闭、限制或扩展服务器。
查看源码

Model Context Protocol(MCP)是 AI 应用连接外部服务的开放协议。Movk Nuxt Docs 基于 @nuxtjs/mcp-toolkit 内置一个 MCP Server,接入后,Claude、Cursor 等助手会在需要时自行搜索和阅读你的文档,而不是凭训练数据作答。

服务器默认开启,地址为站点的 /mcp 路径。例如文档部署在 https://docs.example.com,则 MCP 地址为 https://docs.example.com/mcp。AI Chat 也通过这组工具读取文档。

配置

关闭

MCP 由功能开关 movkNuxtDocs.mcp 控制,关闭后 @nuxtjs/mcp-toolkit 不会被安装为模块,/mcp 与 MCP 服务卡片一并移除:

nuxt.config.ts
export default defineNuxtConfig({
  movkNuxtDocs: {
    mcp: false
  }
})
启用 AI Chat 时不能关闭 MCP,否则构建报错。
MCP Server 需要运行中的服务端,nuxt generate 纯静态部署时不可用。

名称与浏览器跳转

其他选项写在 mcp 下,由 @nuxtjs/mcp-toolkit 读取:

nuxt.config.ts
export default defineNuxtConfig({
  mcp: {
    // 客户端看到的服务器名称
    name: 'My Docs',
    // 在浏览器中直接打开 /mcp 时跳转到的页面
    browserRedirect: '/docs/ai/mcp'
  }
})

browserRedirect 同时作为 MCP 服务卡片 中的文档地址。更多选项见 MCP Toolkit 文档。

内置能力

工具

工具用途主要参数
search-documentation按标题、路径或描述搜索页面,不传参数时列出全部页面search、section、locale
get-documentation-page按路径返回一页的 Markdown,可只取指定的 H2 章节path、headings
search-composables按关键词查找组合式函数页面search、locale
get-component返回组件文档与元信息,可只取部分章节componentName、sections、locale
get-component-metadata返回组件的 props、slots、emitscomponentName、full、locale
list-examples列出全部示例名称无
get-example返回示例源码exampleName
search-icons在一个 Iconify 图标集中搜索图标,默认 lucidequery、collection、limit

组件与示例相关的工具依赖组件文档功能,未启用时没有可返回的数据。search-composables 查找路径中含 composables/ 的页面(如 /docs/composables/ 或 /docs/reference/composables/),get-component 等查找路径中含 /components/ 的页面。

资源

URI内容
resource://docs/documentation-pages全部文档页面的标题、描述与路径
resource://docs/components组件页面及其分类与 keywords
resource://docs/composables组合式函数页面
resource://docs/examples示例名称列表

资源只列出默认语言的内容。

提示词

提示词用途
find-component-for-usecase根据使用场景推荐合适的组件
implement-component-with-props基于组件文档与元数据生成实现代码

多语言

启用国际化后,带 locale 参数的工具与两个提示词按该语言查询对应的内容集合与 /{locale}/docs 前缀,省略时为默认语言;传入未注册的语言返回 400 并列出可用语言。get-documentation-page 直接按路径定位,如 /en/docs/getting-started。

限制工具

客户端可以通过 X-MCP-Tools 请求头(逗号分隔的工具名)只暴露需要的工具,减少上下文占用:

  • 不传该请求头:暴露全部工具
  • 传空值:不暴露任何工具
  • 包含未知工具名:返回 400

这一过滤由 layer 的 server/mcp/index.ts 实现,客户端配置示例见下文 Cursor 一节。

接入客户端

MCP Server 使用 HTTP 传输,以下示例中的 https://docs.example.com/mcp 替换为你的地址。

Claude Code

Terminal
claude mcp add --transport http my-docs https://docs.example.com/mcp

Cursor

Install MCP in Cursor

或在项目根目录创建 .cursor/mcp.json:

.cursor/mcp.json
{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp",
      "headers": {
        "X-MCP-Tools": "search-documentation,get-documentation-page"
      }
    }
  }
}

去掉 headers 即暴露全部工具。

Visual Studio Code

需要安装 GitHub Copilot 与 GitHub Copilot Chat 扩展。

Install MCP in VS Code

或在 .vscode/mcp.json 中添加:

.vscode/mcp.json
{
  "servers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}

Claude Desktop

在「Settings → Developer → Edit Config」打开的 claude_desktop_config.json 中添加,然后重启应用:

claude_desktop_config.json
{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["mcp-remote", "https://docs.example.com/mcp"]
    }
  }
}

Opencode

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-docs": {
      "type": "remote",
      "url": "https://docs.example.com/mcp",
      "enabled": true
    }
  }
}

ChatGPT

在 ChatGPT 网页版「设置 → Connectors → Advanced settings」开启开发者模式,然后新建连接器,MCP server URL 填写你的地址,认证选择 None。

接入后可以直接提问,例如「列出所有文档页面」「读取安装指南」「ComponentProps 接受哪些 props?」,助手会自行选择工具。

扩展

服务器会自动加载项目 server/mcp/ 下的文件,与 layer 内置的定义合并。

自定义工具

server/mcp/tools/search-pages.ts
import { z } from 'zod'
import { queryCollection } from '@nuxt/content/server'

export default defineMcpTool({
  description: '按关键词搜索文档标题与描述',
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false
  },
  inputSchema: {
    search: z.string().describe('搜索关键词')
  },
  cache: '30m',
  async handler({ search }) {
    const event = useEvent()
    const keyword = search.toLowerCase()

    const pages = await queryCollection(event, 'docs')
      .select('title', 'description', 'path')
      .all()

    return pages.filter(page =>
      page.title?.toLowerCase().includes(keyword)
      || page.description?.toLowerCase().includes(keyword)
    )
  }
})

工具名默认取文件名(kebab-case)。在项目中创建与内置工具同名的文件(如 server/mcp/tools/search-documentation.ts)即可覆盖内置实现。

自定义资源

server/mcp/resources/page-index.ts
import { queryCollection } from '@nuxt/content/server'

export default defineMcpResource({
  uri: 'resource://docs/page-index',
  description: '全部页面的标题与路径',
  cache: '1h',
  async handler(uri: URL) {
    const pages = await queryCollection(useEvent(), 'docs')
      .select('title', 'path')
      .all()

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

自定义提示词

server/mcp/prompts/explain-config.ts
import { z } from 'zod'

export default defineMcpPrompt({
  description: '解释一个配置项的作用与默认值',
  inputSchema: {
    key: z.string().describe('配置项路径,如 header.nav')
  },
  async handler({ key }) {
    return {
      messages: [{
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: `阅读 app.config 参考页,解释配置项 ${key} 的作用、类型与默认值。`
        }
      }]
    }
  }
})

覆盖默认处理器

layer 的 server/mcp/index.ts 是默认处理器,负责 X-MCP-Tools 过滤。在项目中创建同路径文件即可替换:

server/mcp/index.ts
import { defineMcpHandler, getMcpTools } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  async tools(event) {
    return getMcpTools({ event, orphansOnly: true })
  }
})
多个处理器、会话、鉴权等高级用法见 MCP Toolkit 文档。
Copyright © 2024 - 2026