Feishu 클라우드 문서 추출 도구 (Feishu Reader)

이 프로그램은 Python과 PyQt6로 작성된 데스크톱 애플리케이션으로, 사용자가 Feishu 문서(Docx / Wiki)를 빠르게 추출하여 로컬에 Markdown 형식으로 저장할 수 있도록 돕습니다.

🌟 주요 기능

그래픽 사용자 인터페이스: 간결하고 사용하기 쉬운 PyQt6 데스크톱 인터페이스를 제공합니다.
원클릭 추출: Feishu 문서/지식 베이스 링크를 붙여넣어 .md 형식의 파일로 즉시 변환합니다.
포괄적인 형식 지원: 텍스트, 다단계 제목, 코드 블록, 목록, 인용문, 표, Mermaid 차트 등 일반적인 Feishu 문서 요소를 지원합니다.
이미지 로컬화: 문서 내 이미지를 로컬 assets_<doc_token>/ 디렉토리에 자동으로 다운로드하고, Markdown 내에 상대 경로 참조를 생성합니다.
권한 및 인증:
- 인터페이스에서 Feishu 앱의 App ID와 App Secret을 직접 입력하여 Access Token을 즉시 획득할 수 있습니다.
- 수동으로 Token을 입력할 수 있으며, "기억하기"를 체크하여 자격 증명을 로컬에 저장할 수 있습니다.
로컬 저장: 타임스탬프가 포함된 파일명을 자동으로 생성하여 사용자가 지정한 디렉토리에 저장합니다.

🔑 Feishu 앱 설정

이 도구는 Feishu 오픈 플랫폼의 **자체 구축 앱(Self-built App)**을 통해 문서에 액세스하므로, 처음 사용 시 다음 설정을 완료해야 합니다.

1단계: 자체 구축 앱 생성

Feishu 오픈 플랫폼에 접속하여 관리자 계정으로 로그인합니다.
개발자 백엔드로 이동 → 오른쪽 상단의 앱 생성 클릭 → 자체 구축 앱을 선택합니다.
앱 이름(예: "문서 추출 도구"), 설명, 아이콘을 업로드한 후 확인을 클릭하여 생성합니다.
앱 상세 페이지의 자격 증명 및 기본 정보 탭에서 다음을 복사합니다:
- App ID (예: cli_xxxxxxxxxxxxxxxx)
- App Secret ("보기" 클릭 후 복사)

2단계: 필요한 권한 활성화

앱 상세 페이지 → 권한 관리 → 다음 권한을 검색하여 활성화합니다:

권한 식별자	권한 이름	용도 설명
`wiki:wiki:readonly`	지식 공간 정보 가져오기	`/wiki/` 유형의 지식 베이스 문서 액세스
`docx:document:readonly`	새 버전 문서 보기	Feishu Docx 형식 문서의 Block 내용 읽기
`docs:document.media:download`	클라우드 문서 내 이미지 및 첨부파일 다운로드	문서 내 이미지를 로컬로 다운로드
`docs:document.content:read`	클라우드 문서 내용 보기	액세스 범위 내의 문서 내용 가져오기
`docx:document:readonly`	새 버전 문서 보기	새 버전 문서 내용 가져오기

주의: 권한 활성화 후 버전 관리 및 게시 탭으로 이동하여 버전을 생성하고 게시해야 권한이 공식적으로 적용됩니다.

3단계: 앱에 문서 공유

Feishu 문서는 기본적으로 권한이 있는 사용자에게만 보이므로, 대상 문서(또는 지식 베이스)를 앱 봇에 공유해야 합니다:

대상 Feishu 문서를 열고 오른쪽 상단의 공유를 클릭합니다.
공유 팝업창에서 앱 이름을 검색하고 권한을 보기 가능으로 설정합니다.
확인을 클릭하면 앱이 해당 문서에 액세스할 수 있습니다.

지식 베이스(Wiki) 문서인 경우, 지식 베이스의 멤버 관리에서 앱 봇을 추가하고 보기 권한을 부여해야 합니다.

🛠️ 설치 및 실행

환경 요구 사항

Python 3.10 이상

의존성 설치

pip install -r requirements.txt

데스크톱 앱 실행

python main.py

🔌 MCP 서버 모드

MCP 서버로 실행을 지원하여 Claude, Cursor 등 AI 도구에서 직접 호출할 수 있습니다.

환경 변수 설정

export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"

MCP 서버 실행

python mcp_server.py

Claude / Cursor에 구성

~/.claude.json 또는 프로젝트 MCP 구성에 다음을 추가합니다:

{
  "mcpServers": {
    "feishu-reader": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      },
      "workingDirectory": "/path/to/feishu-reader-mcp"
    }
  }
}

📖 사용 가이드

자격 증명 입력: 인터페이스 상단에 Feishu 자체 구축 앱의 App ID와 App Secret을 입력합니다(최초 사용 후 자동 저장).
Token 획득: Access Token 행 오른쪽의 [새로고침] 버튼을 클릭하여 Token을 자동으로 가져오고 채웁니다. 기존 Token을 수동으로 붙여넣을 수도 있습니다.
문서 링크 붙여넣기: Feishu 문서 또는 지식 베이스 페이지 링크를 "문서 URL" 입력창에 붙여넣습니다(/docx/, /doc/, /wiki/ 유형 링크 지원).
추출 시작: [추출 시작]을 클릭하고 팝업창에서 Markdown 파일을 저장할 디렉토리를 선택합니다.
완료 대기: 하단 로그 영역에 실시간 진행 상황이 표시되며, 완료 후 대상 디렉토리에서 .md 파일과 assets_xxx/ 이미지 디렉토리를 확인할 수 있습니다.

📄 프로젝트 구조

파일	설명
`main.py`	메인 프로그램 진입점, PyQt6 인터페이스 정의 및 비동기 작업 스레드 로직 포함
`fetcher.py`	Feishu OpenAPI 상호작용 계층, Block 트리 가져오기 및 이미지 다운로드 담당
`parser.py`	Markdown 변환 엔진, Feishu의 다양한 Block을 Markdown 문법으로 매핑
`mcp_server.py`	MCP 서버 모드 진입점
`requirements.txt`	Python 의존성 목록

💡 주의사항

이 도구는 Feishu 새 버전 문서 형식(/docx/v1/documents OpenAPI 기반)에 최적화되어 있으며, 구버전 문서는 형식이 다를 수 있습니다.
이미지 다운로드를 위해서는 앱에 docs:document.media:download 권한이 부여되어야 하며, 문서가 앱 봇에 올바르게 공유되어야 합니다. 그렇지 않으면 이미지 다운로드는 건너뛰며 로그에 실패 원인이 표시됩니다.
인터페이스 호출에는 빈도 제한(5 QPS / 일일 10,000회)이 있으므로, 대용량 문서를 너무 자주 반복해서 추출하지 마십시오.
Token의 기본 유효 기간은 약 2시간이며, 만료 시 [새로고침]을 클릭하여 다시 획득하십시오.

feishu-reader