“Rename ACME Corp to Globex in this contract” 은 사람에게는 3초면 되는 작업이지만 AI 에이전트에게는 함정입니다. 문서를 읽고 새로 작성하는 명백한 방법은 스타일, 표 테두리, 머리글, 그리고 다른 부분이 움직이지 않았다는 검토자의 확신을 모두 잃게 합니다. GroupDocs.Editor MCP 서버를 로컬에서 실행하면 Claude, Cursor 또는 Copilot이 파일을 다시 입력하는 대신 편집합니다: 단어를 찾아 바꾸고, 서식을 유지하며, 편집된 사본을 작성하고, 몇 개가 변경됐는지 알려줍니다:
contract.docx에서 ACME Corp를 Globex Ltd로 바꾸고 서식을 유지합니다.
설정, 프롬프트 및 문제 해결이 포함된 단계별 버전은 문서에 있습니다: How to edit documents with AI agents using MCP.
모델이 파일을 다시 쓰면 무엇이 잘못될까?
언어 모델은 .docx 파일을 보유하고 있지 않습니다. 텍스트만 보유합니다. “계약을 업데이트해라”라고 요청하면 자연스러운 경로는 단어를 읽어 내고, 바꾸고, 자체 복사본으로 새 문서를 만드는 것입니다. 이 과정에서 세 가지가 사라집니다.
서식. 굵게 표시된 당사자 이름, 번호 매긴 머리글, 표 격자선, 수수료 표의 열 너비, 실행 머리글: 이러한 요소는 모델이 읽은 텍스트에 포함되지 않으므로, 무언가가 다시 구축하지 않는 한 여행 중에 살아남지 못합니다.
모델이 건드리지 않도록 요청받지 않은 모든 것. 재생성은 모든 문장이 다시 모델을 통과한다는 의미입니다. 조항이 “정리”될 수 있고, 숫자가 재포맷될 수 있으며, 컨텍스트 창이 가득 차면 문장이 삭제될 수도 있습니다. 이제 검토자는 전체 문서를 비교(diff)해야 세 단어 변경을 신뢰할 수 있습니다.
감사 추적. “계약을 업데이트했습니다”라는 답변은 모델이 한 개의 이름을 바꾸었든 일곱 개를 바꾸었든 동일합니다. 개수가 없고, 신중한 편집과 자신감 있는 편집을 구분할 방법이 없습니다.
목표 편집은 어떻게 보일까?
두 번의 호출. 합성 서비스 계약서에서 “ACME Corp”가 일곱 번 나타나는 경우에 대해 GroupDocs.Editor.Mcp 26.10.0으로 캡처한 예시:
-> get_document_info {"file":{"filePath":"contract.docx"}}
<- { "family": "WordProcessing", "pageCount": 1, "canEdit": true,
"canSaveTo": [ "docx", "doc", "rtf", "odt", "pdf", "md", ... ] }
-> replace_text {"file":{"filePath":"contract.docx"},
"find":"ACME Corp","replace":"Globex Ltd","wholeWord":true}
<- Replaced 6 occurrence(s) of 'ACME Corp' in 'contract.docx'
Saved to: …/contract_edited.docx
-> replace_text {"file":{"filePath":"contract.docx"},
"find":"Initech","replace":"Globex Ltd"}
<- Text replacement found no matches for 'Initech' in 'contract.docx'.
No file was written.
편집된 사본은 굵은 당사자 이름, 머리글 스타일 및 수수료 표를 유지합니다. 원본은 손대지 않으며, 결과는 저장 폴더에 contract_edited.docx라는 새 파일이 됩니다.
그 사본은 엔진에 의해 작성되며 바이트 단위로 패치되지 않습니다: 서버는 문서를 HTML 편집 모델로 열고, 그곳에서 텍스트를 교체한 뒤 새 파일을 저장합니다. 우리는 Word 문서가 무엇을 유지하는지 테스트했습니다. 스타일, 표, 이미지, 하이퍼링크, 북마크, 머리글, 각주 및 댓글은 모두 그대로 전달됩니다. 서버 26.10.0에서는 바닥글은 유지되지 않으며, 콘텐츠 컨트롤은 평문으로 평탄화되고, 추적 변경은 작성자를 잃습니다. 전체 목록과 바닥글에 대한 해결 방법은 FAQ에 있습니다.
왜 여섯 개이고 일곱 개가 아니라?
이것이 두 번 읽을 가치가 있는 상세 내용입니다. 일곱 번째 “ACME Corp”는 고지 조항에 있는데, “ACME”는 이탤릭이고 “ Corp”는 일반 서식입니다. 파일에서는 두 개의 서식 실행으로 나뉘며, replace_text는 하나의 실행 내에서만 일치합니다. 추측하지도 않았고, 스타일을 병합해 강제로 일치시키지도 않았습니다; 여섯 개만 보고했으며, 일곱 번째는 여전히 “ACME Corp”입니다.
이는 계약서를 편집하는 도구가 보여야 할 동작입니다. 기대보다 적은 개수는 살펴볼 신호이며, 조용히 “완전” 재작성되는 것은 바람직하지 않습니다. 에이전트는 서버가 제공하는 다른 경로를 따라갈 수 있습니다: 해당 부분을 HTML로 추출하고, 편집한 뒤 다시 저장합니다. 라운드 트립 포스트에서 자세히 다룹니다.
호출 순서
user agent Editor MCP server
| "Rename ACME Corp to Globex Ltd in contract.docx" |
|---------------->| |
| |-- get_document_info {"file":...} -------->|
| |<- WordProcessing, 1 page, canEdit --------|
| |-- replace_text {"find":"ACME Corp", |
| | "replace":"Globex Ltd", |
| | "wholeWord":true} ------------------->|
| |<- "Replaced 6 occurrence(s) ... |
| | Saved to: .../contract_edited.docx" ---|
|<- "6 changed; one more is split across formatting - check |
| the notices clause. The original is kept." |
(a find that matches nothing: 'No file was written.')
이것이 단순한 Word 트릭을 넘어서는 이유
같은 호출이 워크시트, 슬라이드, PDF 또는 텍스트 파일에서도 작동합니다. 테스트에서는 "worksheet": 1이 예산 요약 시트의 공급자를 바꾸고 나머지 두 시트는 그대로 두었으며, "slide": 1도 리뷰 덱에서 동일하게 동작했습니다. "format": "pdf"는 한 번의 호출로 편집과 변환을 동시에 수행하므로 “이름을 고치고 PDF로 보내줘”가 한 단계가 됩니다. "regex": true는 버전 문자열과 같은 패턴을 처리합니다.
편집 전에 get_document_info는 에이전트에게 파일 종류, 페이지·워크시트·슬라이드 수, 비밀번호 보호 여부, 저장 가능한 포맷 등을 알려줍니다. 신중한 에이전트는 먼저 이를 호출하고, 필요에 따라 요청할 수 있습니다.
설정
dnx GroupDocs.Editor.Mcp --yes
GROUPDOCS_MCP_STORAGE_PATH를 에이전트가 편집할 수 있는 폴더로 지정하거나 Docker 이미지 ghcr.io/groupdocs-editor/editor-net-mcp를 사용합니다(Linux에서는 --user "$(id -u):$(id -g)" 옵션으로 실행해 폴더에 쓸 수 있게 합니다). 클라이언트별 구성은 documentation hub에 있습니다. 엔진 자체의 변경 사항은 GroupDocs.Editor for .NET 26.6 release notes에 기록되어 있습니다.
솔직한 제한 사항
replace_text는 하나의 서식 실행 내에서만 일치합니다; 스타일이 나뉜 구절은 찾지 못하고, 개수에 반영됩니다.- 서버 26.10.0에서는
replace_text가 편집된 사본에서 Word 문서의 바닥글을 삭제하고 콘텐츠 컨트롤을 평탄화합니다. 바닥글이 중요한 문서는 페이지네이션된 HTML 라운드 트립을 사용하세요(세부 사항). - 추적 변경이 없음: 새 편집은 추적되지 않습니다. 기존 댓글과 추적 변경은 사본에 남아 있습니다.
- 평가 모드: 모든 출력은 평가 배너 라인으로 시작하고, 저장된 워크북은 추가 워크시트를 하나 더 갖게 되며, 첫 두 워크시트·슬라이드만 편집 가능하고 세 번째는 서버가 거부하며 이유를 알려줍니다. PDF는 호출당 두 페이지씩 편집됩니다.
- PDF 편집은 편집 가능한 HTML 또는 Word로 변환한 뒤 다시 변환하는 것이며, PDF 파일 자체를 직접 편집하는 것은 아닙니다.
FAQ
에이전트가 원본 파일을 덮어쓰나요?
아니요. 모든 편집은 새 파일을 작성합니다. 기본적으로 <name>_edited.<ext> 형태이며, outputName을 지정하면 그 이름으로 출력 폴더에 저장됩니다. 이미 존재하는 이름이면 번호가 붙어 contract_edited (1).docx처럼 저장되며, 기존 파일은 덮어쓰지 않습니다.
문서에 텍스트가 없으면 어떻게 되나요?
아무 것도 쓰지 않습니다. 서버는 “found no matches … No file was written.”이라고 응답하므로 에이전트가 변경되지 않은 사본을 반환하는 대신 이를 알려줄 수 있습니다.
Word가 설치되어 있지 않아도 작동하나요?
예. 서버는 GroupDocs.Editor 엔진으로 로컬에서 실행되며, Office 설치나 업로드가 필요 없습니다.
더 깊이 파고들기
- 문서, 정식 사용법: How to edit documents with AI agents using MCP
- 문서 허브: GroupDocs.Editor MCP Server
- GroupDocs.Editor MCP 제품 페이지 — VS Code와 Cursor용 원클릭 설치, 다른 모든 클라이언트용 설정
- 관련: 포맷을 건드리지 않고 40개 계약서의 당사자를 일괄 변경
- 관련: AI 에이전트와 스프레드시트를 이용해 Word 양식 채우기, 로컬에서
- 관련: 한 워크시트만 편집하고 워크북은 유지: HTML 라운드 트립을 이용한 정밀 편집
- 관련: AI 에이전트와 PDF 편집? 먼저 Word로 변환, 로컬에서
- 온프레미스 및 보안 모델: AI 문서 처리 3가지 아키텍처, 파일을 네트워크 내부에 보관하는 방법
- 질문: GroupDocs Editor 포럼
- 소스: GroupDocs.Editor.Mcp on GitHub · NuGet package