ShowDoc2MD

アクセスパスワードが既知の ShowDoc プロジェクトを読み取り、Markdown に変換して、AI / Agent / RAG で利用できるようにします。

次の3つの利用方法をサポートしています：

• MCP Server（推奨）：Cursor、Codex、Claude、AgentDock などの AI クライアントがツールを自動検出して呼び出します。

• CLI：手動またはスクリプトで Markdown を一括エクスポートします。

• Legacy HTTP API：/convert 互換インターフェースを保持します。

ShowDoc2MD は、あなたが合法的にアクセス権限とパスワードを取得したドキュメントの読み取りにのみ使用されます。パスワードの推測、クラッキング、ブルートフォース攻撃は行いません。

このプロジェクトを作った理由

パスワードで保護された ShowDoc ページでは、通常ブラウザでキャプチャ/パスワードの操作を先に完了する必要があり、AI Agent がドキュメントを自動的に読むには非常に不便です。

ShowDoc の読み取り専用インターフェースでは、リクエストに _item_pwd=<既知のドキュメントパスワード> を含めることができます。ShowDoc2MD はこの通常の読み取りパラメータを使用してプロジェクトディレクトリとページにアクセスするため、AI が Web のキャプチャフローをシミュレートする必要はありません。

現在主に読み取るもの：

• /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 スキーマを通じてこれらのツールのパラメータと説明を自動的に取得するため、モデルに HTTP JSON 形式を別途教える必要はありません。

方法1：同一マシン上の stdio

まず ShowDoc2MD をインストールし、MCP クライアントで stdio サーバーを設定します。一般的な設定例：

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

ShowDoc プロジェクトごとに異なるパスワードを使用する場合は、SHOWDOC_PASSWORD を設定せず、AI がツール呼び出しのたびに 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 リバインディング保護を有効にしています。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 ヘッダーを設定します：

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

AI クライアントごとに MCP 設定ファイルの形式は異なりますが、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、認証付きリバースプロキシ、または MCP 仕様に準拠した OAuth 2.1 リソースサーバーの背後に配置することを推奨します。

2つの異なるパスワードを混同しない

• SHOWDOC_PASSWORD：ShowDoc ドキュメント自体のアクセスパスワード。

• SHOWDOC_MCP_TOKEN：AI クライアントが ShowDoc2MD MCP Server に接続する際に使用する Bearer Token。

これらは用途が異なり、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 を AI が実際にアクセスするサーバーの IP/ドメイン名に変更してください。

AI の使用方法

通常、特別なプロンプトを書く必要はありません。MCP Server には instructions が組み込まれています。推奨される呼び出し順序：

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

パスワードが MCP サーバーの SHOWDOC_PASSWORD 環境変数に設定されている場合、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

パスワードがシェル履歴に入らないように、環境変数方式を推奨します。

エクスポート構造

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 はエクスポートが不完全な場合、非 0 の終了コードを返します。

• 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 を参照してください。