ShowDoc2MD

Преобразует проекты ShowDoc с известным паролем доступа в Markdown для использования с AI / Agent / RAG.

Поддерживаются три способа использования:

• MCP Server (рекомендуется): AI-клиенты, такие как Cursor, Codex, Claude, AgentDock, автоматически обнаруживают инструменты и вызывают их.

• CLI: ручной или скриптовый массовый экспорт в Markdown.

• Legacy HTTP API: сохранён совместимый интерфейс /convert.

ShowDoc2MD используется только для чтения документов, к которым у вас уже есть законный доступ и пароль. Он не угадывает, не взламывает и не перебирает пароли.

Зачем нужен этот проект

Защищённые паролем страницы ShowDoc обычно требуют, чтобы браузер сначала прошёл интерактивную проверку (капчу/пароль), что неудобно для автоматического чтения документов AI-агентом.

Read-only API ShowDoc позволяет передавать _item_pwd=<известный пароль документа> в запросе. ShowDoc2MD использует этот обычный параметр чтения для доступа к каталогу проекта и страницам, поэтому AI не нужно имитировать веб-капчу.

В настоящее время читаются:

• /api/item/info

• /api/page/info

Related MCP server: mkdocs-mcp

Установка

Требования: Python 3.10+.

Windows

powershell -ExecutionPolicy Bypass -File .\scripts\windows_install.ps1

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

MCP: рекомендуемый способ подключения AI

ShowDoc2MD использует официальный Python MCP SDK и поддерживает:

• stdio: подходит для AI-клиентов на той же машине.

• Streamable HTTP: подходит для развёртывания на фиксированной машине, к которой другие AI-клиенты подключаются по сети.

Инструменты, доступные AI

После подключения AI-клиент автоматически получает параметры и описания этих инструментов через MCP schema, поэтому не нужно дополнительно сообщать модели HTTP JSON-формат.

Способ 1: stdio на той же машине

Сначала установите ShowDoc2MD, затем настройте stdio server в MCP-клиенте. Пример общей конфигурации:

{
  "mcpServers": {
    "showdoc2md": {
      "command": "showdoc2md",
      "args": ["mcp", "--transport", "stdio"],
      "env": {
        "SHOWDOC_PASSWORD": "your-document-password"
      }
    }
  }
}

Если разные проекты ShowDoc используют разные пароли, можно не задавать SHOWDOC_PASSWORD, а передавать password при каждом вызове инструмента.

Способ 2: развёртывание Streamable HTTP на фиксированной машине

Только локальный доступ:

$env:SHOWDOC_PASSWORD='your-document-password'
.\showdoc2md.cmd mcp

Адрес MCP по умолчанию:

http://127.0.0.1:18765/mcp

Linux / macOS:

export SHOWDOC_PASSWORD='your-document-password'
showdoc2md mcp

AI-клиенту достаточно указать MCP URL:

http://127.0.0.1:18765/mcp

Локальная сеть / удалённая машина

MCP SDK по умолчанию включает защиту от DNS-rebinding. ShowDoc2MD также применяет безопасные значения по умолчанию для удалённого прослушивания:

• Необходимо явно указать разрешённые Host/IP.

• По умолчанию требуется установить SHOWDOC_MCP_TOKEN, клиент аутентифицируется через Bearer Token.

Пример сервера:

