AI导哈

文档搜索服务

MkDocs Material MCP Server 是一个为 MkDocs Material 文档站点提供搜索和检索功能的工具，支持多站点配置和动态工具生成。

  • by ojacques
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ojacques/mkdocs-mcp

使用说明

MkDocs材料MCP服务器

用于文档站点的模型上下文协议（MCP）服务器 MkDocs材料.

此MCP服务器提供了从任何基于MkDocs Material的文档网站搜索和检索文档的工具。默认情况下，它连接到 MkDocs材料文档 本身。

特性

  • 搜索文档：在整个文档网站上查找相关页面
  • 检索页面：获取带有源URL的markdown格式的完整页面内容
  • 多站点支持：同时配置多个MkDocs材料站点
  • 动态工具生成：为每个配置的站点自动创建MCP工具

先决条件

安装要求

  • 安装 紫外线 来自Astral或 GitHub自述
  • 使用以下命令安装Python 3.10或更高版本 uv python install 3.10 （或更新版本）

安装

Kiro命令行界面

在MCP客户端中配置MCP服务器（如 Kiro命令行界面)配置(~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "mkdocs": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": ["search_mkdocs-material", "get_mkdocs-material_page"]
    }
  }
}

自定义MkDocs材料网站

要与您自己的MkDocs Material驱动文档一起使用：

{
  "mcpServers": {
    "my-docs": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MKDOCS_SITES": "mysite=https://your-docs-site.com"
      },
      "disabled": false,
      "autoApprove": ["search_mysite", "get_mysite_page"]
    }
  }
}

多个站点

配置多个MkDocs材料站点：

{
  "mcpServers": {
    "mkdocs-multi": {
      "command": "uvx",
      "args": ["mkdocs-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MKDOCS_SITES": "mkdocs-material=https://squidfunk.github.io/mkdocs-material,mysite=https://your-docs-site.com"
      },
      "disabled": false,
      "autoApprove": ["search_mkdocs-material", "get_mkdocs-material_page", "search_mysite", "get_mysite_page"]
    }
  }
}

Windows安装

对于Windows用户，MCP服务器配置格式略有不同：

{
  "mcpServers": {
    "mkdocs": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "mkdocs-mcp@latest",
        "mkdocs-mcp.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

环境变量

变量 描述 默认值
FASTMCP_LOG_LEVEL 日志记录级别（调试、信息、警告、错误、严重） 警告
MKDOCS_SITES 以逗号分隔的站点配置列表 key=url mkdocs材料=https://squidfunk.github.io/mkdocs-material

演出

大型文档网站：搜索索引非常大的网站使用异步加载，超时1.5秒：

  • 如果索引未就绪，第一次搜索将返回“正在加载”消息
  • LLM可以重试搜索（后台加载索引）
  • 加载后，索引将被缓存，搜索将立即进行

搜索功能

此MCP服务器提供基本搜索功能：

  • 短语匹配：优先考虑精确的短语匹配（相关性最高）
  • 单词匹配：当精确短语不匹配时，回退到匹配单个单词
  • 评分：结果按相关性排序（首先是精确匹配，然后是字数）

LLM解释搜索结果并提供有意义的答案，通过智能结果处理弥补了更简单的搜索算法。

企业网络支持

对于具有代理服务器的公司环境：

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "HTTP_PROXY": "http://proxy.company.com:8080"
  }
}

对于经过身份验证的代理：

{
  "env": {
    "HTTPS_PROXY": "http://username:password@proxy.company.com:8080"
  }
}

基本用法

示例查询：

  • “在MkDocs材料文档中搜索警告”
  • “如何在MkDocs材料中使用代码块？”
  • “MkDocs材质的自定义选项是什么？”

关于MkDocs材料

MkDocs材料 是基于MkDocs构建的强大文档框架。此MCP服务器适用于使用MkDocs Material构建的任何文档站点。

发展

来源

git clone https://github.com/ojacques/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e .
mkdocs-mcp

运行测试

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=mkdocs_mcp --cov-report=html

测试通过GitHub Actions在推送和拉取请求上自动运行。

出版

当在GitHub上创建新版本时，此包会自动发布到PyPI：

  1. 更新版本 pyproject.toml
  2. 在GitHub上创建一个带有标签的新版本（例如。， v0.1.0)
  3. GitHub Actions将自动构建并发布到PyPI

注意：需要为存储库配置PyPI可信发布。

许可证

麻省理工学院

相关 MCP