AI 에이전트는 변환할 파일과 변환할 형식을 선택하고, 변환 엔진이 실제 변환을 수행해야 합니다. GroupDocs.Conversion.Mcp 서버를 사용하면 Claude, Cursor 또는 GitHub Copilot이 로컬, 즉 사용자의 머신에서 한 문장으로 해당 엔진을 호출할 수 있습니다:

contract.docx를 PDF로 변환

구성 및 문제 해결 단계별 버전은 문서에 있습니다: AI 에이전트를 사용한 문서 변환 방법 (MCP). 이 게시물은 분할이 왜 중요한지와 에이전트가 어디에서 개입하지 않아야 하는지를 설명합니다.

에이전트가 파일을 직접 변환할 때 발생하는 문제

PDF를 Word로 “변환”한다고 주장하는 언어 모델은 실제로 변환을 수행하지 않습니다. 모델은 제공받은 내용을 읽고 대상 형식으로 새로운 내용을 작성합니다. 모델이 보지 못한 요소는 재현할 수 없습니다: 정확한 글꼴, 열 레이아웃, 표 앞의 페이지 나눔, Word 템플릿이 의존하는 스타일 이름 등. 반환된 결과는 변환처럼 보이지만 실제로는 재타이핑입니다.

이 게시물이 다루는 실패 모드가 바로 이것입니다. 출력 파일은 오류 없이 열리기 때문에 아무도 확인하지 않으며, 표가 이동하거나 제목 스타일이 사라질 때까지 문제를 인식하지 못합니다. 렌더링 정확도는 결정론적인 엔진 작업이며, 생성 작업이 아닙니다.

에이전트가 결정해야 할 사항과 엔진이 수행해야 할 작업

질문 에이전트가 결정 엔진이 수행
범위에 포함되는 파일은 무엇인가? 프롬프트와 저장 폴더를 읽음 없음
대상 형식은? “편집 가능하게 만들기”를 DOCX로, “보관하기”를 PDF로 매핑 없음
파일이 변환 가능한가? get_supported_formats를 호출하고 답변을 읽음 유효한 대상 형식을 보고
파일 크기는? get_document_info를 호출하고 페이지 수를 읽음 유형, 페이지 수, 속성을 읽음
실제 변환 convert를 호출 GroupDocs.Conversion 엔진으로 출력 렌더링
실패 시 처리 재시도, 사용자에게 질문, 또는 파일 건너뛰기 이유를 텍스트로 반환

에이전트를 로컬 엔진에 연결하는 방법

클라이언트에 서버를 한 번만 등록하면 됩니다. Claude Desktop은 claude_desktop_config.json을 사용하고, Claude Code는 claude mcp add를 사용하며, VS Code와 GitHub Copilot은 mcp.json을, Cursor는 ~/.cursor/mcp.json을 사용합니다. 서버는 Visual Studio 2022, Windsurf, Cline, Codex CLI 및 JetBrains Rider도 지원합니다. Claude Desktop 설정 예시는 다음과 같습니다:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Conversion.Mcp", "--yes"],
      "env": { "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents" }
    }
  }
}

dnx는 .NET 10 SDK가 필요합니다. Docker를 선호한다면 자체 포함 이미지 ghcr.io/groupdocs-conversion/conversion-net-mcp:latest를 사용하고, docker run --rm -i -v $(pwd)/documents:/data와 함께 실행합니다. 클라이언트는 stdio를 통해 서버와 통신합니다: 경로는 에이전트 → 로컬 서버 → 로컬 파일 시스템 순입니다. 등록 후 클라이언트를 재시작하십시오.

각 요청이 트리거하는 도구

서버는 네 가지 도구를 노출합니다. 이름은 그대로이며, 문제가 발생했을 때 에이전트가 이를 검색합니다.

  • convert는 문서를 다른 형식으로 변환하고 결과를 저장소 또는 출력 폴더에 저장합니다. file, format(예: pdf, docx, xlsx, pptx, html, png, jpg, csv, txt, rtf, md) 및 선택적 password를 입력으로 받습니다.
  • get_supported_formats는 주어진 소스 파일이 변환될 수 있는 대상 형식 목록을 반환합니다.
  • get_document_info는 변환 없이 파일 유형, 페이지 수 및 기본 속성을 반환합니다.
  • get_license_status는 서버가 평가, 라이선스 파일 또는 사용량 기반 모드 중 어느 모드로 실행되는지 보고합니다.

오픈형 프롬프트가 작동하는 이유는 에이전트가 이를 체인으로 연결하기 때문입니다:

이 Visio 파일을 어떤 형식으로 변환할 수 있나요? 그런 다음 PDF로 변환해 주세요.

먼저 whitepaper.pdf의 페이지 수를 확인하고, 그 다음 DOCX로 변환해 주세요.

기존 파일은 절대 덮어쓰지 않습니다. 동일 파일을 두 번째로 변환하면 report (1).pdf와 같이 별도 이름이 부여됩니다.

예시 세션

다음은 문서에 있는 도구 설명을 기반으로 만든 축약된 예시 세션이며, 실제 화면 캡처는 아닙니다.

You:    Convert contract-draft.pdf to DOCX so I can edit it.
Agent:  [calls convert with file.filePath = "contract-draft.pdf", format = "docx"]
Agent:  Done. The converted file is saved as contract-draft.docx in your output folder.

전체 흐름은 n8n 워크스루에서 확인할 수 있으며, 여기서는 채팅 대신 워크플로우가 동일 엔진을 구동합니다. 또한 서버 전반에 대한 안내도 참고하십시오.

제한 사항

  • 평가 모드. 라이선스가 없을 경우 서버는 변환된 출력에 평가 워터마크를 추가하고, 각 서버 프로세스당 열 수 있는 문서를 15개로 제한합니다. 서버를 재시작하면 카운트가 초기화됩니다. 먼저 에이전트에게 “변환 서버의 라이선스 상태가 무엇인가요?”라고 물어보고, get_license_status를 호출하면 문서를 처리하지 않고도 답변을 받을 수 있습니다.
  • OCR 미지원. 서버는 텍스트 레이어가 있는 문서만 변환합니다. 이미지 전용 PDF와 같이 스캔된 파일은 편집 가능한 텍스트로 변환되지 않습니다.
  • 변환은 지원하지만 추출은 지원하지 않음. 이 서버는 전체 문서를 변환합니다. 필드 수준 데이터 추출이 필요하면 별도 Docker 이미지로 제공되는 GroupDocs.Parser.Mcp 서버를 사용하는 것이 더 적합하며, 많은 파이프라인이 두 서버를 함께 사용합니다.

자주 묻는 질문

Claude가 docx를 pdf로 변환할 수 있나요?
예, 변환 서버가 연결되어 있으면 가능합니다. Claude는 convert를 format: "pdf"와 함께 호출하고, GroupDocs 엔진이 로컬 머신에서 파일을 생성합니다.

에이전트가 파일을 변환할 때 파일이 업로드되나요?
이 서버는 로컬에서 stdio를 통해 동작하므로 파일이 업로드되지 않습니다. 문서는 저장 폴더에 그대로 남으며, 라이선스 파일도 로컬 디스크에서 읽습니다.

서버가 지원하는 형식은 무엇인가요?
100개가 넘는 문서, 스프레드시트, 프레젠테이션, 이미지, 이메일, CAD 및 웹 형식을 지원합니다. 이는 GroupDocs.Conversion .NET 라이브러리와 동일한 세트이며, 특정 파일에 대한 정확한 목록은 get_supported_formats를 호출해 확인할 수 있습니다.

더 깊이 보기