$env:SHOWDOC_MCP_TOKEN='replace-with-a-long-random-token'
.\showdoc2md.cmd mcp `
  --host 0.0.0.0 `
  --port 18765 `
  --allowed-host 192.168.1.20

Затем AI-клиент подключается:

http://192.168.1.20:18765/mcp

И для этого MCP-подключения настраивается HTTP Header:

Authorization: Bearer replace-with-a-long-random-token

Форматы MCP-конфигурации у разных AI-клиентов отличаются, но главное — поддержка пользовательских заголовков для Streamable HTTP.

Если доступ через домен:

showdoc2md mcp \
  --host 0.0.0.0 \
  --port 18765 \
  --allowed-host mcp.example.com

--allowed-host mcp.example.com также разрешает mcp.example.com:*.

Если браузерный MCP-клиент отправляет Origin, можно дополнительно добавить:

--allowed-origin https://app.example.com

Если MCP работает только в полностью доверенной частной сети/VPN и вы явно хотите отключить Bearer Token, можно добавить:

--allow-unauthenticated-remote

Предупреждение безопасности: не выставляйте MCP-сервис без аутентификации в публичный интернет. Статический Bearer Token подходит для личного/небольшого командного развёртывания; для публичного сервиса рекомендуется размещать его за TLS, VPN/Tailscale, аутентифицирующим обратным прокси или ресурсным сервером OAuth 2.1, соответствующим спецификации MCP.

Не путайте два разных пароля

• SHOWDOC_PASSWORD: пароль доступа к самому документу ShowDoc.

• SHOWDOC_MCP_TOKEN: Bearer Token, используемый AI-клиентом для подключения к MCP-серверу ShowDoc2MD.

Они имеют разное назначение и не выводятся инструментами MCP.

Docker

В репозитории есть Dockerfile и docker-compose.example.yml. Пример локального развёртывания:

export SHOWDOC_PASSWORD='your-document-password'
export SHOWDOC_MCP_TOKEN='replace-with-a-long-random-token'
docker compose -f docker-compose.example.yml up -d --build

По умолчанию порт пробрасывается только на 127.0.0.1:18765 хоста. Для доступа с других машин измените проброс портов и в параметрах запуска контейнера замените --allowed-host на фактический IP/домен сервера, к которому обращается AI.

Как AI должен использовать

Обычно не нужно писать специальные промпты — MCP Server содержит собственные инструкции. Рекомендуемый порядок вызовов:

1. Если не уверены в правах: showdoc_probe

2. Сначала посмотреть структуру: showdoc_list_pages

3. Если нужно немного контента: showdoc_read_page

4. Если нужен анализ всего проекта: showdoc_read_full

5. Если нужны файлы на диске: showdoc_export

Например, можно прямо сказать AI:

阅读这个 ShowDoc 并总结它的 API 认证方式：
https://www.showdoc.com.cn/100200/300400

Если пароль уже задан в переменной окружения SHOWDOC_PASSWORD на MCP-сервере, AI не нужно получать пароль.

CLI

Проверка доступности

$env:SHOWDOC_PASSWORD='your-document-password'
.\showdoc2md.cmd probe 'https://www.showdoc.com.cn/100200/300400'

Полный экспорт

.\showdoc2md.cmd export 'https://www.showdoc.com.cn/100200/300400' --output .\output

Можно также передать пароль напрямую:

showdoc2md export 'https://www.showdoc.com.cn/100200/300400' \
  --password 'your-document-password' \
  --output ./output

Рекомендуется использовать переменную окружения, чтобы пароль не попадал в историю shell.

Структура экспорта

output/
└── ProjectName_itemId/
    ├── 完整文档.md
    ├── manifest.json
    ├── assets/
    └── pages/
        ├── 0001_Overview.md
        └── API/
            └── 0002_CreateOrder.md

• Обычные страницы ShowDoc Markdown сохраняются по возможности без изменений.

• Страницы RunAPI/API JSON преобразуются в читаемый Markdown.

• Изображения на страницах по умолчанию загружаются в assets/ и ссылки переписываются.

• 完整文档.md объединяет страницы в порядке каталога.

• manifest.json записывает страницы, ошибки и статус complete.

Защита целостности

ShowDoc2MD не выдаёт «частичный успех» за полный:

• Если каталог проекта возвращает 0 страниц — сразу ошибка.

• Если любая страница или требуемый ресурс не загрузился — complete=false.

• CLI возвращает ненулевой код выхода при неполном экспорте.

• MCP / HTTP результаты явно возвращают статус целостности.

Legacy HTTP API

Если старая система использует /convert, можно продолжать:

.\showdoc2md.cmd serve --host 127.0.0.1 --port 18765

Интерфейс:

GET  /health
POST /convert

Для новых интеграций с AI рекомендуется использовать MCP, а не этот интерфейс.

Разработка и тестирование

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Тесты используют вымышленные URL, вымышленные проекты и Fake Client; они не содержат адресов ShowDoc, паролей документов или экспортированного контента владельца.

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

• В настоящее время приоритет отдаётся ShowDoc с «паролем доступа к проекту».

• Если экземпляр ShowDoc требует обязательного входа в аккаунт (например, force_login), одного пароля проекта может быть недостаточно.

• Изображения на страницах поддерживаются; отдельный список вложений ShowDoc пока не полностью покрыт как отдельная функция вложений.

License

MIT License. Подробнее см. LICENSE.