{
  "markdown": "<p align=\"right\">\n  <a href=\"README_CN.md\">🇨🇳 中文</a>\n</p>\n\n# shuck-file\n\n[![PyPI](https://img.shields.io/pypi/v/shuck-file)](https://pypi.org/project/shuck-file/)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-available-blue)](https://registry.modelcontextprotocol.io/servers/io.github.Shan-Zhu%2Fshuck-file)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> Any file in, Markdown out — read only what matters.\n\n**shuck-file** converts documents to clean Markdown for AI agents and LLMs. Small files output directly; large files return a **document map** with section summaries, token counts, and actionable next steps — so agents only pull what they need.\n\n## Why shuck-file?\n\nAI agents need a bridge that's **context-aware**:\n\n- **Small file** → `shuck report.docx` → full Markdown on stdout\n- **Large file** → `shuck report.docx` → document map with sections and extraction options\n- **Targeted extraction** → `shuck report.docx --sections s1,s3` → only what you need\n- **Search** → `shuck report.docx --grep \"revenue\"` → find without reading everything\n\n## Supported Formats\n\n| Format | Extension | Library | What's Preserved |\n|--------|-----------|---------|-----------------|\n| Word | `.docx` | python-docx | Headings, bold/italic, lists, tables |\n| PDF | `.pdf` | pdfplumber | Text content, page breaks |\n| Excel | `.xlsx` | openpyxl | All sheets as Markdown tables |\n| PowerPoint | `.pptx` | python-pptx | Titles, text, tables, speaker notes |\n| CSV | `.csv` | stdlib | All rows/columns as a table |\n\n## Installation\n\n### Via pip (recommended)\n\n```bash\npip install shuck-file\n```\n\nThis installs the `shuck` CLI command and the MCP server.\n\n### From source\n\n```bash\ngit clone https://github.com/Shan-Zhu/shuck-file.git\ncd shuck-file\npip install -e .\n```\n\n## Quick Start\n\n```bash\n# Convert a document\nshuck report.docx\n\n# Force full output (bypass map mode)\nshuck large-report.pdf --all\n\n# Search within a document\nshuck report.pdf --grep \"revenue\"\n```\n\n## Usage\n\n### Auto-Routing (default)\n\nSmall files output directly, large files return a document map.\n\n```bash\n# Small file → direct Markdown output\nshuck document.pdf\n\n# Large file → document map with sections table + next steps\nshuck large-report.pdf\n```\n\n### Extraction Options\n\n```bash\n# Force full output (bypass map mode)\nshuck report.pdf --all\n\n# Extract specific sections\nshuck report.pdf --sections s1,s3\n\n# Tables only\nshuck report.pdf --tables-only\n\n# Search within document\nshuck report.pdf --grep \"revenue\"\n\n# Token budget (smart compression)\nshuck report.pdf --budget 4000\n\n# Combinations work\nshuck report.pdf --sections s2,s3 --budget 2000\n```\n\n### Excel/CSV Specific\n\n```bash\n# Column headers and types\nshuck data.xlsx --schema-only\n\n# Headers + first N rows\nshuck data.xlsx --sample 5\n```\n\n### Power User Subcommands\n\n```bash\n# Force map mode (even on small files)\nshuck probe document.docx\n\n# Force full extraction (alias for --all)\nshuck pull document.docx\n```\n\n### Output Control\n\n```bash\n# Write to file\nshuck document.pdf -o output.md\n\n# Write to directory (auto-named)\nshuck document.pdf -d ./converted/\n\n# Skip YAML frontmatter\nshuck document.pdf --no-frontmatter\n\n# List supported formats\nshuck --formats\n```\n\n### Map Mode Output\n\nWhen a file is large, shuck returns a document map:\n\n```markdown\n# Document Map: quarterly-report.pdf\n\n**6 pages | ~12,400 tokens | 6 sections**\n\n## Sections\n\n| # | Title | Type | Tokens | Density |\n|---|-------|------|--------|---------|\n| s1 | Executive Summary | narrative | 450 | high |\n| s2 | Q3 Financial Results | mixed | 2,800 | high |\n| s3 | Revenue Breakdown | tabular | 3,200 | high |\n| ...\n\n## Next Steps\n\n- `shuck quarterly-report.pdf --all` -- full document (~12,400 tokens)\n- `shuck quarterly-report.pdf --sections s1,s2` -- high-density (~3,250 tokens)\n- `shuck quarterly-report.pdf --grep \"...\"` -- search for keywords\n```\n\n## MCP Server\n\nshuck-file includes an MCP (Model Context Protocol) server, making it available to any MCP-compatible AI tool.\n\n### Claude Code\n\n```bash\nclaude mcp add shuck-file -- shuck-file\n```\n\nOr add to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shuck-file\": {\n      \"command\": \"shuck-file\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shuck-file\": {\n      \"command\": \"shuck-file\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"shuck-file\": {\n      \"command\": \"shuck-file\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Any MCP Client\n\nshuck-file registers as an MCP server via the `mcp.servers` entry point. Tools exposed:\n\n- **`shuck`** — Convert a document to Markdown with all options (mode, sections, grep, budget, etc.)\n- **`list_formats`** — List supported document formats\n\n### Claude Code Plugin\n\nInstall as a Claude Code plugin for the `/shuck` skill:\n\n```bash\nclaude plugin add /path/to/shuck-file\n```\n\n## Architecture\n\n```\nsrc/shuck_file/\n├── cli.py                # CLI entrypoint\n├── server.py             # MCP Server (FastMCP)\n├── core/\n│   ├── router.py          # Auto-routing logic\n│   ├── segmenter.py       # Document segmentation\n│   ├── mapper.py          # Map mode renderer\n│   ├── budget.py          # Smart compression\n│   ├── grep.py            # In-document search\n│   ├── frontmatter.py     # YAML frontmatter\n│   └── models.py          # Data models\n├── extractors/\n│   ├── base.py            # Base extractor ABC\n│   ├── docx_ext.py        # Word extractor\n│   ├── pdf_ext.py         # PDF extractor\n│   ├── xlsx_ext.py        # Excel extractor\n│   ├── pptx_ext.py        # PowerPoint extractor\n│   └── csv_ext.py         # CSV extractor\nplugin/                    # Claude Code plugin wrapper\ntests/\n├── test_extractors.py\n├── test_router.py\n├── test_segmenter.py\n├── test_budget.py\n└── test_grep.py\n```\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.Shan-Zhu/shuck-file -->\n",
  "bytes": 5957,
  "sha": "d98edc2f1e3dce4741b3a7bbec5d6e563c2a3589e6fded9a87ac8e7c23acd4fc",
  "repo_slug": "shan-zhu/shuck-file",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shan_zhu_shuck_file_2b9a7d12/readme"
}