ShowDoc2MD

Lee proyectos de ShowDoc con contraseña de acceso conocida y los convierte a Markdown para su uso con IA / Agent / RAG.

Admite tres formas de uso:

• MCP Server (recomendado): clientes de IA como Cursor, Codex, Claude, AgentDock, etc., descubren las herramientas automáticamente y las invocan.

• CLI: exportación manual o mediante scripts de Markdown por lotes.

• Legacy HTTP API: se conserva la interfaz compatible /convert.

ShowDoc2MD solo se usa para leer documentos a los que ya tienes acceso y contraseña de forma legítima. No adivina, descifra ni fuerza contraseñas por fuerza bruta.

Por qué se creó este proyecto

Las páginas de ShowDoc protegidas por contraseña normalmente exigen que el navegador complete primero la interacción de captcha/contraseña, lo que resulta muy incómodo para que un agente de IA lea documentos automáticamente.

La interfaz de solo lectura de ShowDoc permite que las peticiones incluyan _item_pwd=<contraseña de documento conocida>. ShowDoc2MD accede al directorio y a las páginas del proyecto mediante este parámetro de lectura normal, por lo que la IA no necesita simular el flujo de captcha de una página web.

Actualmente lee principalmente:

• /api/item/info

• /api/page/info

Related MCP server: mkdocs-mcp

Instalación

Requisitos: 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: la forma recomendada de integrar IA

ShowDoc2MD usa el SDK oficial de MCP para Python y admite:

• stdio: adecuado para clientes de IA en la misma máquina.

• Streamable HTTP: adecuado para desplegar en una máquina fija, mientras que otros clientes de IA se conectan a través de la red.

Herramientas expuestas a la IA

Al conectarse, el cliente de IA obtiene automáticamente los parámetros y la descripción de estas herramientas a través del esquema MCP, sin necesidad de indicar al modelo el formato JSON HTTP.

Opción 1: stdio en la misma máquina

Primero instala ShowDoc2MD y luego configura un servidor stdio en el cliente MCP. Ejemplo de configuración genérica:

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

Si distintos proyectos de ShowDoc usan contraseñas diferentes, puedes omitir SHOWDOC_PASSWORD y dejar que la IA pase password en cada invocación de herramienta.

Opción 2: desplegar Streamable HTTP en una máquina fija

Solo acceso local:

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

Dirección MCP por defecto:

http://127.0.0.1:18765/mcp

Linux / macOS:

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

El cliente de IA solo necesita configurar la URL MCP:

http://127.0.0.1:18765/mcp

Red local / máquina remota

El SDK de MCP activa por defecto la protección contra DNS-rebinding. ShowDoc2MD también aplica valores seguros por defecto para la escucha remota:

• Debe declararse explícitamente el Host/IP permitido.

• Por defecto es obligatorio establecer SHOWDOC_MCP_TOKEN; el cliente se autentica mediante Bearer Token.

Ejemplo de servidor:

$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

Luego el cliente de IA se conecta:

http://192.168.1.20:18765/mcp

Y configura el encabezado HTTP para esta conexión MCP:

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

El formato del archivo de configuración MCP varía según el cliente de IA, pero basta con que admita encabezados personalizados en Streamable HTTP.

Si se accede mediante un dominio:

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

--allowed-host mcp.example.com también permite mcp.example.com:*.

Si el cliente MCP de tipo navegador envía Origin, se puede añadir además:

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

Si MCP solo se ejecuta en una red privada/VPN de total confianza y se desea explícitamente desactivar el Bearer Token, se puede añadir de forma explícita:

--allow-unauthenticated-remote

Aviso de seguridad: no expongas un servicio MCP sin autenticación directamente a Internet. Un Bearer Token estático es adecuado para despliegues personales o de equipos pequeños; para un servicio público formal se recomienda colocarlo detrás de TLS, VPN/Tailscale, un proxy inverso con autenticación o un servidor de recursos conforme a OAuth 2.1 según la especificación MCP.

No confundas las dos contraseñas distintas

• SHOWDOC_PASSWORD: la contraseña de acceso del propio documento ShowDoc.

• SHOWDOC_MCP_TOKEN: el Bearer Token que usa el cliente de IA para conectarse al servidor MCP de ShowDoc2MD.

Tienen usos distintos y ninguna de las dos es devuelta por las herramientas MCP.

Docker

El repositorio incluye Dockerfile y docker-compose.example.yml. Ejemplo de despliegue local:

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

Por defecto el puerto solo se mapea a 127.0.0.1:18765 del host. Si necesitas acceder desde otras máquinas, modifica también el mapeo de puertos y cambia --allowed-host en los argumentos de arranque del contenedor por la IP/dominio del servidor al que la IA accede realmente.

Cómo debería usarlo la IA

Normalmente no se necesitan indicaciones especiales: el servidor MCP incluye sus propias instrucciones. Orden de llamada recomendado:

1. Si no estás seguro de los permisos: showdoc_probe

2. Primero mira la estructura: showdoc_list_pages

3. Si solo necesitas poco contenido: showdoc_read_page

4. Si necesitas analizar todo el proyecto: showdoc_read_full

5. Si necesitas archivos en disco: showdoc_export

Por ejemplo, puedes decirle directamente a la IA:

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

Si la contraseña ya está configurada en la variable de entorno SHOWDOC_PASSWORD del servidor MCP, la IA no necesita volver a obtenerla.

CLI

Comprobar si es accesible

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

Exportación completa

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

También se puede pasar la contraseña directamente:

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

Se recomienda la variable de entorno para evitar que la contraseña quede en el historial del shell.

Estructura de exportación

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

• Las páginas Markdown normales de ShowDoc se guardan en la medida de lo posible tal cual.

• Las páginas RunAPI/API JSON se convierten a Markdown legible.

• Las imágenes de las páginas se descargan por defecto a assets/ y se reescriben los enlaces.

• 完整文档.md combina las páginas en el orden del directorio.

• manifest.json registra las páginas, los elementos fallidos y el estado complete.

Protección de integridad

ShowDoc2MD no presenta un "éxito parcial" como un éxito completo:

• Si el directorio del proyecto devuelve 0 páginas, se produce un error directamente.

• Si falla cualquier página o recurso que deba descargarse, complete=false.

• El CLI devuelve un código de salida distinto de 0 cuando la exportación está incompleta.

• Los resultados MCP / HTTP devuelven explícitamente el estado de integridad.

Legacy HTTP API

Si ya existe un sistema antiguo que usa /convert, puede seguir funcionando:

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

Interfaz:

GET  /health
POST /convert

Para nuevas integraciones de IA se recomienda usar directamente MCP en lugar de esta interfaz.

Desarrollo y pruebas

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

Las pruebas usan URLs ficticias, proyectos ficticios y un Fake Client; no incluyen la dirección de ShowDoc, contraseñas de documentos ni contenido exportado del mantenedor.

Límites actuales

• Actualmente se prioriza el tipo de ShowDoc con "contraseña de acceso al proyecto".

• Si una instancia de ShowDoc exige inicio de sesión con cuenta (por ejemplo, force_login), es posible que solo la contraseña del proyecto no sea suficiente.

• La descarga de imágenes dentro de las páginas ya está soportada; la lista de adjuntos independiente de ShowDoc aún no está cubierta por completo como función de adjuntos separada.

Licencia

Licencia MIT. Consulta LICENSE para más detalles.