PDFCompress

PDFCompress는 인간과 AI 에이전트를 위한, PDF 구조를 보존하는 오픈소스 압축기입니다. 독립적으로 검증된 WPS 스타일 이미지 프리셋을 사용하지만, WPS DLL을 호출하거나 배포하지 않으며 WPS 계정에 의존하지 않습니다.

핵심 규칙은 간단합니다:

텍스트와 벡터는 텍스트와 벡터로 유지하고, 크기가 과도하게 표현된 이미지만 다운샘플링한 뒤, 결과를 게시 전에 검증합니다.

기능

• 실제 PDF 변환 행렬에서 이미지 해상도를 계산합니다. Form XObject에 중첩된 이미지도 포함합니다.

• WPS 호환 high, standard, medium, low 설정을 적용합니다.

• 입찰·낙찰, 보존, 입찰 자료 및 공공 보관용 첨부를 위한 archive-safe 프로필을 추가합니다.

• 원본 파일을 보존하고 다른 출력 경로에 원자적으로(원자적으로) 씁니다.

• 기본적으로 책갈피, 첨부 파일, 주석, 글꼴 및 표시되는 PDF 구조를 보존합니다.

• 서명 무효화를 명시적으로 승인하지 않는 한 서명된 PDF를 거부합니다.

• 각 후보마다 페이지 수, 페이지 박스, 추출 가능한 텍스트를 검증합니다.

• 이전 JPEG 결과를 반복적으로 재압축하지 않고 목표 크기를 지원합니다.

• Python API, CLI, 공유 Agent Skill, Codex 플러그인, Claude Code 플러그인 및 MCP 서버를 제공합니다.

Related MCP server: MokuPDF

설치

Python 3.11 이상이 필요합니다.

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

uv 사용 시:

uv tool install --editable ".[mcp]"

클론 없이 태그된 GitHub 릴리스를 설치하려면:

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

빠른 시작

압축 전에 분석하기:

pdfcompress analyze "input.pdf" --json

WPS 호환 고품질 프로필로 압축:

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

4MB 미만이어야 하는 공식 첨부 파일의 경우:

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

기존 입력/출력 쌍 검증:

pdfcompress verify "input.pdf" "output.pdf" --json

프리셋

네 가지 WPS 호환 값은 설치된 압축 플러그인의 generateCompressArgs 분기에서 복구되었으며, 동반 분석 문서에 독립적으로 기록되었습니다. 정확한 WPS 리샘플링 커널, 크로마 서브색 추출 정책 및 완전한 옵티마이저 비트마스크는 복사되거나 주장되지 않습니다.

목표 크기 동작

--target-size-mb가 지정되면 PDFCompress는 요청된 프리셋에서 시작하여 점점 더 강력한 프로필을 시도합니다. 모든 시도는 원본 PDF를 다시 엽니다:

archive-safe → high → standard → medium → low

제한값 미만의 첫 번째 검증된 후보가 선택됩니다. 어떤 프로필도 한도를 미만 달성하지 못하면, 가장 작은 검증 후보가 경고와 함께 반환됩니다. PDFCompress는 목표를 맞추기 위해 페이지를 조용히 래스터화하거나, 글꼴을 삭제하거나, 첨부 파일을 제거하지 않습니다.

에이전트 통합

Claude Code

먼저 Python 패키지를 설치한 다음 세션에 플러그인을 로드합니다:

cd PDFCompress
claude --plugin-dir .

/pdfcompress:pdf-compress 스킬로 호출하거나, Claude에게 PDF 압축을 요청하십시오. Claude Code는 플러그인의 .mcp.json도 로드하여 stdio로 pdfcompress-mcp를 시작합니다.

Codex

저장소에는 검증된 .codex-plugin/plugin.json, 공유 skills/ 디렉토리 및 .mcp.json이 포함되어 있습니다. 로컬 Codex 마켓플레이스에서 설치하거나, 스킬을 개인/프로젝트 스킬 디렉토리로 복사할 수 있습니다. pdfcompress-mcp가 PATH에 있도록 코어 패키지를 설치해야 합니다.

일반 MCP 클라이언트

이 stdio 구성을 사용하십시오:

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

MCP 도구:

• analyze_pdf(path, password?)

• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)

• verify_pdf(input_path, output_path)

오픈소스 연구 및 채택한 아이디어

라이선스 경계는 THIRD_PARTY_NOTICES.md를 참조하십시오.

안전 및 제한 사항

• PDF를 다시 쓰면 디지털 서명이 무효화됩니다. 기본적으로는 중지합니다.

• 암호화된 PDF는 암호가 필요합니다. 암호화는 출력에서도 유지됩니다.

• 버전 0.1은 시각적 손상을 피하기 위해 이미지 마스크, 투명도, 사용자 지정 디코드 배열, 비정형 색 공간 및 8비트 이외 이미지를 건너뜁니다.

• 텍스트 동등성 검사는 추출 가능한 텍스트를 사용합니다. OCR이 없는 스캔 페이지는 여전히 육안 QA가 필요합니다.

• 법적으로 중요한 문서 또는 매우 복잡한 문서에 도구를 쓰기 전에 픽셀 단위 렌더 비교를 권장합니다.

• 만약 후보가 소스보다 더 크지 않으면, PDFCompress는 바이트 단위의 소스 복사본을 출력하고 안전한 크기 축소가 없음을 보고합니다.

검증된 예

12페이지짜리 이미지가 많은 개발용 PDF에서:

100 DPI 렌더링 비교에서 모든 페이지 크기가 일치했습니다. archive-safe 결과는 페이지당 평균 RGB RMS 차이 0.388, 0–255 채널 스케일에서 최대 3.002였습니다. 이는 하나의 검증 사례일 뿐, 보편적인 품질 보장은 아닙니다.

개발

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

테스트는 검색 가능한 텍스트와 해상도 이미지가 포함된 자체 PDF를 생성합니다. 저장소에는 사설 문서가 포함되어 있지 않습니다.

라이선스

PDFCompress는 MIT License에 따라 배포됩니다. 타사 종속성은 그들의 라이선스를 그대로 유지합니다.

버전 변경 사항과 다운로드 가능한 Python 패키지는 변경 기록 과 GitHub releases 를 참조하십시오.