shuck-file

io.github.Shan-ZhuPublished by GitHub account Shan-Zhuv2.0.4Updated Oct 24, 2026

Any file in, Markdown out — read only what matters.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Converts local documents such as Word, PDF, Excel, PowerPoint and CSV files into clean Markdown, returning a section map for large files.

What you can do
shuck-file exposes two MCP tools: shuck, which converts a document to Markdown with options for full output, specific sections, tables only, keyword search, token budget and output paths, and list_formats, which lists supported formats. Small files are returned in full, while large files produce a document map with section titles, token counts and suggested next steps so an assistant can pull only the parts it needs. Supported inputs are .docx, .pdf, .xlsx, .pptx and .csv.
When to use it
Useful when an assistant needs to read or search local office documents and spreadsheets without loading whole files into context. It fits workflows where large reports or workbooks should be summarised, searched by keyword, or partially extracted.
Requirements
Runs as a local process over stdio. Install the shuck-file Python package with pip, which provides the shuck CLI and the MCP server; a Python environment is required. No accounts, API keys, environment variables or headers are declared.
Before you install
It reads files from the local machine, so the assistant can access any document path it is given; point it only at files you are willing to expose. Output can be written to files or directories via the -o and -d options, which creates or overwrites files on disk.

Installation

In SourceWeft

  1. Open shuck-file in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

🇨🇳 中文

shuck-file

[PyPI] [MCP Registry] [License: MIT]

Any file in, Markdown out — read only what matters.

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.

Why shuck-file?

AI agents need a bridge that's context-aware:

  • Small file → shuck report.docx → full Markdown on stdout
  • Large file → shuck report.docx → document map with sections and extraction options
  • Targeted extraction → shuck report.docx --sections s1,s3 → only what you need
  • Search → shuck report.docx --grep "revenue" → find without reading everything

Supported Formats

FormatExtensionLibraryWhat's Preserved
Word.docxpython-docxHeadings, bold/italic, lists, tables
PDF.pdfpdfplumberText content, page breaks
Excel.xlsxopenpyxlAll sheets as Markdown tables
PowerPoint.pptxpython-pptxTitles, text, tables, speaker notes
CSV.csvstdlibAll rows/columns as a table

Installation

Via pip (recommended)

bash
pip install shuck-file

This installs the shuck CLI command and the MCP server.

From source

bash
git clone https://github.com/Shan-Zhu/shuck-file.gitcd shuck-filepip install -e .

Quick Start

bash
# Convert a documentshuck report.docx
# Force full output (bypass map mode)shuck large-report.pdf --all
# Search within a documentshuck report.pdf --grep "revenue"

Usage

Auto-Routing (default)

Small files output directly, large files return a document map.

bash
# Small file → direct Markdown outputshuck document.pdf
# Large file → document map with sections table + next stepsshuck large-report.pdf

Extraction Options

bash
# Force full output (bypass map mode)shuck report.pdf --all
# Extract specific sectionsshuck report.pdf --sections s1,s3
# Tables onlyshuck report.pdf --tables-only
# Search within documentshuck report.pdf --grep "revenue"
# Token budget (smart compression)shuck report.pdf --budget 4000
# Combinations workshuck report.pdf --sections s2,s3 --budget 2000

Excel/CSV Specific

bash
# Column headers and typesshuck data.xlsx --schema-only
# Headers + first N rowsshuck data.xlsx --sample 5

Power User Subcommands

bash
# Force map mode (even on small files)shuck probe document.docx
# Force full extraction (alias for --all)shuck pull document.docx

Output Control

bash
# Write to fileshuck document.pdf -o output.md
# Write to directory (auto-named)shuck document.pdf -d ./converted/
# Skip YAML frontmattershuck document.pdf --no-frontmatter
# List supported formatsshuck --formats

Map Mode Output

When a file is large, shuck returns a document map:

markdown
# 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 Server

shuck-file includes an MCP (Model Context Protocol) server, making it available to any MCP-compatible AI tool.

Claude Code

bash
claude mcp add shuck-file -- shuck-file

Or add to your project's .mcp.json:

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

Cursor

Add to ~/.cursor/mcp.json:

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

Windsurf

Add to your MCP configuration:

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

Any MCP Client

shuck-file registers as an MCP server via the mcp.servers entry point. Tools exposed:

  • shuck — Convert a document to Markdown with all options (mode, sections, grep, budget, etc.)
  • list_formats — List supported document formats

Claude Code Plugin

Install as a Claude Code plugin for the /shuck skill:

bash
claude plugin add /path/to/shuck-file

Architecture

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 extractorplugin/                    # Claude Code plugin wrappertests/├── test_extractors.py├── test_router.py├── test_segmenter.py├── test_budget.py└── test_grep.py

License

MIT

Source: README.md at commit 05a7d31

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.0.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts