ShowDoc2MD

접근 비밀번호를 알고 있는 ShowDoc 프로젝트를 읽어 Markdown으로 변환하여 AI / Agent / RAG에서 사용할 수 있게 합니다.

세 가지 사용 방식을 지원합니다:

• MCP Server(권장): Cursor, Codex, Claude, AgentDock 등 AI 클라이언트가 도구를 자동으로 발견하고 호출합니다.

• CLI: 수동 또는 스크립트로 Markdown을 일괄 내보냅니다.

• Legacy HTTP API: /convert 호환 인터페이스를 유지합니다.

ShowDoc2MD는 법적으로 접근 권한과 비밀번호를 획득한 문서만 읽는 용도로 사용됩니다. 비밀번호를 추측, 크래킹 또는 무차별 대입하지 않습니다.

이 프로젝트를 만든 이유

비밀번호로 보호된 ShowDoc 페이지는 일반적으로 브라우저에서 먼저 캡차/비밀번호 상호작용을 완료해야 하므로, AI Agent가 문서를 자동으로 읽기에 매우 불편합니다.

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 스키마를 통해 이 도구들의 파라미터와 설명을 자동으로 얻으므로, 모델에 HTTP JSON 형식을 별도로 알려줄 필요가 없습니다.

방법 1: 동일 머신 stdio

먼저 ShowDoc2MD를 설치한 다음, MCP 클라이언트에서 stdio server를 구성합니다. 공통 구성 예시:

{
  "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

LAN / 원격 머신

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

AI 클라이언트마다 MCP 구성 파일 형식이 다르지만, Streamable HTTP 커스텀 headers를 지원하기만 하면 됩니다.

도메인으로 접근하는 경우:

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 리소스 서버 뒤에 배치하는 것을 권장합니다.

서로 다른 두 비밀번호를 혼동하지 마세요

• 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

비밀번호가 shell history에 남지 않도록 환경 변수 방식을 권장합니다.

내보내기 구조

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를 참조하십시오.