Format Converter MCP

범용 포맷 변환 MCP Server

오디오, 비디오, 이미지, Office, 데이터, 전자책, PDF, 자막 등 전 포맷 변환을 지원하는 Model Context Protocol (MCP) 서버로, TimeVerse Studio, Claude Desktop, Cursor, VS Code 등 모든 MCP 클라이언트에서 호출할 수 있습니다.

English

✨ 특징

Related MCP server: ChangeThisFile MCP Server

📦 지원 포맷

* 표시는 제한 포맷(PAGES / WPS / NUMBERS / KEY)으로, macOS 네이티브 앱 또는 iCloud 내보내기가 필요합니다.

중복 제거 후 총 약 71개 포맷으로, 업계 공통 변환 요구의 95%+를 커버합니다.

⚠️ 알려진 제한 사항

• 제한 포맷: PAGES / WPS / NUMBERS / KEY는 macOS 네이티브 앱 또는 iCloud 내보내기가 필요하며, 다른 플랫폼에서는 일반적으로 직접 변환할 수 없습니다.

• HEIC/HEIF 디코딩: ImageMagick의 libheif 지원에 의존합니다. 없으면 Apple 고효율 이미지를 디코딩할 수 없습니다.

• 엔진 기본 다운그레이드: LaTeX 미설치 시 Markdown→PDF는 weasyprint로 다운그레이드됩니다. Calibre 미설치 시 MOBI/AZW3 전자책을 사용할 수 없습니다. ImageMagick 미설치 시 이미지 변환은 Python Pillow(기능 제한적)로 대체됩니다.

• Protocol Buffers: PB로 변환하려면 추가 .proto 정의 파일이 필요합니다.

• Parquet / Protobuf: 해당 Python 의존성(pyarrow, protobuf)은 선택 사항으로, 수동 설치가 필요합니다.

🧰 도구 목록

핵심 변환 도구(10개)

보조 도구(4개)

모든 변환 도구는 input_path + output_format + options 매개변수 패턴을 공통으로 따릅니다.

🏗️ 아키텍처

┌─────────────────────────────────────────────────────┐
│              MCP Client (LLM)                        │
│        Claude / Cursor / VS Code / ...               │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC (stdio)
┌──────────────────────┴──────────────────────────────┐
│           MCP Protocol Layer                         │
│      tool list · tool call · notifications           │
├──────────────────────────────────────────────────────┤
│           Tool Router Layer                          │
│    请求解析 → 格式识别 → 路由分发 → 结果封装           │
├───────────┬───────────┬──────────┬───────────────────┤
│  Format   │ Conversion│  File    │  Dependency       │
│  Registry │  Planner  │ Manager  │  Checker          │
├───────────┴───────────┴──────────┴───────────────────┤
│           Conversion Engine Layer                    │
│  FFmpeg · ImageMagick · LibreOffice · Pandoc         │
│  Python · PDF                                         │
└──────────────────────────────────────────────────────┘

스마트 경로 계획 예시:

⚙️ 기술 스택

• 주 언어: TypeScript (Node.js ≥ 18)

• 프로토콜: @modelcontextprotocol/sdk

• 변환 엔진: FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (venv 격리) / PyMuPDF

시스템 의존성

LaTeX(선택, Markdown→PDF 고품질)와 Calibre(선택, MOBI/AZW3)는 없어도 되며, 시스템이 자동으로 다운그레이드합니다.

Python 의존성

pip install -r python/requirements.txt

핵심 의존성: openpyxl, pandas, PyYAML, tomlkit, xmltodict, PyMuPDF, pypdf, pdf2docx, pysubs2, Pillow(pyarrow, protobuf는 선택 사항).

🚀 설치

먼저 시스템 의존성(FFmpeg / ImageMagick / LibreOffice / Pandoc)을 설치합니다:

• Windows: npm run prepare-deps(휴대용 버전 원클릭 다운로드)

• macOS: brew install ffmpeg imagemagick pandoc && brew install --cask libreoffice

• Linux: apt install ffmpeg imagemagick libreoffice pandoc

그런 다음 빌드하고 Python 의존성을 설치합니다:

# 1. 安装 Node 依赖
npm install

# 2. 构建（生成 dist/）
npm run build

# 3. 安装 Python 依赖（建议使用虚拟环境）
python3 -m venv .venv        # macOS/Linux；Windows 使用 python
source .venv/bin/activate    # macOS/Linux；Windows 使用 .venv\Scripts\activate
pip install -r python/requirements.txt

