docs2mcp

Превратите каталог файлов Markdown, HTML или TXT в удаленный MCP-сервер только для чтения, к которому любой совместимый MCP-клиент или агент может подключиться для получения документации. Сюда входят AskMesh, интеграции с Claude, Codex и пользовательские MCP-клиенты.

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

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx создает изолированное окружение из PyPI и запускает опубликованный CLI docs2mcp без ручного шага установки. Для локальной разработки из рабочей копии вместо этого используйте python -m docs2mcp.runtime.

Включите инкрементальную синхронизацию с отслеживанием файлов и периодической сверкой:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

Первый запуск сканирует весь каталог. Последующие изменения применяются по каждому документу: новые файлы добавляются, измененные файлы переиндексируются, удаленные файлы убираются, а неизмененные пропускаются. Наблюдатель использует короткое окно антидребезга, а периодическое сканирование служит запасным вариантом для файловых систем, которые ненадежно генерируют события.

При привязке к конкретному публичному адресу с включенной защитой от DNS-rebinding явно разрешите входящий заголовок Host:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

Используйте тот же интерпретатор Python для установки и запуска. docs2mcp требует официальный MCP Python SDK mcp>=1.27.0,<2; более старая или не связанная с ним библиотека с именем mcp не предоставляет mcp.server.fastmcp.

Устаревшая команда doc2mcp остается доступной как псевдоним для совместимости.

Процесс выводит конфигурацию MCP-подключения при запуске. Аутентификация необязательна: передайте --token, чтобы включить Bearer-аутентификацию, или опустите его для запуска без аутентификации.

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

Введите значения endpoint, режима аутентификации, search_docs и get_document в конфигурации вашего MCP-клиента. Если auth_type равен none, выберите отсутствие аутентификации и оставьте токен пустым. Клиенты, поддерживающие Streamable HTTP, могут подключаться к тому же endpoint без специального адаптера для AskMesh.

GET /readyz возвращает количество документов и последние счетчики синхронизации: добавлено, обновлено, удалено, пропущено, ошибок, длительность и последняя ошибка.

Related MCP server: Synapse

Поддерживаемые форматы

MVP поддерживает .md, .markdown, .txt, .html и .htm. Для индексации используется SQLite FTS5, поэтому отдельная векторная база данных не требуется.

MCP-контракт

Сервер реализует интероперабельный контракт документов agent-qa.docs/v1 и предоставляет два инструмента только для чтения:

• search_docs(query, limit): возвращает route, title, url, snippet и score.

• get_document(route, max_characters): возвращает содержимое документа, разделы и URL для цитирования.

search_docs.query использует синтаксис SQLite FTS5. Пробел означает запрос AND, OR соответствует любому из терминов, текст в кавычках ищет точную фразу, NOT исключает термин, а * включает префиксное соответствие. Это не семантический поиск на естественном языке; клиенты должны показывать этот синтаксис пользователям.

Подключение из любого MCP-клиента

Используйте endpoint Streamable HTTP и названия двух инструментов в любом клиенте, поддерживающем удаленные MCP-подключения. AskMesh — одна из поддерживаемых интеграций; клиенты на основе Claude, Codex и пользовательские агенты могут использовать тот же endpoint и контракт только для чтения.

Текущие ограничения

Этот выпуск — однохостовый MVP: документы импортируются из локального каталога, а индекс хранится в SQLite. Синхронизация с Git, разбор PDF, объектное хранилище, векторный поиск и мультитенантная плоскость управления запланированы на последующие выпуски.