diff --git a/_posts/2025-12-28-translation-mcp-project-overview.md b/_posts/2025-12-28-translation-mcp-project-overview.md new file mode 100644 index 0000000..211c2e6 --- /dev/null +++ b/_posts/2025-12-28-translation-mcp-project-overview.md @@ -0,0 +1,214 @@ +--- +layout: post +title: "Hugging Face 번역 MCP 서버 자기소개 시작" +author: minju +categories: [Robotics, AI, Community] +image: assets/images/blog/posts/2025-11-20-translation-mcp-project-overview/thumbnail.png +--- +* TOC +{:toc} + +_이 글은 Hugging Face 문서 번역 프로젝트의 MCP server 소개글입니다._ + +--- + +## 들어가기 전 + +이 글은 Hugging Face 번역 MCP 서버 프로젝트의 글들과 함께 읽으시면 좋습니다. + +현서님께서 MCP 서버 전략 및 개발 도구 선정 과정을 소개해주셨어요. +👉 [MCP 서버 설계 전략 및 개발 도구 선정](https://hugging-face-krew.github.io/hf_translation_hub_mcp_design_and_tooling/) + +그리고 각 MCP 서버의 사용법도 소개해주셨습니다. +👉 [HuggingFace 번역 MCP 서버 사용법](https://hugging-face-krew.github.io/hf-translation-hub-mcp-server-usage-guide/) + +--- + +## MCP server 배포 완료 🎉 + +프로젝트를 기획할 당시에 설계했던 3개의 MCP server와 현서님께서 추가해주신 PR 리뷰 MCP server까지 총 **4개의 MCP server**들의 배포가 완료되었습니다! + +허깅페이스 스페이스에 각각 배포를 완료하였고, Hugging Face Chat, Claude Desktop, Gemini CLI에 MCP server를 연결하고 테스트를 진행하였어요. + +이 글에서는 각 MCP server 안에 등록된 tool들과 각 tool들에 대한 설명을 소개드리려고 합니다. + +번역할 문서 검색, 문서 번역, 번역 PR 등록, 번역 PR 리뷰의 총 4가지 MCP server를 차례대로 살펴보겠습니다. + +![mcp-list](../assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/mcp_list.png) + +--- + +## Hugging Face MCP 서버와 도구 소개 + +우리 팀은 번역 문서 관리와 PR 자동화, 리뷰를 위해 총 4개의 Hugging Face MCP 서버를 운영하고 있습니다. + +각 서버는 특화된 도구들을 제공하여 번역 작업의 검색, 생성, 관리, 리뷰를 자동화할 수 있습니다. + +아래에서 각 서버와 그 안의 도구들을 자세히 소개합니다. + +--- + +## 1️⃣ hf-translation-docs-explorer + +### 개요 +- **주요 역할:** 번역 프로젝트 및 문서 탐색, 상태 확인 +- **URL:** `https://hyeonseo-hf-translation-docs-explorer.hf.space/gradio_api/mcp/` + +### 설명 +이 서버는 번역해야 할 문서 파일을 찾고, 누락되거나 오래된 파일을 확인하는 데 특화되어 있습니다. 사용자는 프로젝트별로 번역 진행 상태를 쉽게 파악할 수 있습니다. + +예를 들어, `transformers` 프로젝트의 한국어 번역에서 어떤 파일이 아직 번역되지 않았는지, 어떤 파일이 원본 대비 오래되어 업데이트가 필요한지 한눈에 확인할 수 있어요. + +### 🛠️ 도구 목록 + +| Tool 이름 | 설명 | 입력 파라미터 | +|-----------|------|---------------| +| `hf_translation_docs_explorer_list_projects` | 번역 프로젝트 목록 조회 | 없음 | +| `hf_translation_docs_explorer_search_files` | 특정 프로젝트/언어의 파일 검색 | `project` (`smolagents`, `transformers`)
`lang` (`ko`, `ja`, `zh`, `fr`, `de`)
`limit`
`include_status_report` | +| `hf_translation_docs_explorer_list_missing_files` | 누락된 번역 파일 목록 조회 | `project`
`lang`
`limit` | +| `hf_translation_docs_explorer_list_outdated_files` | 오래된 번역 파일 목록 조회 | `project`
`lang`
`limit` | + +**지원하는 프로젝트:** `smolagents`, `transformers` +**지원하는 언어:** `ko` (한국어), `ja` (일본어), `zh` (중국어), `fr` (프랑스어), `de` (독일어) + +--- + +## 2️⃣ hf-translation-docs + +### 개요 +- **주요 역할:** 번역 문서 처리 전체 파이프라인 +- **URL:** `https://jmj-minju-hf-translation-docs.hf.space/gradio_api/mcp/` + +### 설명 +문서 번역 과정 전체를 다루는 핵심 서버입니다. 번역 파일 검색부터 내용 조회, 번역 프롬프트 생성, 품질 검증, 결과 저장까지 모든 단계를 지원합니다. + +이 서버를 통해 번역 워크플로우를 일관성 있게 관리할 수 있습니다. 특히 번역 프롬프트 생성 기능은 번역자가 일관된 스타일과 품질로 번역할 수 있도록 도와주며, 검증 기능은 번역 결과가 원본 포맷을 유지하고 있는지 자동으로 확인해줍니다. + +### 🛠️ 도구 목록 + +| Tool 이름 | 설명 | 입력 파라미터 | +|-----------|------|---------------| +| `hf_translation_docs_get_project_config` | 프로젝트 설정 정보 조회 | `project` | +| `hf_translation_docs_search_translation_files` | 번역이 필요한 파일 검색 | `project`
`target_language`
`max_files` | +| `hf_translation_docs_get_file_content` | 특정 파일 내용 조회 | `project`
`file_path`
`include_metadata` | +| `hf_translation_docs_generate_translation_prompt` | 번역 프롬프트 생성 | `target_language`
`content`
`additional_instruction`
`project`
`file_path` | +| `hf_translation_docs_validate_translation` | 번역 품질/포맷 검증 | `original_content`
`translated_content`
`target_language`
`file_path` | +| `hf_translation_docs_save_translation_result` | 번역 결과 저장 | `project`
`original_file_path`
`translated_content`
`target_language` | + +이 서버는 번역 작업의 중심축 역할을 하며, 번역의 시작부터 끝까지 모든 과정을 체계적으로 관리할 수 있게 해줍니다. + +--- + +## 3️⃣ hf-translation-pr-generator + +### 개요 +- **주요 역할:** 번역 PR(Pull Request) 자동 생성 +- **URL:** `https://jmj-minju-hf-translation-pr-generator.hf.space/gradio_api/mcp/` + +### 설명 +번역 작업을 PR 형태로 GitHub에 자동 생성하고 관리하는 서버입니다. + +번역이 완료되면 수동으로 GitHub에 접속해서 PR을 생성하는 것이 아니라, 이 서버를 통해 자동으로 PR을 생성할 수 있어요. PR 생성 전 설정 검증, 참조 PR 검색, 번역 분석, PR 초안 생성, 최종 PR 생성까지 일련의 과정을 모두 지원합니다. + +특히 참조 PR 검색 기능은 이전에 승인된 번역 PR들을 참고하여 일관성 있는 번역 스타일을 유지할 수 있도록 도와줍니다. + +### 🛠️ 도구 목록 + +| Tool 이름 | 설명 | 입력 파라미터 | +|-----------|------|---------------| +| `hf_translation_pr_generator_validate_pr_config_ui` | PR 생성 설정 검증 (UI) | `github_token`
`owner`
`repo_name`
`project` | +| `hf_translation_pr_generator_search_reference_pr` | 참조용 PR 검색 | `target_language`
`context` | +| `hf_translation_pr_generator_analyze_translation` | 번역 내용 분석 및 메타데이터 생성 | `filepath`
`translated_content`
`target_language`
`project` | +| `hf_translation_pr_generator_generate_pr_draft` | PR 초안/메타데이터 생성 | `filepath`
`translated_content`
`target_language`
`reference_pr_url`
`project` | +| `hf_translation_pr_generator_create_github_pr` | GitHub PR 생성 | `github_token`
`owner`
`repo_name`
`filepath`
`translated_content`
`target_language`
`reference_pr_url`
`project` | + +이 서버를 사용하면 번역 작업이 끝난 후 PR 생성에 들어가는 시간과 노력을 크게 줄일 수 있습니다. + +--- + +## 4️⃣ hf-translation-reviewer + +### 개요 +- **주요 역할:** 번역 리뷰 및 피드백 자동화 +- **URL:** `https://hyeonseo-hf-translation-reviewer.hf.space/gradio_api/mcp/` + +### 설명 +번역 PR을 검토하고 피드백을 생성하는 자동화 서버입니다. + +리뷰 준비, 응답/피드백 생성, 제출, 엔드투엔드 리뷰 등 모든 과정을 자동화할 수 있어 리뷰 업무의 부담을 크게 줄여줍니다. 특히 `e2e_proxy` 도구를 사용하면 리뷰 준비부터 피드백 생성, 제출까지 전 과정을 한 번에 실행할 수 있어요. + +리뷰어는 이 서버가 생성한 피드백을 바탕으로 최종 검토만 하면 되기 때문에, 리뷰 시간을 대폭 단축할 수 있습니다. + +### 🛠️ 도구 목록 + +| Tool 이름 | 설명 | 입력 파라미터 | +|-----------|------|---------------| +| `hf_translation_reviewer__prepare_proxy` | 리뷰 준비 (프록시) | `pr_url_`
`original_path_`
`translated_path_` | +| `hf_translation_reviewer__review_emit_proxy` | 검토 응답/피드백 생성 | `pr_url_`
`translated_path_`
`translated_text_`
`raw_response_` | +| `hf_translation_reviewer__submit_proxy` | 리뷰 제출 (프록시) | `pr_url_`
`translated_path_`
`payload_json_` | +| `hf_translation_reviewer__e2e_proxy` | 엔드투엔드 리뷰 및 제출 | `pr_url_`
`original_path_`
`translated_path_`
`save_review_`
`save_path_`
`submit_flag_`
`e2e_raw_response_` | + +--- + +## 🔹 전체 워크플로우 요약 + +4개의 MCP 서버가 어떻게 연결되어 작동하는지 살펴볼까요? + +### 단계별 프로세스 + +1. **hf-translation-docs-explorer** → 번역할 문서 탐색 및 상태 확인 + - 프로젝트에서 번역이 필요한 파일들을 찾습니다 + - 누락되거나 오래된 파일들을 확인합니다 + +2. **hf-translation-docs** → 파일 조회, 번역 생성, 검증, 저장 + - 파일 내용을 가져옵니다 + - 번역 프롬프트를 생성합니다 + - 번역 결과를 검증하고 저장합니다 + +3. **hf-translation-pr-generator** → GitHub PR 생성 및 관리 + - 번역 내용을 분석합니다 + - PR 초안을 생성합니다 + - GitHub에 PR을 자동으로 생성합니다 + +4. **hf-translation-reviewer** → PR 리뷰 및 제출 자동화 + - PR을 검토합니다 + - 자동으로 피드백을 생성합니다 + - 리뷰를 제출합니다 + +### 시퀀스 다이어그램 + +![mcp-list](../assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/image.png) + + +이 4개의 MCP 서버를 연계하면 **번역 문서 관리 → PR 생성 → 리뷰 제출**까지 완전한 자동화 워크플로우를 구축할 수 있습니다. + +![mcp-list](../assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/image2.png) + +예를 들어, Hugging Face chat에 mcp server를 연결한 모습입니다. + +--- + +## 💭 고민거리 + +프로젝트를 진행하면서 가장 큰 고민은 역시 **LLM 모델 사용 비용**입니다. + +Tool 사용이 가능하고 tool 선택을 잘 하는 모델은 Claude나 Gemini 같은 상용 모델들이에요. 이런 모델들을 사용하면 MCP 서버와의 연동이 매우 원활하고 정확합니다. + +하지만 프로젝트를 장기적으로 운영하려면 비용 문제를 고려하지 않을 수 없어요. 현재는 각 모델들의 무료 사용량 범위 내에서 테스트를 진행하고 있지만, 앞으로는 오픈소스 모델 중에서도 좋은 성능을 내는 모델을 찾아 활용하는 노력이 필요할 것 같습니다. + +--- + +## 마치며 + +Hugging Face 번역 MCP 서버 프로젝트는 번역 작업의 전 과정을 자동화하여 효율성을 크게 높일 수 있는 시스템입니다. + +4개의 서버가 각자의 역할을 충실히 수행하면서도 유기적으로 연결되어 하나의 완전한 워크플로우를 만들어내는 것이 이 프로젝트의 핵심이에요. + +앞으로도 계속해서 개선하고 발전시켜 나갈 예정이니, 많은 관심 부탁드립니다! 🚀 + +--- + +### 📚 관련 자료 + +- [MCP 서버 설계 전략 및 개발 도구 선정](https://hugging-face-krew.github.io/hf_translation_hub_mcp_design_and_tooling/) +- [HuggingFace 번역 MCP 서버 사용법](https://hugging-face-krew.github.io/hf-translation-hub-mcp-server-usage-guide/) \ No newline at end of file diff --git a/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/image.png b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/image.png new file mode 100644 index 0000000..557293f Binary files /dev/null and b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/image.png differ diff --git a/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/mcp_list.png b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/mcp_list.png new file mode 100644 index 0000000..3bf7b94 Binary files /dev/null and b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/mcp_list.png differ diff --git a/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/thumbnail.png b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/thumbnail.png new file mode 100644 index 0000000..dea67ca Binary files /dev/null and b/assets/images/blog/posts/2025-12-28-translation-mcp-project-overview/thumbnail.png differ