MCP Server
关于 MCP Servers
Model Context Protocol (MCP) 是一个开放协议，用于在 AI 应用和外部服务（例如文档）之间创建标准化连接。
每个 Docus 实例都包含内置 MCP server，让你的内容可以进入更广泛的 AI 生态，任何 MCP client（例如 Claude、Cursor、VS Code 等）都能连接到你的文档。
MCP Servers 如何工作
当 MCP server 连接到 AI 工具后，LLM 可以在生成回答时决定使用你的文档工具：
- LLM 可以在生成回答时主动搜索你的文档，而不只是用户明确要求时才搜索。
- LLM 会根据对话上下文和文档相关性判断何时使用工具。
- 每次工具调用都发生在生成过程中，让 LLM 能把文档中的实时信息纳入回答。
例如，如果用户提出一个编码问题，而 LLM 判断你的文档相关，它就可以搜索文档并把相关信息纳入回答，即使用户没有明确询问你的文档。
访问 MCP Server
你的 MCP server 会自动在文档 URL 的 /mcp 路径可用。
https://docs.example.com，MCP server URL 就是 https://docs.example.com/mcp。禁用 MCP Server
如果想禁用 MCP server，可以在 nuxt.config.ts 中配置：
export default defineNuxtConfig({
mcp: {
enabled: false,
},
})
内置工具
Docus 开箱提供两个工具，让任何 LLM 都能发现并读取你的文档：
list-pages
列出所有文档页面及其标题、路径和描述。AI 助手应先调用它来发现可用内容。
| 参数 | 类型 | 描述 |
|---|---|---|
locale | string（可选） | 按 locale 过滤页面 |
get-page
检索指定文档页面的完整 Markdown 内容。
| 参数 | 类型 | 描述 |
|---|---|---|
path | string（必填） | 页面路径（例如 /zh-cn/getting-started/installation） |
设置
Docus MCP server 使用 HTTP transport，可以安装到不同 AI 助手中。
Claude Code
使用 CLI 命令添加 server：
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"
}
}
}
Visual Studio Code
确保已经安装 GitHub Copilot 和 GitHub Copilot Chat 扩展。
或者手动创建/更新 .vscode/mcp.json 文件：
{
"servers": {
"my-docs": {
"type": "http",
"url": "https://docs.example.com/mcp"
}
}
}
Windsurf
- 打开 Windsurf，并进入 Settings > Windsurf Settings > Cascade
- 点击 Manage MCPs 按钮，然后选择 View raw config
- 添加以下配置：
{
"mcpServers": {
"my-docs": {
"type": "http",
"url": "https://docs.example.com/mcp"
}
}
}
Zed
- 打开 Zed，进入 Settings > Open Settings
- 打开 JSON 设置文件
- 添加以下 context server 配置：
{
"context_servers": {
"my-docs": {
"source": "custom",
"command": "npx",
"args": ["mcp-remote", "https://docs.example.com/mcp"],
"env": {}
}
}
}
自定义
Docus 使用 @nuxtjs/mcp-toolkit 模块，因此你可以通过自定义 tools、resources、prompts 和 handlers 扩展 MCP server。
添加自定义工具
在 server/mcp/tools/ 目录中创建新工具：
import { z } from 'zod'
export default defineMcpTool({
description: 'Search documentation by keyword',
inputSchema: {
query: z.string().describe('The search query'),
},
handler: async ({ query }) => {
const results = await searchDocs(query)
return {
content: [{ type: 'text', text: JSON.stringify(results) }],
}
},
})
添加 Resources
在 server/mcp/resources/ 目录中把文件或数据源暴露为 MCP resources。最简单的方式是使用 file 属性：
export default defineMcpResource({
file: 'CHANGELOG.md',
metadata: {
description: 'Project changelog',
},
})
这会自动处理 URI 生成、MIME 类型检测和文件读取。
添加 Prompts
在 server/mcp/prompts/ 目录中为 AI 助手创建可复用 prompts：
import { z } from 'zod'
export default defineMcpPrompt({
description: 'Get help with migrating between versions',
inputSchema: {
fromVersion: z.string().describe('Current version'),
toVersion: z.string().describe('Target version'),
},
handler: async ({ fromVersion, toVersion }) => {
return {
messages: [{
role: 'user',
content: {
type: 'text',
text: `Help me migrate from version ${fromVersion} to ${toVersion}. What are the breaking changes and steps I need to follow?`,
},
}],
}
},
})
添加自定义 Handlers
Handlers 允许你创建独立的 MCP endpoints，并为它们配置自己的 tools、resources 和 prompts。这适用于在不同路由暴露不同能力。
例如，你可以拥有：
/mcp- 主文档 MCP server/mcp/migration- 专用于迁移辅助的 MCP server
import { z } from 'zod'
const migrationTool = defineMcpTool({
name: 'migrate-v3-to-v4',
description: 'Migrate code from version 3 to version 4',
inputSchema: {
code: z.string().describe('The code to migrate'),
},
handler: async ({ code }) => {
// Migration logic
return {
content: [{ type: 'text', text: migratedCode }],
}
},
})
export default defineMcpHandler({
route: '/mcp/migration',
name: 'Migration Assistant',
version: '1.0.0',
tools: [migrationTool],
})
覆盖内置工具
你可以在项目中创建同名工具来覆盖默认的 list-pages 或 get-page 工具：
import { z } from 'zod'
export default defineMcpTool({
description: 'Custom list pages implementation',
inputSchema: {
locale: z.string().optional(),
category: z.string().optional(),
},
handler: async ({ locale, category }) => {
const pages = await getCustomPageList(locale, category)
return {
content: [{ type: 'text', text: JSON.stringify(pages) }],
}
},
})