ShowDoc2MD

Read ShowDoc projects with known access passwords and convert them to Markdown for use with AI / Agent / RAG.

Three usage modes are supported:

• MCP Server (recommended): AI clients such as Cursor, Codex, Claude, and AgentDock automatically discover the tools and call them.

• CLI: Manually or via scripts, batch-export Markdown.

• Legacy HTTP API: Keeps the /convert compatibility endpoint.

ShowDoc2MD only reads documents for which you already have legitimate access and the password. It does not guess, crack, or brute-force passwords.

Why this project exists

Password-protected ShowDoc pages usually require the browser to complete a captcha/password interaction first, which is very inconvenient for AI agents that need to read documentation automatically.

ShowDoc's read-only API allows requests to carry _item_pwd=<known document password>. ShowDoc2MD accesses the project directory and pages through this normal read parameter, so the AI does not need to simulate a web captcha flow.

Currently it reads:

• /api/item/info

• /api/page/info

Related MCP server: mkdocs-mcp

Installation

Requirements: 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: the recommended way to connect AI

ShowDoc2MD uses the official Python MCP SDK and supports:

• stdio: suitable for AI clients on the same machine.

• Streamable HTTP: suitable for deployment on a fixed machine, with other AI clients connecting over the network.

Tools exposed to AI

Once connected, AI clients automatically get the parameters and descriptions of these tools through the MCP schema, so there is no need to tell the model the HTTP JSON format separately.

Option 1: stdio on the same machine

First install ShowDoc2MD, then configure a stdio server in the MCP client. A generic configuration example:

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

If different ShowDoc projects use different passwords, you can leave SHOWDOC_PASSWORD unset and let the AI pass password on each tool call.

Option 2: deploy Streamable HTTP on a fixed machine

Local access only:

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

Default MCP address:

http://127.0.0.1:18765/mcp

Linux / macOS:

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

The AI client only needs to configure the MCP URL:

http://127.0.0.1:18765/mcp

LAN / remote machines

The MCP SDK enables DNS-rebinding protection by default. ShowDoc2MD also enables secure defaults for remote listening:

• Allowed Hosts/IPs must be explicitly declared.

• SHOWDOC_MCP_TOKEN must be set by default, and clients authenticate via Bearer Token.

Server example:

$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

Then the AI client connects:

http://192.168.1.20:18765/mcp

And configure the HTTP Header for this MCP connection:

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

Different AI clients have different MCP configuration file formats, but as long as it supports custom headers for Streamable HTTP, it works.

If accessing via a domain name:

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

--allowed-host mcp.example.com also allows mcp.example.com:*.

If a browser-based MCP client sends an Origin, you can additionally add:

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

If the MCP runs only on a private network/VPN you fully trust, and you explicitly want to disable the Bearer Token, you can add:

--allow-unauthenticated-remote

Security note: Do not expose an unauthenticated MCP service directly to the public internet. A static Bearer Token is suitable for personal/small-team deployments; for a production public service, we recommend placing it behind TLS, a VPN/Tailscale, an authenticated reverse proxy, or an OAuth 2.1 resource server that complies with the MCP specification.

Don't confuse the two different passwords

• SHOWDOC_PASSWORD: the access password for the ShowDoc document itself.

• SHOWDOC_MCP_TOKEN: the Bearer Token used by AI clients to connect to the ShowDoc2MD MCP Server.

They serve different purposes, and neither is echoed back by the MCP tools.

Docker

The repository includes a Dockerfile and docker-compose.example.yml. A local deployment example:

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

By default, the port is only mapped to the host's 127.0.0.1:18765. To access it from other machines, also change the port mapping and change --allowed-host in the container startup arguments to the server IP/domain that the AI actually accesses.

How AI should use it

Usually no special prompt is needed; the MCP Server comes with its own instructions. Recommended call order:

1. When permissions are uncertain: showdoc_probe

2. Look at the structure first: showdoc_list_pages

3. Only need a small amount of content: showdoc_read_page

4. Need full-project analysis: showdoc_read_full

5. Need files written to disk: showdoc_export

For example, you can simply tell the AI:

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

If the password is already configured in the MCP server's SHOWDOC_PASSWORD environment variable, the AI does not need to obtain the password.

CLI

Check whether it is accessible

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

Full export

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

You can also pass the password directly:

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

The environment variable approach is recommended to keep the password out of shell history.

Export structure

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

• Ordinary ShowDoc Markdown pages are saved as-is where possible.

• RunAPI/API JSON pages are converted to readable Markdown.

• Images in pages are downloaded to assets/ by default and links are rewritten.

• 完整文档.md merges pages in directory order.

• manifest.json records pages, failures, and the complete status.

Completeness protection

ShowDoc2MD does not disguise "partial success" as full success:

• It errors out directly when the project directory returns 0 pages.

• If any page or required asset fails to download, complete=false.

• The CLI returns a non-zero exit code when the export is incomplete.

• MCP / HTTP results explicitly return the completeness status.

Legacy HTTP API

If an existing legacy system uses /convert, you can keep it running:

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

Endpoint:

GET  /health
POST /convert

For new AI integrations, we recommend using MCP directly instead of this endpoint.

Development and testing

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

Tests use fictional URLs, fictional projects, and a Fake Client, and do not include the maintainer's own ShowDoc addresses, document passwords, or exported content.

Current limitations

• Currently prioritizes ShowDoc instances with "project access password" protection.

• If a ShowDoc instance enforces account login (e.g., force_login), a project password alone may not be sufficient.

• Images in pages are supported for download; ShowDoc's separate attachment list is not yet fully covered as a standalone attachment feature.

License

MIT License. See LICENSE for details.