papermoon-mkdocs-mcp

Легковесный MCP-сервер для сайтов документации MkDocs. Читает markdown-файлы напрямую с диска, обеспечивает полнотекстовый и опциональный семантический поиск, а также предоставляет структуру проекта через Model Context Protocol.

Возможности

• 5 MCP-инструментов — search, read_document, list_documents, get_project_info, get_document_outline

• Ключевой поиск SQLite FTS5 с ранжированием BM25 (без внешних зависимостей)

• Опциональный семантический векторный поиск через sentence-transformers

• Гибридный поиск — комбинация ключевого и векторного поиска с Reciprocal Rank Fusion

• Инкрементальная индексация — быстрое обновление при изменении файлов

• Постоянный SQLite-индекс, переживающий перезапуски сервера

• Учёт навигации — парсит mkdocs.yml и .nav.yml

• Исключаемые документы — черновики и внутренние страницы можно скрыть из MCP

• Безопасность в приоритете — защита от path traversal, read-only соединения для поиска

• Минимум зависимостей — 3 обязательных, 2 опциональных

Related MCP server: mdbook-mcp-server

Установка

pip install papermoon-mkdocs-mcp

Чтобы включить векторный поиск:

pip install papermoon-mkdocs-mcp[vector]

Быстрый старт

Запустите из корня любого MkDocs-проекта (где находится mkdocs.yml):

cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp

Или укажите конкретный файл конфигурации:

papermoon-mkdocs-mcp --config /path/to/mkdocs.yml

Сервер автоматически определяет mkdocs.yml в текущем каталоге, если --config не указан.

Варианты транспорта

По умолчанию сервер использует транспорт stdio. Вы можете переключиться на сетевой транспорт для удалённых или много-клиентских сценариев:

# Streamable HTTP (recommended for network access)
papermoon-mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (legacy client compatibility)
papermoon-mkdocs-mcp --transport sse --port 8080

Примечание по безопасности: При привязке к не-loopback адресу размещайте сервер за обратным прокси (например, nginx, Caddy), который завершает TLS.

Конфигурация MCP-клиента

Claude Desktop

Добавьте в файл конфигурации Claude Desktop:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Примечание: Если Claude Desktop не может найти команду (Failed to spawn process: No such file or directory), используйте полный путь к исполняемому файлу вместо просто mkdocs-mcp:

{
  "mcpServers": {
    "mkdocs": {
      "command": "/path/to/.venv/bin/mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Это часто случается, когда пакет установлен в виртуальное окружение, чей каталог bin/ не входит в PATH Claude Desktop.

Claude Code / VS Code

Добавьте в .mcp.json в корне вашего проекта:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Доступные инструменты

search

Поиск по документации с использованием ключевого, семантического или гибридного поиска.

Возвращает ранжированные результаты с путём, заголовком, оценкой релевантности (нормализованной 0.0–1.0) и фрагментом текста.

read_document

Чтение файла документации по его относительному пути.

Возвращает тело markdown (без frontmatter), разобранный frontmatter как отдельное поле, структуру заголовков и метаданные файла.

list_documents

Список всех файлов документации, опционально отфильтрованных по разделу.

Возвращает метаданные документов (путь, заголовок, описание, категории, размер, время изменения).

get_project_info

Получение метаданных MkDocs-проекта. Не принимает параметров.

Возвращает название сайта, URL сайта, каталог docs, тему, дерево навигации, количество документов и статус индекса.

get_document_outline

Получение структуры заголовков (оглавления) для документа.

Возвращает заголовок документа и список заголовков с уровнем, текстом и якорем.

Исключение документов

Некоторые markdown-файлы не стоит показывать через MCP — черновики, внутренние руководства, сгенерированные временные файлы. Добавьте список mcp_exclude в mkdocs.yml:

site_name: My Docs

mcp_exclude:
  - drafts/             # any directory named 'drafts', at any depth
  - internal/**         # anchored: only 'internal/' at the docs root
  - "*-scratch.md"      # by filename suffix, at any depth
  - "!internal/public.md"  # re-include one file from a broader rule

Исключения применяются сразу везде. Исключённый документ отсутствует в дереве навигации, никогда не попадает в поисковый индекс, не появляется в list_documents и отклоняется в read_document и get_document_outline — отказ идентичен ответу для несуществующего файла, поэтому не раскрывает наличие документа.

mcp_exclude влияет только на этот MCP-сервер. Он не меняет то, что публикует mkdocs build.

Синтаксис шаблонов

Шаблоны в стиле gitignore и сопоставляются с путём документа относительно docs_dir.

• Шаблон, содержащий /, привязан к docs_dir; без него — соответствует на любой глубине.

• Завершающий / ограничивает шаблон каталогами, поэтому drafts/ не скрывает файл с именем drafts.md.

• Правила оцениваются по порядку, и последнее совпавшее решает, поэтому помещайте !-повторные включения после правила, которое они вырезают.

• Пустые строки и комментарии # игнорируются.

Вновь исключённые файлы удаляются из индекса при следующем запуске, а удаление шаблона возвращает их — нет необходимости удалять .mkdocs-mcp.db.

Архитектура

src/mkdocs_mcp/
  config.py      -- MkDocs config detection and nav parsing
  exclusions.py  -- mcp_exclude pattern matching
  repository.py  -- SQLite schema and CRUD operations
  indexer.py     -- Index orchestration with incremental updates
  searcher.py    -- Keyword, vector, and hybrid search
  server.py      -- FastMCP server with 5 tool definitions
  utils.py       -- Path validation, frontmatter parsing, text extraction
  models.py      -- Pydantic response models

При запуске сервер читает mkdocs.yml, сканирует каталог docs и строит (или инкрементально обновляет) индекс SQLite FTS5. Поисковые запросы обращаются к индексу напрямую; векторный поиск преобразует запрос с помощью all-MiniLM-L6-v2 и сравнивает с сохранёнными эмбеддингами документов. Гибридный режим объединяет оба списка результатов с помощью Reciprocal Rank Fusion.

Разработка

git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest

Линтинг и проверка типов:

ruff check .
mypy src/

Требования

• Python >= 3.10

• Обязательные: fastmcp (>=3.0, <4), pydantic (>=2.0, <3), pyyaml (>=6.0), markdown (>=3.4)

• Опциональные (векторный поиск): sentence-transformers (>=3.0), numpy (>=1.24)

Лицензия

См. LICENSE для подробностей.