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으로 변환합니다. 작은 파일은 직접 출력하고, 큰 파일은 섹션 요약, 토큰 수, 실행 가능한 다음 단계가 포함된 문서 맵을 반환합니다 — 에이전트는 필요한 부분만 가져오면 됩니다.

왜 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 — 모든 옵션(모드, 섹션, grep, 예산 등)으로 문서를 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

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