Skip to main content
Glama
deenesjakoruzh
Shan-Zhu

shuck-file

by Shan-Zhu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

shuck-file

PyPI MCP Registry License: MIT

Jede Datei rein, Markdown raus — lies nur, was wichtig ist.

shuck-file konvertiert Dokumente in sauberes Markdown für KI-Agenten und LLMs. Kleine Dateien werden direkt ausgegeben; große Dateien liefern eine Dokumentkarte mit Abschnittszusammenfassungen, Token-Anzahlen und umsetzbaren nächsten Schritten — so ziehen Agenten nur, was sie brauchen.

Warum shuck-file?

KI-Agenten brauchen eine Brücke, die kontextbewusst ist:

  • Kleine Datei → shuck report.docx → vollständiges Markdown auf stdout

  • Große Datei → shuck report.docx → Dokumentkarte mit Abschnitten und Extraktionsoptionen

  • Gezielte Extraktion → shuck report.docx --sections s1,s3 → nur was du brauchst

  • Suche → shuck report.docx --grep "revenue" → finden, ohne alles zu lesen

Related MCP server: document-parser

Unterstützte Formate

Format

Erweiterung

Bibliothek

Was erhalten bleibt

Word

.docx

python-docx

Überschriften, fett/kursiv, Listen, Tabellen

PDF

.pdf

pdfplumber

Textinhalt, Seitenumbrüche

Excel

.xlsx

openpyxl

Alle Blätter als Markdown-Tabellen

PowerPoint

.pptx

python-pptx

Titel, Text, Tabellen, Sprechernotizen

CSV

.csv

stdlib

Alle Zeilen/Spalten als Tabelle

Installation

Über pip (empfohlen)

pip install shuck-file

Dies installiert den shuck-CLI-Befehl und den MCP-Server.

Aus dem Quellcode

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

Schnellstart

# 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"

Verwendung

Automatisches Routing (Standard)

Kleine Dateien werden direkt ausgegeben, große Dateien liefern eine Dokumentkarte.

# Small file → direct Markdown output
shuck document.pdf

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

Extraktionsoptionen

# 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-spezifisch

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

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

Subbefehle für Power-User

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

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

Ausgabesteuerung

# 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

Ausgabe im Kartenmodus

Wenn eine Datei groß ist, liefert shuck eine Dokumentkarte:

# 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 enthält einen MCP-Server (Model Context Protocol), der es jedem MCP-kompatiblen KI-Tool zur Verfügung stellt.

Claude Code

claude mcp add shuck-file -- shuck-file

Oder fügen Sie es zur .mcp.json Ihres Projekts hinzu:

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

Cursor

Fügen Sie zu ~/.cursor/mcp.json hinzu:

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

Windsurf

Fügen Sie zu Ihrer MCP-Konfiguration hinzu:

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

Beliebiger MCP-Client

shuck-file registriert sich als MCP-Server über den Einstiegspunkt mcp.servers. Verfügbare Tools:

  • shuck — Konvertiert ein Dokument in Markdown mit allen Optionen (Modus, Abschnitte, grep, Budget usw.)

  • list_formats — Listet unterstützte Dokumentformate auf

Claude Code Plugin

Installieren Sie als Claude-Code-Plugin für den /shuck-Skill:

claude plugin add /path/to/shuck-file

Architektur

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

Lizenz

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MinerU Document Explorer by opendatalab

    MinerU Document Explorerofficial

    opendatalab
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to search, deep-read, and build knowledge bases from Markdown, PDF, DOCX, and PPTX documents via MCP tools for retrieval, document navigation, and ingestion.
    12 npm
    638
    MIT

  • document-parser

    agenson-tools
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI agents with comprehensive document parsing capabilities including PDF text extraction, OCR, HTML-to-markdown conversion, table extraction, and summarization, optimized for agent workflows.
    63 npm
    MIT
  • groupdocs-markdown-mcp by groupdocs-markdown

    groupdocs-markdown-mcpofficial

    groupdocs-markdown
    A
    license
    Not graded
    quality
    A
    maintenance
    Converts documents (PDF, DOCX, XLSX, EPUB, etc.) to clean, structured Markdown, and retrieves document info, for use with AI agents.
    MIT