MCP Server
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 服务卡片一并移除:
export default defineNuxtConfig({
movkNuxtDocs: {
mcp: false
}
})
nuxt generate 纯静态部署时不可用。名称与浏览器跳转
其他选项写在 mcp 下,由 @nuxtjs/mcp-toolkit 读取:
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、emits | componentName、full、locale |
list-examples | 列出全部示例名称 | 无 |
get-example | 返回示例源码 | exampleName |
search-icons | 在一个 Iconify 图标集中搜索图标,默认 lucide | query、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
claude mcp add --transport http my-docs https://docs.example.com/mcp
Cursor
或在项目根目录创建 .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 扩展。
或在 .vscode/mcp.json 中添加:
{
"servers": {
"my-docs": {
"type": "http",
"url": "https://docs.example.com/mcp"
}
}
}
Claude Desktop
在「Settings → Developer → Edit Config」打开的 claude_desktop_config.json 中添加,然后重启应用:
{
"mcpServers": {
"my-docs": {
"command": "npx",
"args": ["mcp-remote", "https://docs.example.com/mcp"]
}
}
}
Opencode
{
"$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 内置的定义合并。
自定义工具
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)即可覆盖内置实现。
自定义资源
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)
}]
}
}
})
自定义提示词
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 过滤。在项目中创建同路径文件即可替换:
import { defineMcpHandler, getMcpTools } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpHandler({
async tools(event) {
return getMcpTools({ event, orphansOnly: true })
}
})