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オープンプラットフォームの自作アプリを通じてドキュメントにアクセスします。初回使用時には以下の設定が必要です。

ステップ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 / 1日10,000回）があるため、大規模なドキュメントを頻繁に繰り返し抽出しないでください。
Tokenのデフォルト有効期限は約2時間です。期限切れになった場合は【更新】をクリックして再取得してください。

feishu-reader