> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/ai/mcp.md](/docs/manual/zh/ai/mcp.md).

---
title: MCP 服务器
description: 使用原生 MCP 服务器将您的文档连接到 AI 工具。
navigation:
  icon: i-lucide-cpu
---

## 关于 MCP 服务器

[模型上下文协议（MCP）](https://modelcontextprotocol.io/) 是一个开放协议，用于将 AI 应用连接到外部工具和数据源。

每个 TockDocs 实例都包含一个内置的 MCP 服务器，因此 Claude、Cursor、VS Code、Windsurf 和 Zed 等 AI 工具可以搜索和阅读您的文档。

## 访问您的 MCP 服务器

您的 MCP 服务器可在文档 URL 的 `/mcp` 路径下访问。

::note
如果您的文档托管在 `https://docs.example.com`，您的 MCP 服务器 URL 是 `https://docs.example.com/mcp`。
::

## 禁用 MCP 服务器

如果您想禁用 MCP 服务器，请在 `nuxt.config.ts` 中进行配置：

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

## 内置工具

TockDocs 提供三个内置工具。

### `search-pages`

搜索标题、描述、标题、路径和完整页面正文内容。

| 参数      | 类型             | 描述 |
| --------- | ---------------- | ---- |
| `query`   | string（必填）   | 搜索查询或自然语言问题 |
| `limit`   | number（可选）   | 返回的最大结果数 |
| `kb`      | string（可选）   | 在多知识库站点中限定结果范围的知识库 ID |
| `locale`  | string（可选）   | 限定结果范围的语言代码 |

`search-pages` 主要使用 FlexSearch 进行检索，使用 Fuse.js 作为模糊回退。

### `list-pages`

列出可用的文档页面及其标题、路径、描述和 URL。

| 参数      | 类型             | 描述 |
| --------- | ---------------- | ---- |
| `kb`      | string（可选）   | 在多知识库站点中限定结果范围的知识库 ID |
| `locale`  | string（可选）   | 限定结果范围的语言代码 |

### `get-page`

检索特定文档页面的完整 Markdown 内容。

| 参数    | 类型             | 描述 |
| ------- | ---------------- | ---- |
| `path`  | string（必填）   | 精确的页面路径 |

示例：

- 知识库模式：`/docs/manual/zh/getting-started/installation`
- 传统 i18n 模式：`/zh/getting-started/installation`
- 传统单语言模式：`/getting-started/installation`

## 知识库感知行为

在多知识库站点中：

- 外部 MCP 客户端可以向 `search-pages` 和 `list-pages` 显式传递 `kb` 和 `locale`
- 内置助手也可以从触发请求的文档页面推断当前知识库和语言

这使检索在可能时限定在活动文档集范围内。

## 设置

TockDocs MCP 服务器使用 HTTP 传输，可以连接到多个助手。

### Claude Code

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

### Cursor

:install-button{ide="cursor" label="在 Cursor 中安装" url="https://docs.example.com/mcp"}

或手动创建/更新 `.cursor/mcp.json`：

```json [.cursor/mcp.json]
{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}
```

### Visual Studio Code

:install-button{ide="vscode" label="在 VS Code 中安装" url="https://docs.example.com/mcp"}

或手动创建/更新 `.vscode/mcp.json`：

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

### Windsurf

```json [.codeium/windsurf/mcp_config.json]
{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}
```

### Zed

```json [.config/zed/settings.json]
{
  "context_servers": {
    "my-docs": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://docs.example.com/mcp"],
      "env": {}
    }
  }
}
```

## 自定义

TockDocs 使用 `@nuxtjs/mcp-toolkit`，因此您可以使用自定义工具、资源、提示词和处理程序扩展 MCP 服务器。

### 添加自定义工具

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

export default defineMcpTool({
  description: '按关键字搜索文档',
  inputSchema: {
    query: z.string().describe('搜索查询'),
  },
  handler: async ({ query }) => {
    const results = await searchDocs(query)
    return {
      content: [{ type: 'text', text: JSON.stringify(results) }],
    }
  },
})
```

### 添加资源

```ts [server/mcp/resources/changelog.ts]
export default defineMcpResource({
  file: 'CHANGELOG.md',
  metadata: {
    description: '项目变更日志',
  },
})
```

### 添加提示词

```ts [server/mcp/prompts/migration-help.ts]
import { z } from 'zod'

export default defineMcpPrompt({
  description: '获取版本迁移帮助',
  inputSchema: {
    fromVersion: z.string().describe('当前版本'),
    toVersion: z.string().describe('目标版本'),
  },
  handler: async ({ fromVersion, toVersion }) => {
    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `帮我从版本 ${fromVersion} 迁移到 ${toVersion}。有哪些变化？`,
          },
        },
      ],
    }
  },
})
```

### 添加独立处理程序

您可以暴露不同的 MCP 端点及其各自的工具集。

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

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  description: '将代码从版本 3 迁移到版本 4',
  inputSchema: {
    code: z.string().describe('要迁移的代码'),
  },
  handler: async ({ code }) => {
    return {
      content: [{ type: 'text', text: code }],
    }
  },
})

export default defineMcpHandler({
  route: '/mcp/migration',
  name: '迁移助手',
  version: '1.0.0',
  tools: [migrationTool],
})
```

::tip{to="https://mcp-toolkit.nuxt.dev/"}
请参阅 `@nuxtjs/mcp-toolkit` 文档了解完整的 API 接口。
::