---
title: "MCP Server"
description: "每个文档站默认在 /mcp 提供 Model Context Protocol 服务。本页列出内置的工具、资源与提示词，说明如何在 Claude Code、Cursor、VS Code 等客户端接入，以及如何关闭、限制或扩展服务器。"
canonical_url: "https://docs.mhaibaraai.cn/docs/ai/mcp"
---
# MCP Server

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

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

服务器默认开启，地址为站点的 `/mcp` 路径。例如文档部署在 `https://docs.example.com`，则 MCP 地址为 `https://docs.example.com/mcp`。[AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat) 也通过这组工具读取文档。

## 配置

### 关闭

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movkNuxtDocs: {
    mcp: false
  }
})
```

> [!WARNING]
> 
> 启用 
> 
> AI Chat
> 
>  时不能关闭 MCP，否则构建报错。

> [!NOTE]
> 
> MCP Server 需要运行中的服务端，
> 
> nuxt generate
> 
>  纯静态部署时不可用。

### 名称与浏览器跳转

其他选项写在 `mcp` 下，由 `@nuxtjs/mcp-toolkit` 读取：

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

`browserRedirect` 同时作为 [MCP 服务卡片](https://docs.mhaibaraai.cn/docs/ai/agent-discovery#mcp-%E6%9C%8D%E5%8A%A1%E5%8D%A1%E7%89%87) 中的文档地址。更多选项见 [MCP Toolkit 文档](https://mcp-toolkit.nuxt.dev)。

## 内置能力

### 工具

| 工具 | 用途 | 主要参数 |
| --- | --- | --- |
| `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` |

组件与示例相关的工具依赖[组件文档](https://docs.mhaibaraai.cn/docs/components/component-props)功能，未启用时没有可返回的数据。`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` | 基于组件文档与元数据生成实现代码 |

### 多语言

启用[国际化](https://docs.mhaibaraai.cn/docs/guide/i18n)后，带 `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

```bash [Terminal]
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

### Cursor

::install-button{url="https://docs.example.com/mcp"}
::

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

```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-button{url="https://docs.example.com/mcp" ide="vscode"}
::

或在 `.vscode/mcp.json` 中添加：

```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` 中添加，然后重启应用：

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

### Opencode

```json [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 内置的定义合并。

### 自定义工具

```ts [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`）即可覆盖内置实现。

### 自定义资源

```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)
      }]
    }
  }
})
```

### 自定义提示词

```ts [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` 过滤。在项目中创建同路径文件即可替换：

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

export default defineMcpHandler({
  async tools(event) {
    return getMcpTools({ event, orphansOnly: true })
  }
})
```

> [!TIP]
> See: https://mcp-toolkit.nuxt.dev
> 
> 多个处理器、会话、鉴权等高级用法见 MCP Toolkit 文档。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