🔌 MCP 구성

MCP 클라이언트의 mcpServers 구성에 다음 서버를 추가하면 됩니다.

TimeVerse Studio(권장 · npm 호스팅)

TimeVerse Studio는 표준 mcpServers JSON으로 연동합니다. npm에 배포한 후 npx로 원클릭 실행이 가능하며, 로컬 빌드가 필요 없습니다:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "npx",
      "args": ["-y", "timeverse-omni-converter-mcp"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

Claude Desktop / Cursor(로컬 빌드)

로컬 빌드 후 node로 직접 실행합니다:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "node",
      "args": ["C:/path/to/timeverse-omni-converter-mcp/dist/index.js"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

macOS: args를 /Users/<you>/timeverse-omni-converter-mcp/dist/index.js로 변경하고, FC_PYTHON_PATH를 python3로 변경합니다(또는 해당 항목을 삭제하여 .venv/python3 자동 감지 사용).

🔧 환경 변수

💬 사용 예시

MCP 클라이언트의 LLM에 자연어 명령을 전달합니다. 예:

• 「a.mov를 a.mp4로 변환, 해상도 1920x1080」→ convert_media

• 「photo.heic를 photo.png로 변환」→ convert_image

• 「report.docx를 report.pdf로 변환」→ convert_document

• 「data.json을 data.csv로 변환」→ convert_data

• 「slides.pptx의 각 페이지를 PNG로 내보내기」→ convert_presentation

• 「book.epub을 book.mobi로 변환」→ convert_ebook

• 「a.pdf와 b.pdf 병합」→ convert_pdf(operation: "merge")

• 「subs.ass를 subs.srt로 변환」→ convert_subtitle

도구 호출 예시:

{
  "name": "convert_media",
  "arguments": {
    "input_path": "C:/media/input.mov",
    "output_format": "mp4",
    "options": {
      "video_codec": "libx264",
      "video_resolution": "1920x1080",
      "crf": 23
    }
  }
}

반환 결과:

{
  "success": true,
  "outputPath": "C:/media/input.mp4",
  "outputSize": 10485760,
  "duration": 3215,
  "warnings": []
}

❓ 자주 묻는 질문

Q: 변환 시 의존성 누락 또는 실패가 발생하면 어떻게 하나요? A: check_dependencies 도구를 호출하여 각 엔진(FFmpeg / ImageMagick / LibreOffice / Pandoc / Python)의 가용 상태와 버전을 확인하고, 누락된 의존성을 설치한 후 다시 시도하세요.

Q: Python 관련 변환(데이터 / PDF / 스프레드시트 / 자막)에서 오류가 발생하나요? A: pip install -r python/requirements.txt로 의존성을 설치했는지 확인하고, FC_PYTHON_PATH가 올바른 Python 인터프리터를 가리키는지 확인하세요(또는 가상 환경 활성화).

Q: 대상 파일이 이미 존재하면 어떻게 되나요? A: 기본적으로 파일명_1.확장자로 자동 이름 변경됩니다. 일괄 변환 시 on_conflict 매개변수로 overwrite / skip / rename을 제어할 수 있습니다.

Q: 일부 포맷(예: PAGES / NUMBERS)은 왜 변환할 수 없나요? A: 이는 Apple 독점 포맷으로, macOS 네이티브 앱 또는 iCloud 내보내기가 필요하며 제한 포맷에 해당합니다. 자세한 내용은 「알려진 제한 사항」을 참조하세요.

Q: 대용량 파일 변환 시 타임아웃이 발생하면 어떻게 하나요? A: FC_TIMEOUT(기본 300000ms)을 늘리고, FC_MAX_FILE_SIZE(기본 500MB) 상한에 주의하세요.

🛡️ 보안

Server는 신뢰할 수 없는 파일 콘텐츠를 처리하므로, 여러 리소스 및 보안 보호 기능이 내장되어 있습니다:

• 입력 파일 크기, 압축 해제 후 용량, 압축 비율, 이미지 픽셀 상한(zip bomb / 압축 해제 폭탄 방지)

• 단일 변환 타임아웃 및 동시성 상한

• 파서의 XXE(외부 엔티티 주입), PDF 임베디드 스크립트, 외부 리소스 로드 비활성화

• 외부 프로세스는 매개변수 배열 호출(execFile)을 통일적으로 사용하여 명령 주입 방지

📄 License

MIT