MkDocs MCP Search Server

MkDocs MCP搜索服务器

Claude桌面快速入门

请按照安装说明进行操作 Claude Desktop用户的模型上下文协议快速入门。您需要在MCP配置文件中添加一个部分，如下所示：

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@serverless-dna/mkdocs-mcp",
        "https://your-doc-site",
        "Describe what you are enabling search for to help your AI Agent"
      ]
    }
  }
}

概述

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

特性

• 符合MCP标准的服务器，用于与LLM集成
• 使用lunr.js索引进行本地搜索
• 特定版本的文档搜索功能
• MkDocs材料HTML到Markdown转换，带有结构化JSON响应
• 基于语言检测和上下文的代码示例提取
• 多语言文档的选项卡视图支持
• 美人鱼图保存
• 自动URL解析（相对于绝对值）
• 搜索索引和转换文档的智能缓存

安装

# Install dependencies
pnpm install

# Build the project
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 utility for structured logging...",
      "location": "core/logger/"
    },
    {
      "title": "Configuration",
      "url": "https://docs.example.com/latest/core/logger/#config",
      "score": 0.8,
      "preview": "Configure the logger with custom settings...",
      "location": "core/logger/#config",
      "parentArticle": {
        "title": "Logger",
        "location": "core/logger/",
        "url": "https://docs.example.com/latest/core/logger/"
      }
    }
  ]
}

特征：

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

获取文档工具

服务器提供 fetchMkDoc 检索和转换文档页面的工具：

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

样本响应：

{
  "title": "Getting Started",
  "markdown": "# Getting Started\n\nThis guide will help you...\n\n## Installation\n\n```bash\nnpm install example\n```",
  "code_examples": [
    {
      "title": "Installation",
      "description": "Install the package using npm",
      "code": "```bash\nnpm install example\n```"
    },
    {
      "title": "Basic Usage",
      "description": "Import and initialize the library",
      "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：缓存存储的基本目录（默认： /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)
• 视窗: %TEMP%\mkdocs-mcp-cache

你可以用以下命令覆盖它 CACHE_BASE_PATH 环境变量。

发展

建筑

pnpm build

测试

pnpm test

Claude桌面MCP配置

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

下面的配置显示了在使用windows Linux子系统（WSL）进行开发时在windows claude桌面中运行。您可以在Mac或Linux环境中以类似的方式运行。

输出是一个捆绑文件，它使安装在windows中的Node能够运行MCP服务器，因为所有依赖项都是捆绑的。

{
  "mcpServers": {
    "powertools": {
	"command": "node",
	"args": [
	  "\\\\wsl$\\Ubuntu\\home\\walmsles\\dev\\serverless-dna\\mkdocs-mcp\\dist\\index.js",
    "Search online documentation"
	]
    }
  }
}

运作原理

搜索功能

1. 服务器为每个支持的运行时加载预构建的lunr.js索引
2. 当收到搜索请求时，它：

- 根据版本加载相应的索引（当前固定为最新版本） - 使用lunr.js执行搜索 - 以JSON格式返回搜索结果

1. 然后，LLM可以使用这些结果来查找相关的文档页面

文档获取

1. 当收到带有URL的获取请求时：

- 获取HTML内容（带缓存） - 使用Cheerio解析MkDocs材料HTML结构 - 删除导航、页眉、页脚和其他UI元素 - 将选项卡视图处理为连续的部分 - 使用语言检测和上下文提取代码块 - 将所有相对URL解析为绝对URL - 将已清理的HTML转换为markdown - 返回一个包含标题、markdown和代码示例的结构化JSON响应

1. 缓存结果以提高后续请求的性能

许可证

麻省理工学院