de en es ja ko ru zh

ShowDoc2MD

Name: ShowDoc2MD
Author: ishare2121

by ishare2121

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

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

Tool	Назначение
`showdoc_probe`	Проверка доступности адреса ShowDoc и пароля
`showdoc_list_pages`	Получение всего каталога проекта без чтения содержимого
`showdoc_read_page`	Чтение одной страницы и возврат в Markdown
`showdoc_read_full`	Чтение всего проекта и объединение в Markdown
`showdoc_export`	Экспорт файлов Markdown и ресурсов на машине MCP-сервера

После подключения 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 содержит собственные инструкции. Рекомендуемый порядок вызовов:

Если не уверены в правах: showdoc_probe
Сначала посмотреть структуру: showdoc_list_pages
Если нужно немного контента: showdoc_read_page
Если нужен анализ всего проекта: showdoc_read_full
Если нужны файлы на диске: 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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Related MCP Connectors

stagenth · 文档生成 A
com.stagenth
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
File Systems Workplace & Productivity
3
https://stagenth.com/mcp/doc-gen/
PDF to MD
io.github.liuyan-wjy
Convert PDF documents to Markdown for AI agents through an authenticated remote MCP server.
Documentation Access RAG Systems
1
https://pdf-to-md.app/mcp
mkdshare.DEV A
io.github.PhilipAnd
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Content Management Systems Documentation Access Developer Tools
112
https://mkdshare.dev/mcp
remnus AOAuth
io.github.Ranork
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Note Taking Project Management Workplace & Productivity
12373
https://www.remnus.com/api/mcp

Related MCP Servers

MinerU MCP Server
Documentation Access Multimedia Processing App Automation
Tongzhao9417
A
license
A
quality
D
maintenance
Exposes the MinerU document-to-markdown API as MCP tools for converting PDF, Word, PPT, and images into Markdown. It supports both local and remote file processing with integrated OCR capabilities for multiple languages.
Updated 7 months ago (2026-03-19 09:20 UTC)
2
24 PyPI
10
MIT
mkdocs-mcp
Documentation Access Search
ubaumann
A
license
Not graded
quality
C
maintenance
Enables interaction with MkDocs documentation through the MCP protocol, allowing AI assistants to read, search, and retrieve documentation content from MkDocs projects.
Updated a year ago (2025-09-20 19:10 UTC)
9
MIT
yuque
Documentation Access Content Management Systems
andy8663
A
license
B
quality
D
maintenance
Enables reading Yuque documents, listing knowledge base docs, and converting source content to Markdown via MCP. Supports session cookie authentication and optional Playwright rendering.
Updated 4 months ago (2026-06-18 11:45 UTC)
3
1
MIT
feishu-mcp-server
Documentation Access Content Management Systems Workplace & Productivity
Xdong320
A
license
A
quality
D
maintenance
Enables reading Feishu documents and Wiki pages, including full content and metadata, via MCP protocol.
Updated 7 months ago (2026-03-20 03:33 UTC)
2
21 npm
ISC

ShowDoc2MD

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

Установка

Windows

macOS / Linux

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

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

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

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

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

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

Docker

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

CLI

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

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

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

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

Legacy HTTP API

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

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

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MinerU MCP Server

mkdocs-mcp

yuque

feishu-mcp-server