MkDocs MCP 搜索服务器

一个提供搜索功能的模型上下文协议（MCP）服务器，适用于任何由MkDocs驱动的网站。该服务器依赖于现有的MkDocs搜索实现，使用Lunr.Js搜索引擎。

Claude Desktop 快速入门

请遵循Model Context Protocol 快速入门指南中的安装说明。您需要在MCP配置文件中添加如下部分：

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@serverless-dna/mkdocs-mcp",
        "https://your-doc-site",
        "描述您启用搜索的内容，以帮助您的AI代理"
      ]
    }
  }
}

概述

该项目实现了一个MCP服务器，使大型语言模型（LLMs）能够搜索任何已发布的mkdocs文档站点。它使用lunr.js进行高效的本地搜索，并提供可以总结并呈现给用户的搜索结果。

特性

• 符合MCP标准的服务器，用于与LLMs集成
• 使用lunr.js索引进行本地搜索
• 版本特定的文档搜索能力
• 将MkDocs Material HTML转换为Markdown，并提供结构化的JSON响应
• 提取代码示例，包括语言检测和上下文
• 支持多语言文档的标签视图
• 保存Mermaid图表
• 自动解析URL（相对转绝对）
• 对搜索索引和转换文档进行智能缓存

安装

# 安装依赖
pnpm install

# 构建项目
pnpm build

使用方法

该服务器可以作为MCP服务器运行，通过stdio通信：

npx -y @serverless-dna/mkdocs-mcp https://your-doc-site.com

可用工具

搜索工具

服务器提供了一个searchMkDoc工具，参数如下：

• search: 搜索查询字符串
• version: 可选版本字符串（仅适用于有版本的站点）

示例响应：

{
  "query": "logger",
  "version": "latest",
  "total": 3,
  "results": [
    {
      "title": "Logger",
      "url": "https://docs.example.com/latest/core/logger/",
      "score": 1.2,
      "preview": "结构化日志的Logger实用程序...",
      "location": "core/logger/"
    },
    {
      "title": "Configuration",
      "url": "https://docs.example.com/latest/core/logger/#config",
      "score": 0.8,
      "preview": "使用自定义设置配置日志...",
      "location": "core/logger/#config",
      "parentArticle": {
        "title": "Logger",
        "location": "core/logger/",
        "url": "https://docs.example.com/latest/core/logger/"
      }
    }
  ]
}

特性：

• 基于置信度的过滤（可配置阈值）
• 具有标题匹配和提升的高级评分
• 部分结果的父文章上下文
• 限制为顶级结果（可配置，默认：10）

获取文档工具

服务器提供了一个fetchMkDoc工具，用于检索和转换文档页面：

• url: 要获取的文档页面的URL

示例响应：

{
  "title": "开始使用",
  "markdown": "# 开始使用\n\n此指南将帮助您...\n\n## 安装\n\n```bash\nnpm install example\n```",
  "code_examples": [
    {
      "title": "安装",
      "description": "使用npm安装包",
      "code": "```bash\nnpm install example\n```"
    },
    {
      "title": "基本用法",
      "description": "导入并初始化库",
      "code": "```python\nfrom example import Client\nclient = Client()\n```"
    }
  ],
  "url": "https://docs.example.com/getting-started/"
}

配置

服务器可以通过环境变量进行配置：

• SEARCH_CONFIDENCE_THRESHOLD: 搜索结果的最小置信分数（默认：0.1）
• SEARCH_MAX_RESULTS: 返回的最大搜索结果数（默认：10）
• CACHE_BASE_PATH: 缓存存储的基本目录（默认：<system-tmp>/mkdocs-mcp-cache）

示例：

SEARCH_MAX_RESULTS=20 SEARCH_CONFIDENCE_THRESHOLD=0.2 npx @serverless-dna/mkdocs-mcp https://your-doc-site.com

缓存位置： 默认情况下，服务器会在系统的临时目录中缓存搜索索引和转换后的文档：

• macOS/Linux: /tmp/mkdocs-mcp-cache（或$TMPDIR）
• Windows: %TEMP%\mkdocs-mcp-cache

您可以使用CACHE_BASE_PATH环境变量覆盖这一设置。

开发

构建

pnpm build

测试

pnpm test

Claude Desktop MCP 配置

在开发过程中，您可以使用以下配置在Claude Desktop上运行MCP服务器。

下面的配置显示了在Windows Claude Desktop上开发时使用Windows子系统Linux（WSL）的情况。Mac或Linux环境也可以类似方式运行。

输出是一个捆绑文件，这使得安装在Windows上的Node可以运行MCP服务器，因为所有依赖项都被捆绑在一起。

{
  "mcpServers": {
    "powertools": {
	"command": "node",
	"args": [
	  "\\\\wsl$\\Ubuntu\\home\\walmsles\\dev\\serverless-dna\\mkdocs-mcp\\dist\\index.js",
    "在线文档搜索"
	]
    }
  }
}

工作原理

搜索功能

1. 服务器加载每个支持的运行时的预构建lunr.js索引
2. 当收到搜索请求时，它会：
   • 根据版本加载适当的索引（当前固定为最新版）
   • 使用lunr.js执行搜索
   • 以JSON形式返回搜索结果
3. LLM可以使用这些结果来查找相关的文档页面

文档获取

1. 当收到带有URL的获取请求时：
   • 获取HTML内容（带缓存）
   • 使用Cheerio解析MkDocs Material HTML结构
   • 移除导航、页眉、页脚和其他UI元素
   • 处理标签视图为连续的部分
   • 提取代码块，包括语言检测和上下文
   • 解析所有相对URL为绝对URL
   • 将清理后的HTML转换为Markdown
   • 返回一个包含标题、Markdown和代码示例的结构化JSON响应
2. 结果会被缓存，以提高后续请求的性能

许可证

MIT