shuck-file

🇨🇳 中国語

shuck-file

どんなファイルも入力するだけで、Markdown を出力します。必要な情報だけを読み取ります。

shuck-file は、ドキュメントを AI エージェントや LLM 向けの整った Markdown に変換します。小さなファイルはそのまま出力し、大きなファイルの場合は、セクションの概要、トークン数、実行可能な次のステップを含むドキュメントマップを返します。これにより、エージェントは必要な情報だけを取得できます。

shuck-file を選ぶ理由

AI エージェントには、コンテキストを認識する橋渡し役が必要です。

• 小さなファイル → shuck report.docx → Markdown 全体を標準出力に出力
• 大きなファイル → shuck report.docx → セクションと抽出オプションを含むドキュメントマップ
• 対象を絞った抽出 → shuck report.docx --sections s1,s3 → 必要な情報だけを抽出
• 検索 → shuck report.docx --grep "revenue" → すべてを読まずに検索

対応フォーマット

フォーマット	拡張子	ライブラリ	保持される内容
Word	.docx	python-docx	見出し、太字／斜体、リスト、表
PDF	.pdf	pdfplumber	テキストコンテンツ、ページ区切り
Excel	.xlsx	openpyxl	すべてのシートを Markdown の表として出力
PowerPoint	.pptx	python-pptx	タイトル、テキスト、表、発表者ノート
CSV	.csv	stdlib	すべての行／列を表として出力

インストール

pip 経由（推奨）

pip install shuck-file

これにより、shuck CLI コマンドと MCP サーバーがインストールされます。

ソースからインストール

git clone https://github.com/Shan-Zhu/shuck-file.git
cd shuck-file
pip install -e .

クイックスタート

# Convert a document
shuck report.docx

# Force full output (bypass map mode)
shuck large-report.pdf --all

# Search within a document
shuck report.pdf --grep "revenue"

使い方

自動ルーティング（デフォルト）

小さなファイルはそのまま出力し、大きなファイルの場合はドキュメントマップを返します。

# Small file → direct Markdown output
shuck document.pdf

# Large file → document map with sections table + next steps
shuck large-report.pdf

抽出オプション

# Force full output (bypass map mode)
shuck report.pdf --all

# Extract specific sections
shuck report.pdf --sections s1,s3

# Tables only
shuck report.pdf --tables-only

# Search within document
shuck report.pdf --grep "revenue"

# Token budget (smart compression)
shuck report.pdf --budget 4000

# Combinations work
shuck report.pdf --sections s2,s3 --budget 2000

Excel／CSV 固有の設定

# Column headers and types
shuck data.xlsx --schema-only

# Headers + first N rows
shuck data.xlsx --sample 5

上級者向けサブコマンド

# Force map mode (even on small files)
shuck probe document.docx

# Force full extraction (alias for --all)
shuck pull document.docx

出力の制御

# Write to file
shuck document.pdf -o output.md

# Write to directory (auto-named)
shuck document.pdf -d ./converted/

# Skip YAML frontmatter
shuck document.pdf --no-frontmatter

# List supported formats
shuck --formats

マップモードの出力

ファイルが大きい場合、shuck はドキュメントマップを返します。

# Document Map: quarterly-report.pdf

**6 pages | ~12,400 tokens | 6 sections**

## Sections

| # | Title | Type | Tokens | Density |
|---|-------|------|--------|---------|
| s1 | Executive Summary | narrative | 450 | high |
| s2 | Q3 Financial Results | mixed | 2,800 | high |
| s3 | Revenue Breakdown | tabular | 3,200 | high |
| ...

## Next Steps

- `shuck quarterly-report.pdf --all` -- full document (~12,400 tokens)
- `shuck quarterly-report.pdf --sections s1,s2` -- high-density (~3,250 tokens)
- `shuck quarterly-report.pdf --grep "..."` -- search for keywords

MCP サーバー

shuck-file には MCP（Model Context Protocol）サーバーが含まれており、MCP 対応の AI ツールから利用できます。

Claude Code

claude mcp add shuck-file -- shuck-file

または、プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

Cursor

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

Windsurf

MCP 設定に追加します。

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

任意の MCP クライアント

shuck-file は、mcp.servers エントリーポイントを介して MCP サーバーとして登録されます。公開されるツールは次のとおりです。

• shuck — すべてのオプション（mode、sections、grep、budget など）を指定して、ドキュメントを Markdown に変換します
• list_formats — 対応するドキュメント形式を一覧表示します

Claude Code プラグイン

/shuck スキルを使う Claude Code プラグインとしてインストールします。

claude plugin add /path/to/shuck-file

アーキテクチャ

src/shuck_file/
├── cli.py                # CLI entrypoint
├── server.py             # MCP Server (FastMCP)
├── core/
│   ├── router.py          # Auto-routing logic
│   ├── segmenter.py       # Document segmentation
│   ├── mapper.py          # Map mode renderer
│   ├── budget.py          # Smart compression
│   ├── grep.py            # In-document search
│   ├── frontmatter.py     # YAML frontmatter
│   └── models.py          # Data models
├── extractors/
│   ├── base.py            # Base extractor ABC
│   ├── docx_ext.py        # Word extractor
│   ├── pdf_ext.py         # PDF extractor
│   ├── xlsx_ext.py        # Excel extractor
│   ├── pptx_ext.py        # PowerPoint extractor
│   └── csv_ext.py         # CSV extractor
plugin/                    # Claude Code plugin wrapper
tests/
├── test_extractors.py
├── test_router.py
├── test_segmenter.py
├── test_budget.py
└── test_grep.py

ライセンス

MIT