Co-op Translator MCP를 만들면서 배운 것들

최근 Co-op Translator에 Model Context Protocol 서버를 추가했습니다.

Co-op Translator는 원래 Markdown 파일, Jupyter notebook, 이미지 안의 텍스트를 번역하는 CLI 중심 도구로 시작했습니다. 지금도 사람이 터미널에서 repository 전체를 번역할 때는 CLI가 가장 자연스러운 인터페이스입니다.

하지만 agent는 도구를 조금 다르게 봅니다.

Codex나 Claude Code 같은 agent는 큰 명령 하나를 실행하고 끝내기보다는, context를 읽고, 작은 action을 선택하고, 결과를 확인한 뒤 다음 단계를 결정합니다. 그래서 MCP로 노출하기 전에 Co-op Translator의 API 모양부터 다시 생각하게 되었습니다.

CLI는 복잡성을 숨겨도 괜찮다

CLI 명령은 한 번에 많은 일을 해도 괜찮습니다.

translate -l "ko" -md -nb -img

이 명령은 파일을 찾고, 콘텐츠를 번역하고, output path를 정하고, 링크를 재작성하고, metadata를 업데이트하고, 오래된 번역 asset을 정리할 수 있습니다. 사람 입장에서는 편합니다.

하지만 agent-facing API에서는 같은 편의성이 ambiguity가 될 수 있습니다.

하나의 tool이 번역, path rewriting, file write, metadata update를 동시에 수행하면 agent는 어떤 단계가 성공했고 다음에 무엇을 해야 하는지 이해하기 어려워집니다.

그래서 low-level responsibility를 더 명확하게 분리했습니다.

translate_markdown_content(document, language_code, options)
rewrite_markdown_paths(content, source_path, target_path, policy)
run_translation(...)

하나의 API는 Markdown 콘텐츠만 번역합니다. 다른 API는 caller가 source path와 target path를 알고 난 뒤 링크를 재작성합니다. project-level API는 CLI처럼 repository 전체 workflow를 orchestration합니다.

이 분리 덕분에 MCP 서버도 훨씬 이해하기 쉬워졌습니다.

MCP tool에는 안전한 기본값이 필요하다

MCP 서버는 기존 함수를 얇게 감싼 wrapper만으로는 충분하지 않았습니다.

MCP tool은 host application의 model이 호출합니다. 그래서 기본값이 중요합니다. repository translation은 많은 파일을 만들거나 수정할 수 있습니다. agent가 조용히 실행해서는 안 되는 작업입니다.

그래서 MCP를 통한 repository translation은 기본적으로 dry run으로 시작합니다. 실제 write를 하려면 명시적인 confirmation이 필요합니다.

{
  "language_codes": "ko",
  "root_dir": ".",
  "markdown": true,
  "dry_run": true
}

이 작업에서 가장 분명하게 배운 점 중 하나는 이것이었습니다. Agent-facing API에는 capability만큼 guardrail도 중요합니다. 더 좋은 기본값은 agent가 workspace를 변경하기 전에 먼저 범위를 확인하고, 설명하고, 사용자에게 물어볼 수 있게 만드는 쪽입니다.

Agent-assisted translation이 자연스러웠다

가장 흥미로웠던 부분은 agent-assisted translation이었습니다.

Provider-backed flow에서는 Co-op Translator가 Azure OpenAI나 OpenAI를 직접 호출합니다. 이 방식은 production pipeline이나 반복 가능한 automation에 유용합니다.

하지만 MCP 환경에서는 host agent가 이미 model을 가지고 있습니다. Markdown과 notebook의 경우 Co-op Translator가 항상 별도의 LLM provider를 직접 호출할 필요는 없습니다. 대신 작업을 준비하고, 구조를 보호하고, host agent가 chunk를 번역하도록 만들 수 있습니다.

흐름은 이렇게 됩니다.

1. start_markdown_agent_translation
2. host agent가 반환된 chunk를 번역
3. finish_markdown_agent_translation

Co-op Translator는 chunking, code placeholder 보존, frontmatter 복원, notebook Markdown cell 교체, post-translation normalization을 담당합니다. 실제 번역은 host agent가 수행합니다.

사용자는 이렇게 요청할 수 있습니다.

Translate this Markdown file to Korean with Co-op Translator MCP.
Use agent-assisted mode.
Keep Markdown formatting, code blocks, and links intact.

그러면 agent는 MCP tool을 호출하고, 준비된 chunk를 자신의 model로 번역한 뒤, 재구성된 Markdown을 반환할 수 있습니다.

이 역할 분리가 더 자연스럽게 느껴졌습니다. Agent는 언어 작업을 잘합니다. Co-op Translator는 언어 주변의 번역 workflow를 책임집니다.

이미지 번역은 다르게 봐야 한다

Markdown과 notebook은 content가 이미 text이기 때문에 agent-assisted path를 사용할 수 있습니다.

이미지는 다릅니다.

이미지 번역에는 OCR, bounding box, layout-aware rendering이 필요합니다. 이미지 안에서 텍스트가 어디에 있는지, 번역된 텍스트를 다시 어디에 그려야 하는지 알아야 합니다.

그래서 image translation은 여전히 provider-backed입니다. 텍스트 추출과 layout 정보를 위해 Azure AI Vision이 필요합니다.

이 차이는 문서에서 명확히 설명해야 했습니다. MCP를 지원한다는 것이 모든 workflow에서 key가 필요 없어졌다는 뜻은 아닙니다. 각 workflow가 자신에게 맞는 실행 모델을 선택할 수 있게 되었다는 뜻에 가깝습니다.

가장 큰 배움

이번 작업에서 가장 크게 배운 점은 단순했습니다.

Agent-facing API는 human-facing CLI보다 경계가 더 명확해야 한다.

사람을 위한 CLI는 편의성을 최적화해야 합니다. Agent를 위한 API는 조합 가능성, 예측 가능성, 안전한 기본값을 최적화해야 합니다.

좋은 MCP tool은 단순히 함수를 노출하는 것이 아닙니다. Agent가 추측하지 않고 workflow를 진행할 수 있도록 적절한 작업 표면을 제공하는 것입니다.

Co-op Translator MCP는 그 방향을 목표로 합니다. CLI 스타일의 전체 project workflow는 유지하면서, agent가 Markdown, notebook, image, path rewriting, review, configuration inspection을 더 작은 tool로 다룰 수 있게 만드는 것입니다.

이번 작업은 agent를 위한 developer tool을 제품화한다는 것이 무엇인지 다시 생각하게 해주었습니다. 이제 tool은 사람이 실행하는 명령만이 아닙니다. 다른 reasoning loop 안에서 사용되는 구성 요소가 됩니다.