Skip to main content
Glama
deenesjakoruzh
Shan-Zhu

shuck-file

by Shan-Zhu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

shuck-file

PyPI MCP Registry License: MIT

任意文件输入，Markdown 输出——只读取关键的内容。

shuck-file 将文档转换为适合 AI 智能体和 LLM 使用的简洁 Markdown。小文件直接输出；大文件返回一份文档地图，包含章节摘要、token 计数和可操作的后续步骤——这样智能体只需拉取自己需要的部分。

为什么选择 shuck-file？

AI 智能体需要一个上下文感知的桥梁：

  • 小文件 → shuck report.docx → 在 stdout 上输出完整 Markdown

  • 大文件 → shuck report.docx → 返回带章节和提取选项的文档地图

  • 定向提取 → shuck report.docx --sections s1,s3 → 只提取你需要的内容

  • 搜索 → shuck report.docx --grep "revenue" → 无需读取全部内容即可查找

Related MCP server: document-parser

支持的格式

格式

扩展名

库

保留内容

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 插件

作为 Claude Code 插件安装，以获得 /shuck 技能：

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

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