Convert MCP server submodules to regular directories

external/mcp-servers/hf-translation-docs-explorer

@@ -1 +0,0 @@
-Subproject commit 45883c3faf36a9abcf03ede91a12ed4c8f3ab1cc

external/mcp-servers/hf-translation-docs-explorer/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

external/mcp-servers/hf-translation-docs-explorer/README.md

@@ -0,0 +1,13 @@
+---
+title: Traslation File Explorer
+emoji: ⚡
+colorFrom: red
+colorTo: pink
+sdk: gradio
+sdk_version: 5.49.1
+app_file: app.py
+pinned: false
+license: mit
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

external/mcp-servers/hf-translation-docs-explorer/adapters.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+import requests
+
+from setting import SETTINGS
+
+
+def _build_auth_headers() -> Dict[str, str]:
+    """
+    GitHub 호출용 Authorization 헤더 생성.
+    - 우선순위: SETTINGS.github_token → (fallback) 환경변수 GITHUB_TOKEN
+    """
+    token = SETTINGS.github_token
+    if not token:
+        # 환경변수 직접 조회
+        import os
+        token = os.environ.get("GITHUB_TOKEN", "")
+
+    if not token:
+        return {}
+    return {"Authorization": f"token {token}"}
+
+
+def fetch_document_paths(api_url: str) -> List[str]:
+    """
+    GitHub git/trees API에서 blob 경로 목록만 추출.
+
+    Parameters
+    ----------
+    api_url : str
+        예: https://api.github.com/repos/huggingface/transformers/git/trees/main?recursive=1
+    """
+    response = requests.get(
+        api_url,
+        headers=_build_auth_headers(),
+        timeout=SETTINGS.request_timeout_seconds,
+    )
+
+    if response.status_code == 403 and "rate limit" in response.text.lower():
+        raise RuntimeError(
+            "GitHub API rate limit exceeded. Provide a GITHUB_TOKEN to continue."
+        )
+
+    response.raise_for_status()
+    tree = response.json().get("tree", [])
+    return [item["path"] for item in tree if item.get("type") == "blob"]

external/mcp-servers/hf-translation-docs-explorer/app.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import argparse
+import os
+
+import gradio as gr
+
+from services import get_available_projects, LANGUAGE_CHOICES
+from tools import list_projects, search_files, list_missing_files
+from setting import SETTINGS
+
+
+def ensure_mcp_support() -> None:
+    """Verify that ``gradio[mcp]`` is installed and enable the MCP server flag."""
+    try:
+        import gradio.mcp  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - runtime guard
+        raise RuntimeError("Install gradio[mcp] before launching this module.") from exc
+    os.environ.setdefault("GRADIO_MCP_SERVER", "true")
+
+
+def build_demo() -> gr.Blocks:
+    """Create a lightweight Gradio Blocks UI for exercising the MCP tools."""
+    projects = get_available_projects()
+    languages = LANGUAGE_CHOICES[:]
+
+    with gr.Blocks(title=SETTINGS.ui_title) as demo:
+        gr.Markdown("# Translation MCP Server\nTry the MCP tools exposed below.")
+
+        # --- 1) Project catalog ---
+        with gr.Tab("Project catalog"):
+            catalog_output = gr.JSON(label="catalog")
+            gr.Button("Fetch").click(
+                fn=list_projects,
+                inputs=[],  # 인자 없음
+                outputs=catalog_output,
+                api_name="translation_project_catalog",
+            )
+
+        # --- 2) File search (report + candidates) ---
+        with gr.Tab("File search"):
+            project_input = gr.Dropdown(
+                choices=projects,
+                label="Project",
+                value=projects[0] if projects else "",
+            )
+            lang_input = gr.Dropdown(
+                choices=languages,
+                label="Language",
+                value=SETTINGS.default_language,
+            )
+            limit_input = gr.Number(
+                label="Limit",
+                value=SETTINGS.default_limit,
+                minimum=1,
+            )
+            include_report = gr.Checkbox(
+                label="Include status report",
+                value=True,
+            )
+
+            search_output = gr.JSON(label="search result")
+            gr.Button("Search").click(
+                fn=search_files,
+                inputs=[project_input, lang_input, limit_input, include_report],
+                outputs=search_output,
+                api_name="translation_file_search",
+            )
+
+        # --- 3) Missing docs only ---
+        with gr.Tab("Missing docs"):
+            missing_project = gr.Dropdown(
+                choices=projects,
+                label="Project",
+                value=projects[0] if projects else "",
+            )
+            missing_lang = gr.Dropdown(
+                choices=languages,
+                label="Language",
+                value=SETTINGS.default_language,
+            )
+            missing_limit = gr.Number(
+                label="Limit",
+                value=max(SETTINGS.default_limit, 20),
+                minimum=1,
+            )
+
+            missing_output = gr.JSON(label="missing files")
+            gr.Button("List missing").click(
+                fn=list_missing_files,
+                inputs=[missing_project, missing_lang, missing_limit],
+                outputs=missing_output,
+                api_name="translation_missing_list",
+            )
+
+    return demo
+
+
+def _parse_args(argv=None) -> argparse.Namespace:
+    """Parse CLI arguments used for local or Space deployments."""
+    parser = argparse.ArgumentParser(description="Launch the translation MCP demo.")
+
+    parser.add_argument(
+        "--as-space",
+        action="store_true",
+        help="Use Hugging Face Space defaults.",
+    )
+    parser.add_argument(
+        "--share",
+        action="store_true",
+        help="Create a public share link.",
+    )
+    parser.add_argument(
+        "--no-queue",
+        dest="queue",
+        action="store_false",
+        help="Disable the request queue.",
+    )
+    parser.set_defaults(queue=True)
+
+    return parser.parse_args(argv)
+
+
+def main(argv=None) -> None:
+    """Launch the Gradio app with MCP server support enabled."""
+    args = _parse_args(argv)
+
+    ensure_mcp_support()
+
+    launch_kwargs = {"mcp_server": True}
+
+    if args.as_space or os.environ.get("SPACE_ID"):
+        launch_kwargs.update(
+            {
+                "server_name": "0.0.0.0",
+                "server_port": int(os.environ.get("PORT", "7860")),
+                "show_api": False,
+            }
+        )
+    else:
+        launch_kwargs["show_api"] = True
+
+    if args.share:
+        launch_kwargs["share"] = True
+
+    demo = build_demo()
+    app = demo.queue() if args.queue else demo
+    app.launch(**launch_kwargs)
+
+
+if __name__ == "__main__":  # pragma: no cover - manual execution helper
+    main()

external/mcp-servers/hf-translation-docs-explorer/configs/defaults.yaml

@@ -0,0 +1,10 @@
+github:
+  token: ""                 # 기본값: 환경변수 GITHUB_TOKEN 사용 권장
+  request_timeout_seconds: 30
+
+translation:
+  default_language: "ko"    # 기본 타겟 언어
+  default_limit: 5          # 기본 검색/누락 파일 개수
+
+ui:
+  title: "Translation Docs Search MCP Server"

external/mcp-servers/hf-translation-docs-explorer/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "translation-file-explorer-mcp"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+  "gradio[mcp]>=5.33.0",
+  "pydantic>=2.7.0",
+  "requests>=2.31.0",
+  "pyyaml>=6.0.1",
+]
+
+[tool.ruff]
+line-length = 100

external/mcp-servers/hf-translation-docs-explorer/requirements.txt

@@ -0,0 +1,11 @@
+gradio[mcp]==5.33.0
+requests
+pydantic
+langchain-anthropic
+python-dotenv
+langchain
+PyGithub
+langchain-core
+langchain-community
+boto3
+PyYAML

external/mcp-servers/hf-translation-docs-explorer/services.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Tuple
+
+from adapters import fetch_document_paths
+from setting import SETTINGS
+
+
+# Gradio / UI 에 노출할 언어 선택지
+LANGUAGE_CHOICES: List[str] = [
+    "ko",
+    "ja",
+    "zh",
+    "fr",
+    "de",
+]
+
+
+@dataclass(frozen=True)
+class Project:
+    """Store the minimum metadata required for documentation lookups."""
+
+    slug: str
+    name: str
+    repo_url: str
+    docs_path: str
+    tree_api_url: str
+
+    @property
+    def repo_path(self) -> str:
+        """Return the ``owner/repo`` identifier for GitHub API requests."""
+        return self.repo_url.replace("https://github.com/", "")
+
+
+# 지원 프로젝트 정의
+PROJECTS: Dict[str, Project] = {
+    "transformers": Project(
+        slug="transformers",
+        name="Transformers",
+        repo_url="https://github.com/huggingface/transformers",
+        docs_path="docs/source",
+        tree_api_url=(
+            "https://api.github.com/repos/huggingface/transformers/git/trees/main?recursive=1"
+        ),
+    ),
+    "smolagents": Project(
+        slug="smolagents",
+        name="SmolAgents",
+        repo_url="https://github.com/huggingface/smolagents",
+        docs_path="docs/source",
+        tree_api_url=(
+            "https://api.github.com/repos/huggingface/smolagents/git/trees/main?recursive=1"
+        ),
+    ),
+}
+
+
+def get_available_projects() -> List[str]:
+    """Return the list of project slugs supported by this module."""
+    return sorted(PROJECTS.keys())
+
+
+def _iter_english_docs(all_docs: Iterable[str], docs_root: str) -> Iterable[Path]:
+    """Yield English documentation files as ``Path`` objects."""
+    english_root = Path(docs_root) / "en"
+
+    for doc_path in all_docs:
+        if not doc_path.endswith(".md"):
+            continue
+
+        path = Path(doc_path)
+        try:
+            # en/ 아래에 있는지 필터링
+            path.relative_to(english_root)
+        except ValueError:
+            continue
+
+        yield path
+
+
+def _compute_missing_translations(
+    project_key: str,
+    language: str,
+    limit: int,
+) -> Tuple[str, List[str], Project]:
+    """
+    영어 기준으로 누락 번역 파일을 계산하고,
+    마크다운 요약 리포트 + 누락 경로 리스트 + Project 메타데이터를 반환.
+    """
+    project = PROJECTS[project_key]
+
+    all_paths = fetch_document_paths(project.tree_api_url)
+    english_docs = list(_iter_english_docs(all_paths, project.docs_path))
+    english_total = len(english_docs)
+
+    missing: List[str] = []
+    docs_set = set(all_paths)
+
+    for english_doc in english_docs:
+        relative = english_doc.relative_to(Path(project.docs_path) / "en")
+        translated_path = str(Path(project.docs_path) / language / relative)
+
+        if translated_path not in docs_set:
+            # 누락된 경우: 기준은 영어 경로(en/...)
+            missing.append(str(english_doc))
+            if len(missing) >= limit:
+                break
+
+    missing_count = len(missing)
+    percentage = (missing_count / english_total * 100) if english_total else 0.0
+
+    report = (
+        "| Item | Count | Percentage |\n"
+        "|------|-------|------------|\n"
+        f"| English docs | {english_total} | - |\n"
+        f"| Missing translations | {missing_count} | {percentage:.2f}% |"
+    )
+
+    return report, missing, project
+
+
+def build_project_catalog(default: str | None) -> Dict[str, Any]:
+    """Build the project catalog payload (API-neutral, pure logic)."""
+    slugs = get_available_projects()
+    default = default if default in slugs else None
+
+    return {
+        "type": "translation.project_list",
+        "projects": [
+            {
+                "slug": slug,
+                "display_name": PROJECTS[slug].name,
+                "repo_url": PROJECTS[slug].repo_url,
+                "docs_path": PROJECTS[slug].docs_path,
+            }
+            for slug in slugs
+        ],
+        "default_project": default,
+        "total_projects": len(slugs),
+    }
+
+
+def build_search_response(
+    project: str,
+    lang: str,
+    limit: int,
+    include_status_report: bool,
+) -> Dict[str, Any]:
+    """
+    누락 번역 파일 후보 + (선택) 상태 리포트를 포함한 검색 응답.
+    MCP / Gradio 에서 사용 가능한 JSON 형태.
+    """
+    project = project.strip()
+    lang = lang.strip()
+    limit = max(1, int(limit))
+
+    project_config = PROJECTS[project]
+
+    status_report, candidate_paths, project_config = _compute_missing_translations(
+        project_key=project,
+        language=lang,
+        limit=limit,
+    )
+
+    repo_url = project_config.repo_url.rstrip("/")
+
+    return {
+        "type": "translation.search.response",
+        "request": {
+            "type": "translation.search.request",
+            "project": project,
+            "target_language": lang,
+            "limit": limit,
+            "include_status_report": include_status_report,
+        },
+        "files": [
+            {
+                "rank": index,
+                "path": path,
+                "repo_url": f"{repo_url}/blob/main/{path}",
+                "metadata": {
+                    "project": project,
+                    "target_language": lang,
+                    "docs_path": project_config.docs_path,
+                },
+            }
+            for index, path in enumerate(candidate_paths, start=1)
+        ],
+        "total_candidates": len(candidate_paths),
+        "status_report": status_report if include_status_report else None,
+    }
+
+
+def build_missing_list_response(
+    project: str,
+    lang: str,
+    limit: int,
+) -> Dict[str, Any]:
+    """
+    누락 번역 파일 목록만 제공하는 응답(JSON).
+    """
+    project = project.strip()
+    lang = lang.strip()
+    limit_int = max(1, int(limit))
+
+    status_report, missing_paths, project_config = _compute_missing_translations(
+        project_key=project,
+        language=lang,
+        limit=limit_int,
+    )
+
+    repo_url = project_config.repo_url.rstrip("/")
+
+    return {
+        "type": "translation.missing_list",
+        "project": project,
+        "target_language": lang,
+        "limit": limit_int,
+        "count": len(missing_paths),
+        "files": [
+            {
+                "rank": index,
+                "path": path,
+                "repo_url": f"{repo_url}/blob/main/{path}",
+                "metadata": {
+                    "project": project,
+                    "target_language": lang,
+                    "docs_path": project_config.docs_path,
+                },
+            }
+            for index, path in enumerate(missing_paths, start=1)
+        ],
+        "status_report": status_report,  # 필요 없다면 제거 가능
+    }

external/mcp-servers/hf-translation-docs-explorer/setting.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+import os
+
+try:
+    import yaml  # type: ignore
+except Exception:
+    yaml = None
+
+
+@dataclass
+class AppSettings:
+    github_token: str = ""
+    request_timeout_seconds: int = 30
+    default_language: str = "ko"
+    default_limit: int = 5
+    ui_title: str = "Translation MCP Server"
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    if not path.is_file():
+        return {}
+    if yaml is None:
+        return {}
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def load_settings(config_path: str = "configs/default.yaml") -> AppSettings:
+    cfg = _load_yaml(Path(config_path))
+
+    github_cfg = cfg.get("github", {}) if isinstance(cfg.get("github"), dict) else {}
+    trans_cfg = cfg.get("translation", {}) if isinstance(cfg.get("translation"), dict) else {}
+    ui_cfg = cfg.get("ui", {}) if isinstance(cfg.get("ui"), dict) else {}
+
+    # ENV > YAML
+    github_token = os.getenv("GITHUB_TOKEN", github_cfg.get("token", ""))
+    request_timeout_seconds = int(
+        os.getenv("REQUEST_TIMEOUT_SECONDS", github_cfg.get("request_timeout_seconds", 30))
+    )
+    default_language = os.getenv("DEFAULT_LANGUAGE", trans_cfg.get("default_language", "ko"))
+    default_limit = int(
+        os.getenv("DEFAULT_LIMIT", trans_cfg.get("default_limit", 5))
+    )
+    ui_title = ui_cfg.get("title", "Translation MCP Server")
+
+    return AppSettings(
+        github_token=github_token,
+        request_timeout_seconds=request_timeout_seconds,
+        default_language=default_language,
+        default_limit=default_limit,
+        ui_title=ui_title,
+    )
+
+
+# 전역 설정 인스턴스
+SETTINGS: AppSettings = load_settings()

external/mcp-servers/hf-translation-docs-explorer/tools.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from services import (
+    build_project_catalog,
+    build_search_response,
+    build_missing_list_response,
+)
+
+
+def list_projects() -> Dict[str, Any]:
+    """
+    Gradio + MCP에서 사용되는 'translation_project_catalog' 엔드포인트.
+    입력값 없이 전체 프로젝트 카탈로그를 반환한다.
+    """
+    return build_project_catalog(default=None)
+
+
+def search_files(
+    project: str,
+    lang: str,
+    limit: float | int,
+    include_status_report: bool,
+) -> Dict[str, Any]:
+    """
+    Gradio + MCP에서 사용되는 'translation_file_search' 엔드포인트.
+    """
+    return build_search_response(
+        project=project,
+        lang=lang,
+        limit=int(limit or 1),
+        include_status_report=bool(include_status_report),
+    )
+
+
+def list_missing_files(
+    project: str,
+    lang: str,
+    limit: float | int,
+) -> Dict[str, Any]:
+    """
+    Gradio + MCP에서 사용되는 'translation_missing_list' 엔드포인트.
+    누락 파일 리스트만 반환.
+    """
+    return build_missing_list_response(
+        project=project,
+        lang=lang,
+        limit=int(limit or 1),
+    )

external/mcp-servers/hf-translation-reviewer

@@ -1 +0,0 @@
-Subproject commit d3b82f5b7eba8b3121d9f49792908edb59758e47

external/mcp-servers/hf-translation-reviewer/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

external/mcp-servers/hf-translation-reviewer/README.md

@@ -0,0 +1,13 @@
+---
+title: LLM Translation Reviewer
+emoji: 🦀
+colorFrom: blue
+colorTo: gray
+sdk: gradio
+sdk_version: 5.49.1
+app_file: app.py
+pinned: false
+license: mit
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

external/mcp-servers/hf-translation-reviewer/adapters.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import base64
+from typing import Dict, List, Optional
+
+from urllib.parse import urlparse
+
+import requests
+
+from setting import SETTINGS
+
+# Optional provider SDKs
+try:
+    import openai  # type: ignore
+except Exception:
+    openai = None
+
+try:
+    import anthropic  # type: ignore
+except Exception:
+    anthropic = None
+
+try:
+    import google.generativeai as genai  # type: ignore
+except Exception:
+    genai = None
+
+
+# ---------------- GitHub HTTP adapters -----------------
+
+
+def github_request(
+    url: str,
+    token: str,
+    params: Optional[Dict[str, str]] = None,
+) -> Dict:
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "Authorization": f"token {token}",
+    }
+    response = requests.get(url, headers=headers, params=params, timeout=30)
+    if response.status_code == 404:
+        raise FileNotFoundError(f"GitHub resource not found: {url}")
+    if response.status_code == 401:
+        raise PermissionError("GitHub token is invalid or lacks necessary scopes.")
+    if response.status_code >= 400:
+        raise RuntimeError(
+            f"GitHub API request failed with status {response.status_code}: {response.text}"
+        )
+    return response.json()
+
+
+def fetch_file_from_pr(
+    repo_name: str,
+    pr_number: int,
+    path: str,
+    head_sha: str,
+    github_token: str,
+) -> str:
+    url = f"{SETTINGS.github_api_base}/repos/{repo_name}/contents/{path}"
+    data = github_request(url, github_token, params={"ref": head_sha})
+    content = data.get("content")
+    encoding = data.get("encoding")
+    if content is None or encoding != "base64":
+        raise ValueError(
+            f"Unexpected content response for '{path}' (encoding={encoding!r})."
+        )
+    decoded = base64.b64decode(content)
+    try:
+        return decoded.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ValueError(
+            f"File '{path}' in PR {pr_number} is not valid UTF-8 text"
+        ) from exc
+
+
+# ---------------- LLM provider adapters -----------------
+
+
+def call_openai(
+    token: str,
+    system_prompt: str,
+    user_prompt: str,
+    model_name: str = "gpt-5",
+) -> str:
+    if openai is None:
+        raise RuntimeError("openai package not installed. Install with `pip install openai`.")
+    client = openai.OpenAI(api_key=token)
+    params = {
+        "model": model_name,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+    }
+    # Some models (e.g., gpt-5) may not allow custom temperature.
+    if model_name not in {"gpt-5"}:
+        params["temperature"] = 0.2
+    response = client.chat.completions.create(**params)
+    return response.choices[0].message.content.strip()
+
+
+def call_anthropic(
+    token: str,
+    system_prompt: str,
+    user_prompt: str,
+    model_name: str = "claude-3-5-sonnet-20240620",
+) -> str:
+    if anthropic is None:
+        raise RuntimeError("anthropic package not installed. Install with `pip install anthropic`.")
+    client = anthropic.Anthropic(api_key=token)
+    response = client.messages.create(
+        model=model_name,
+        system=system_prompt,
+        max_tokens=1500,
+        temperature=0.2,
+        messages=[{"role": "user", "content": user_prompt}],
+    )
+    return "".join(block.text for block in response.content if hasattr(block, "text")).strip()
+
+
+def call_gemini(
+    token: str,
+    system_prompt: str,
+    user_prompt: str,
+    model_name: str = "gemini-1.5-pro",
+) -> str:
+    if genai is None:
+        raise RuntimeError("google-generativeai package not installed. Install with `pip install google-generativeai`.")
+    genai.configure(api_key=token)
+    model = genai.GenerativeModel(model_name)
+    prompt = f"{system_prompt}\n\n{user_prompt}"
+    response = model.generate_content(prompt, generation_config={"temperature": 0.2})
+    return response.text.strip()
+
+
+PROVIDERS = {
+    "openai": call_openai,
+    "anthropic": call_anthropic,
+    "gemini": call_gemini,
+}
+
+
+def dispatch_review(
+    provider: str,
+    token: str,
+    system_prompt: str,
+    user_prompt: str,
+    model_name: str,
+) -> str:
+    if provider not in PROVIDERS:
+        raise ValueError(f"Unknown provider '{provider}'. Choose from: {', '.join(PROVIDERS)}")
+    return PROVIDERS[provider](token, system_prompt, user_prompt, model_name)

external/mcp-servers/hf-translation-reviewer/app.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+Gradio + MCP server app for LLM translation review on GitHub PRs.
+
+- UI만 담당하고, 실제 로직은 tools/services/adapters 로 분리.
+"""
+
+from __future__ import annotations
+
+import json
+
+import gradio as gr
+
+from setting import SETTINGS
+from tools import (
+    tool_prepare,
+    tool_review_and_emit,
+    tool_submit_review,
+    tool_end_to_end,
+)
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title=SETTINGS.ui_title) as demo:
+        gr.Markdown(
+            "# LLM Translation Reviewer for GitHub PRs (MCP-enabled)\n"
+            "Only **PR URL** + fields below are required. Repo/PR number are parsed."
+        )
+
+        # 공통 입력 영역
+        with gr.Row():
+            pr_url = gr.Textbox(
+                label="PR URL",
+                placeholder="https://github.com/owner/repo/pull/123",
+                scale=2,
+            )
+            provider = gr.Dropdown(
+                label="Provider",
+                choices=["openai", "anthropic", "gemini"],
+                value=SETTINGS.default_provider,
+            )
+            model_name = gr.Textbox(
+                label="Model name",
+                value=SETTINGS.default_model,
+                placeholder=(
+                    "e.g., gpt-5 / gpt-4o / claude-3-5-sonnet-20240620 / gemini-1.5-pro"
+                ),
+            )
+        with gr.Row():
+            provider_token = gr.Textbox(
+                label="Provider API Token",
+                type="password",
+            )
+            github_token = gr.Textbox(
+                label="GitHub Token",
+                type="password",
+            )
+        with gr.Row():
+            original_path = gr.Textbox(
+                label="Original File Path (in repo)",
+                placeholder="docs/source/en/xxx.md",
+            )
+            translated_path = gr.Textbox(
+                label="Translated File Path (in repo)",
+                placeholder="docs/source/ko/xxx.md",
+            )
+
+        gr.Markdown("---")
+
+        # Tool 1: Prepare
+        with gr.Accordion(
+            "Tool 1: Prepare (Fetch Files + Build Prompts)", open=False
+        ):
+            prepare_btn = gr.Button("tool_prepare")
+            prepare_out = gr.JSON(label="Prepare result (files + prompts)")
+
+            prepare_btn.click(
+                fn=tool_prepare,
+                inputs=[github_token, pr_url, original_path, translated_path],
+                outputs=[prepare_out],
+            )
+
+        # Tool 2: Review + Emit Payload
+        with gr.Accordion("Tool 2: Review + Emit Payload", open=False):
+            review_btn = gr.Button("tool_review_and_emit")
+
+            original_text = gr.Textbox(
+                label="Original (for review)",
+                lines=6,
+            )
+            translated_text = gr.Textbox(
+                label="Translated (for review)",
+                lines=10,
+            )
+
+            review_out = gr.JSON(
+                label="Review result (verdict/summary/comments/event)"
+            )
+            payload_out = gr.JSON(label="Payload JSON (for GitHub)")
+
+            def _review_emit_proxy(
+                provider_: str,
+                provider_token_: str,
+                model_name_: str,
+                pr_url_: str,
+                translated_path_: str,
+                original_text_: str,
+                translated_text_: str,
+            ):
+                result = tool_review_and_emit(
+                    provider=provider_,
+                    provider_token=provider_token_,
+                    model_name=model_name_,
+                    pr_url=pr_url_,
+                    translated_path=translated_path_,
+                    original=original_text_,
+                    translated=translated_text_,
+                )
+                return result, result.get("payload", {})
+
+            review_btn.click(
+                fn=_review_emit_proxy,
+                inputs=[
+                    provider,
+                    provider_token,
+                    model_name,
+                    pr_url,
+                    translated_path,
+                    original_text,
+                    translated_text,
+                ],
+                outputs=[review_out, payload_out],
+            )
+
+        # Tool 3: Submit Review
+        with gr.Accordion("Tool 3: Submit Review", open=False):
+            submit_btn = gr.Button("tool_submit_review")
+            payload_in = gr.Textbox(
+                label="Payload or Review JSON (from Tool 2)",
+                lines=6,
+            )
+            submit_out = gr.JSON(label="Submission result")
+
+            def _submit_proxy(
+                github_token_: str,
+                pr_url_: str,
+                translated_path_: str,
+                payload_json_: str,
+            ):
+                try:
+                    payload_obj = json.loads(payload_json_) if payload_json_ else {}
+                except Exception as e:
+                    raise ValueError(f"Invalid JSON: {e}")
+                return tool_submit_review(
+                    github_token=github_token_,
+                    pr_url=pr_url_,
+                    translated_path=translated_path_,
+                    payload_or_review=payload_obj,
+                    allow_self_request_changes=True,
+                )
+
+            submit_btn.click(
+                fn=_submit_proxy,
+                inputs=[github_token, pr_url, translated_path, payload_in],
+                outputs=[submit_out],
+            )
+
+        gr.Markdown("---")
+
+        # Tool 4: End-to-End
+        with gr.Accordion("Tool 4: End-to-End", open=True):
+            e2e_btn = gr.Button("tool_end_to_end")
+            save_review = gr.Checkbox(
+                label="Save review JSON to file", value=True
+            )
+            save_path = gr.Textbox(
+                label="Save path", value="review.json"
+            )
+            submit_flag = gr.Checkbox(
+                label="Submit to GitHub", value=False
+            )
+            e2e_out = gr.JSON(label="E2E result")
+
+            e2e_btn.click(
+                fn=tool_end_to_end,
+                inputs=[
+                    provider,
+                    provider_token,
+                    model_name,
+                    github_token,
+                    pr_url,
+                    original_path,
+                    translated_path,
+                    save_review,
+                    save_path,
+                    submit_flag,
+                ],
+                outputs=[e2e_out],
+            )
+
+        gr.Markdown(
+            """
+            **Notes**
+            - Tool 1: PR에서 파일을 읽고 프롬프트까지 준비합니다.
+            - Tool 2: LLM으로 리뷰한 뒤, GitHub 리뷰 payload까지 생성합니다.
+            - Tool 3: Tool 2에서 만든 payload JSON을 그대로 넣고 GitHub에 전송합니다.
+            - Tool 4: 파일 로드부터 리뷰/저장/제출까지 한 번에 처리하는 end-to-end 툴입니다.
+            - `launch(mcp_server=True)` 이므로 각 `tool_*` 버튼은 MCP 툴로도 사용 가능합니다.
+            """
+        )
+    return demo
+
+
+if __name__ == "__main__":
+    ui = build_ui()
+    ui.launch(
+        share=SETTINGS.ui_share,
+        mcp_server=SETTINGS.ui_launch_mcp_server,
+    )

external/mcp-servers/hf-translation-reviewer/configs/default.yaml

@@ -0,0 +1,11 @@
+provider:
+  default: "openai"
+  model: "gpt-5"
+
+github:
+  api_base: "https://api.github.com"
+
+ui:
+  title: "LLM Translation Reviewer (PR) — MCP Tools"
+  share: true
+  launch_mcp_server: true

external/mcp-servers/hf-translation-reviewer/requirements.txt

@@ -0,0 +1,14 @@
+# Core dependencies
+requests>=2.31.0
+gradio>=5.0.0
+
+# LLM providers (optional, choose what you use)
+openai>=1.12.0
+anthropic>=0.34.0
+google-generativeai>=0.5.0
+
+# Typing helpers (optional, for static analysis)
+typing-extensions>=4.8.0
+
+# Python version note
+# Python >=3.9 recommended

external/mcp-servers/hf-translation-reviewer/services.py

@@ -0,0 +1,575 @@
+from __future__ import annotations
+
+import json
+import re
+import textwrap
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from urllib.parse import urlparse
+
+import requests
+
+from setting import SETTINGS
+from adapters import github_request, fetch_file_from_pr, dispatch_review
+
+
+PROMPT_TEMPLATE = textwrap.dedent(
+    """
+    You are a meticulous bilingual reviewer checking a translation PR.
+
+    PR number: {pr_number}
+    PR URL: {pr_url}
+
+    Review the translated text against the original and focus on:
+    1. Are there any typos or spelling mistakes?
+    2. Are any sentences difficult to understand?
+    3. Is the overall content hard to comprehend?
+
+    Always respond with strict JSON using this schema:
+    {{
+      "verdict": "request_changes" | "comment" | "approve",
+      "summary": "<High-level Markdown summary of the review findings>",
+      "comments": [
+        {{
+          "line": <1-based line number in the translated file>,
+          "issue": "<Short Markdown description of the problem>",
+          "suggested_edit": "<Replacement text for the entire translated line>",
+          "context": "<Exact current text of that line for grounding>"
+        }},
+        ...
+      ]
+    }}
+
+    Guidelines:
+    - Only include comments for issues that warrant direct feedback.
+    - When a concrete rewrite is possible, populate "suggested_edit" with the full replacement line exactly as it should appear after fixing the issue.
+    - Keep edits scoped to the referenced line; do not span multiple lines.
+    - Always copy the current text of that line verbatim into "context".
+    - Omit the "suggested_edit" field or set it to an empty string if no suggestion is available.
+    - Use "request_changes" when the identified problems must be fixed before merging.
+    - Use "approve" only when the translation is correct and clear with no changes needed.
+    - For optional improvements or general observations, use "comment".
+    - Keep suggestions tightly scoped so they can be applied as GitHub suggestions.
+    - Do not output partial fragments in "suggested_edit"; always provide the entire replacement line including unchanged portions.
+    - Use the line numbers from the "TRANSLATED TEXT WITH LINE NUMBERS" section.
+    """
+).strip()
+
+
+# --------------------- Core helpers ------------------
+
+
+def parse_pr_url(pr_url: str) -> Tuple[str, int]:
+    """Extract repo (owner/name) and PR number from a GitHub PR URL."""
+    if not pr_url:
+        raise ValueError("PR URL is required")
+    parsed = urlparse(pr_url)
+    parts = [p for p in parsed.path.split("/") if p]
+    # Expect: [owner, repo, 'pull', pr_number, ...]
+    if len(parts) < 4 or parts[2] != "pull":
+        raise ValueError(f"Not a valid GitHub PR URL: {pr_url}")
+    owner, repo, _, num = parts[0], parts[1], parts[2], parts[3]
+    if not num.isdigit():
+        raise ValueError(f"PR number not found in URL: {pr_url}")
+    return f"{owner}/{repo}", int(num)
+
+
+def add_line_numbers(text: str) -> str:
+    return "\n".join(f"{i:04d}: {line}" for i, line in enumerate(text.splitlines(), 1))
+
+
+def load_pr_files(
+    github_token: str,
+    pr_url: str,
+    original_path: str,
+    translated_path: str,
+) -> Tuple[str, int, str, str]:
+    repo_name, pr_number = parse_pr_url(pr_url)
+    pr_api = f"{SETTINGS.github_api_base}/repos/{repo_name}/pulls/{pr_number}"
+    pr_data = github_request(pr_api, github_token)
+    head_sha = pr_data.get("head", {}).get("sha")
+    if not head_sha:
+        raise RuntimeError(f"Unable to determine head SHA for PR {pr_number} in {repo_name}.")
+    original = fetch_file_from_pr(repo_name, pr_number, original_path, head_sha, github_token)
+    translated = fetch_file_from_pr(repo_name, pr_number, translated_path, head_sha, github_token)
+    return repo_name, pr_number, original, translated
+
+
+def build_messages(
+    original: str,
+    translated: str,
+    pr_number: int,
+    pr_url: str,
+) -> Tuple[str, str]:
+    system_prompt = (
+        "You are an expert translation reviewer ensuring clarity, accuracy, "
+        "and readability of localized documentation."
+    )
+    user_prompt = (
+        f"{PROMPT_TEMPLATE}\n\n"
+        "----- ORIGINAL TEXT -----\n"
+        f"{original}\n\n"
+        "----- TRANSLATED TEXT -----\n"
+        f"{translated}\n\n"
+        "----- TRANSLATED TEXT WITH LINE NUMBERS -----\n"
+        f"{add_line_numbers(translated)}"
+    )
+    return system_prompt, user_prompt
+
+
+def normalize_summary_for_body(summary: str) -> str:
+    """
+    GitHub review body로 쓸 텍스트 정리.
+    """
+    s = (summary or "").strip()
+    if not s:
+        return "LLM translation review"
+
+    if s.startswith("{") or s.startswith("["):
+        try:
+            obj = json.loads(s)
+            if isinstance(obj, dict):
+                inner = obj.get("summary")
+                if isinstance(inner, str) and inner.strip():
+                    return inner.strip()
+        except Exception:
+            return s
+
+    return s
+
+
+# ----------------------- Parsing & GitHub glue ----------------------
+
+
+def _extract_json_candidates(raw_response: str) -> List[str]:
+    candidates: List[str] = []
+    for match in re.finditer(r"```(?:json)?\s*(\{.*?\})\s*```", raw_response, re.DOTALL):
+        snippet = match.group(1).strip()
+        if snippet:
+            candidates.append(snippet)
+    stripped = raw_response.strip()
+    if stripped:
+        candidates.append(stripped)
+    return candidates
+
+
+def parse_review_response(raw_response: str) -> Tuple[str, str, List[Dict[str, object]]]:
+    parsed: Optional[Dict[str, object]] = None
+    for candidate in _extract_json_candidates(raw_response):
+        try:
+            parsed_candidate = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed_candidate, dict):
+            parsed = parsed_candidate
+            break
+    if parsed is None:
+        return "comment", raw_response.strip(), []
+
+    verdict = parsed.get("verdict", "comment")
+    summary = parsed.get("summary", "").strip()
+    comments = parsed.get("comments", [])
+
+    if not isinstance(verdict, str):
+        verdict = "comment"
+    verdict = verdict.lower()
+    if verdict not in {"request_changes", "comment", "approve"}:
+        verdict = "comment"
+
+    if not summary:
+        summary = raw_response.strip()
+
+    if not isinstance(comments, list):
+        comments = []
+
+    normalized_comments: List[Dict[str, object]] = []
+    for comment in comments:
+        if not isinstance(comment, dict):
+            continue
+        line = comment.get("line")
+        issue = comment.get("issue", "").strip()
+        suggested_edit = comment.get("suggested_edit", "").strip()
+        context = comment.get("context", "").strip()
+        if not isinstance(line, int) or line <= 0:
+            continue
+        if not issue:
+            continue
+        normalized_comments.append(
+            {
+                "line": line,
+                "issue": issue,
+                "suggested_edit": suggested_edit,
+                "context": context,
+            }
+        )
+    return verdict, summary, normalized_comments
+
+
+def review_event_from_verdict(verdict: str) -> str:
+    return {
+        "request_changes": "REQUEST_CHANGES",
+        "comment": "COMMENT",
+        "approve": "APPROVE",
+    }.get(verdict, "COMMENT")
+
+
+def build_review_comments(
+    translated_path: str,
+    comments: List[Dict[str, object]],
+) -> List[Dict[str, object]]:
+    review_comments: List[Dict[str, object]] = []
+    for comment in comments:
+        line = int(comment["line"])
+        issue = str(comment["issue"]).strip()
+        raw_suggested = comment.get("suggested_edit", "")
+        if isinstance(raw_suggested, str):
+            suggested_edit = raw_suggested.rstrip("\r\n")
+        else:
+            suggested_edit = str(raw_suggested).rstrip("\r\n") if raw_suggested else ""
+        context = str(comment.get("context", "")).rstrip("\n")
+        full_line_suggestion = suggested_edit.rstrip("\n") if suggested_edit else ""
+
+        body_parts = [issue]
+        if context:
+            body_parts.append(f"> _Current text_: {context}")
+        if full_line_suggestion:
+            body_parts.append("```suggestion\n" + full_line_suggestion + "\n```")
+
+        body = "\n\n".join(body_parts).strip()
+        review_comments.append(
+            {
+                "path": translated_path,
+                "side": "RIGHT",
+                "line": line,
+                "body": body,
+            }
+        )
+    return review_comments
+
+
+def attach_translated_line_context(
+    translated_text: str,
+    comments: List[Dict[str, object]],
+) -> None:
+    if not comments:
+        return
+    lines = translated_text.splitlines()
+    for comment in comments:
+        line_idx = comment.get("line")
+        if not isinstance(line_idx, int):
+            continue
+        list_index = line_idx - 1
+        if list_index < 0 or list_index >= len(lines):
+            continue
+        current_line = lines[list_index].rstrip("\n")
+        if not comment.get("context"):
+            comment["context"] = current_line
+
+
+def build_github_review_payload(
+    body: str,
+    event: str = "COMMENT",
+    comments: Optional[List[Dict[str, object]]] = None,
+) -> Dict[str, object]:
+    payload: Dict[str, object] = {"event": event, "body": body}
+    if comments:
+        payload["comments"] = comments
+    return payload
+
+
+def submit_pr_review(
+    repo_name: str,
+    pr_number: int,
+    github_token: str,
+    body: str,
+    event: str,
+    comments: Optional[List[Dict[str, object]]] = None,
+    allow_self_request_changes: bool = True,
+) -> Tuple[Dict, str]:
+    """
+    GitHub PR 리뷰 전송 (self-review REQUEST_CHANGES 우회 포함).
+    """
+    url = f"{SETTINGS.github_api_base}/repos/{repo_name}/pulls/{pr_number}/reviews"
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "Authorization": f"token {github_token}",
+    }
+
+    def _post(event_to_use: str, body_to_use: str) -> requests.Response:
+        payload = build_github_review_payload(
+            body=body_to_use,
+            event=event_to_use,
+            comments=comments,
+        )
+        return requests.post(url, headers=headers, json=payload, timeout=30)
+
+    # 1차 요청
+    response = _post(event, body)
+
+    if response.status_code == 401:
+        raise PermissionError(
+            "GitHub token is invalid or lacks permission to submit a review."
+        )
+
+    # 본인 PR + REQUEST_CHANGES 케이스 처리
+    if response.status_code == 422 and event == "REQUEST_CHANGES":
+        try:
+            error_payload = response.json()
+        except ValueError:
+            error_payload = {"message": response.text}
+        message = str(error_payload.get("message", ""))
+        errors = " ".join(str(item) for item in error_payload.get("errors", []))
+        combined_error = f"{message} {errors}".strip()
+
+        if "own pull request" in combined_error.lower():
+            if not allow_self_request_changes:
+                raise RuntimeError(
+                    "GitHub does not allow REQUEST_CHANGES on your own pull request: "
+                    + combined_error
+                )
+
+            fallback_event = "COMMENT"
+            fallback_body = "[REQUEST_CHANGES (self-review)]\n\n" + (body or "").strip()
+
+            comment_response = _post(fallback_event, fallback_body)
+            if comment_response.status_code >= 400:
+                raise RuntimeError(
+                    "Failed to submit fallback self-review comment: "
+                    f"HTTP {comment_response.status_code} - {comment_response.text}"
+                )
+            return comment_response.json(), "REQUEST_CHANGES_SELF"
+
+    if response.status_code >= 400:
+        raise RuntimeError(
+            "Failed to submit review: "
+            f"HTTP {response.status_code} - {response.text}"
+        )
+
+    return response.json(), event
+
+
+# --------------------- High-level domain services ------------------
+
+
+def prepare_translation_context(
+    github_token: str,
+    pr_url: str,
+    original_path: str,
+    translated_path: str,
+) -> Dict[str, object]:
+    """
+    PR에서 파일을 가져와 system/user prompt까지 구성.
+    """
+    repo_name, pr_number, original, translated = load_pr_files(
+        github_token=github_token,
+        pr_url=pr_url,
+        original_path=original_path,
+        translated_path=translated_path,
+    )
+    system_prompt, user_prompt = build_messages(
+        original=original,
+        translated=translated,
+        pr_number=pr_number,
+        pr_url=pr_url,
+    )
+    return {
+        "repo": repo_name,
+        "pr_number": pr_number,
+        "original": original,
+        "translated": translated,
+        "system_prompt": system_prompt,
+        "user_prompt": user_prompt,
+    }
+
+
+def review_and_emit_payload(
+    provider: str,
+    provider_token: str,
+    model_name: str,
+    pr_url: str,
+    translated_path: str,
+    original: str,
+    translated: str,
+) -> Dict[str, object]:
+    """
+    LLM 리뷰 수행 후 verdict / summary / comments 및 GitHub payload 생성.
+    """
+    _, pr_number = parse_pr_url(pr_url)
+    system_prompt, user_prompt = build_messages(
+        original=original,
+        translated=translated,
+        pr_number=pr_number,
+        pr_url=pr_url,
+    )
+
+    raw = dispatch_review(
+        provider=provider,
+        token=provider_token,
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        model_name=model_name,
+    )
+    verdict, summary, comments = parse_review_response(raw)
+    attach_translated_line_context(translated, comments)
+
+    event = review_event_from_verdict(verdict)
+    github_comments = build_review_comments(translated_path, comments)
+    payload = build_github_review_payload(
+        body=summary,
+        event=event,
+        comments=github_comments,
+    )
+
+    return {
+        "verdict": verdict,
+        "summary": summary,
+        "comments": comments,
+        "event": event,
+        "payload": payload,
+    }
+
+
+def submit_review_to_github(
+    github_token: str,
+    pr_url: str,
+    translated_path: str,
+    payload_or_review: Dict[str, object],
+    allow_self_request_changes: bool = True,
+) -> Dict[str, object]:
+    """
+    payload JSON 또는 review JSON을 입력받아 GitHub 리뷰 제출.
+    """
+    repo, pr_number = parse_pr_url(pr_url)
+
+    event = payload_or_review.get("event")
+    body = payload_or_review.get("body")
+    comments_obj = payload_or_review.get("comments")
+
+    comments: Optional[List[Dict[str, object]]] = None
+
+    if isinstance(event, str) and body:
+        # 이미 GitHub payload 형식
+        event_str = event
+        if isinstance(comments_obj, list):
+            comments = comments_obj
+        body_str = str(body)
+    else:
+        # review 형식 (verdict/summary/comments)
+        verdict = str(payload_or_review.get("verdict", "comment")).lower()
+        summary = str(payload_or_review.get("summary", "")).strip()
+        review_comments = payload_or_review.get("comments", [])
+        if not isinstance(review_comments, list):
+            review_comments = []
+
+        event_str = review_event_from_verdict(verdict)
+        body_str = summary if summary else "LLM translation review"
+        comments = build_review_comments(translated_path, review_comments)
+
+    if event_str == "REQUEST_CHANGES" and not body_str.strip() and not comments:
+        raise ValueError(
+            "REQUEST_CHANGES를 보내려면 review 본문 또는 코멘트가 하나 이상 필요합니다."
+        )
+
+    response, final_event = submit_pr_review(
+        repo_name=repo,
+        pr_number=pr_number,
+        github_token=github_token,
+        body=body_str,
+        event=event_str,
+        comments=comments,
+        allow_self_request_changes=allow_self_request_changes,
+    )
+    return {
+        "final_event": final_event,
+        "response": response,
+    }
+
+
+def run_end_to_end(
+    provider: str,
+    provider_token: str,
+    model_name: str,
+    github_token: str,
+    pr_url: str,
+    original_path: str,
+    translated_path: str,
+    save_review: bool = False,
+    save_path: str = "review.json",
+    submit_review_flag: bool = False,
+) -> Dict[str, object]:
+    repo, pr_number, original, translated = load_pr_files(
+        github_token=github_token,
+        pr_url=pr_url,
+        original_path=original_path,
+        translated_path=translated_path,
+    )
+
+    system_prompt, user_prompt = build_messages(
+        original=original,
+        translated=translated,
+        pr_number=pr_number,
+        pr_url=pr_url,
+    )
+
+    raw = dispatch_review(
+        provider=provider,
+        token=provider_token,
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        model_name=model_name,
+    )
+
+    verdict, summary, comments = parse_review_response(raw)
+    attach_translated_line_context(translated, comments)
+
+    body_for_github = normalize_summary_for_body(summary)
+
+    github_comments = build_review_comments(translated_path, comments)
+    event = review_event_from_verdict(verdict)
+    payload = build_github_review_payload(
+        body=body_for_github,
+        event=event,
+        comments=github_comments,
+    )
+
+    saved_file_path: Optional[str] = None
+    if save_review:
+        p = Path(save_path).expanduser()
+        p.write_text(
+            json.dumps(
+                {
+                    "verdict": verdict,
+                    "summary": summary,
+                    "comments": comments,
+                },
+                ensure_ascii=False,
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        saved_file_path = str(p)
+
+    submission = None
+    if submit_review_flag:
+        resp, final_event = submit_pr_review(
+            repo_name=repo,
+            pr_number=pr_number,
+            github_token=github_token,
+            body=body_for_github,
+            event=event,
+            comments=github_comments,
+            allow_self_request_changes=True,
+        )
+        submission = {"final_event": final_event, "response": resp}
+
+    return {
+        "repo": repo,
+        "pr_number": pr_number,
+        "verdict": verdict,
+        "summary": summary,
+        "comments": comments,
+        "payload": payload,
+        "saved_file": saved_file_path,
+        "submission": submission,
+    }

external/mcp-servers/hf-translation-reviewer/setting.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import os
+
+try:
+    import yaml  # type: ignore
+except Exception:
+    yaml = None
+
+
+@dataclass
+class AppSettings:
+    default_provider: str = "openai"
+    default_model: str = "gpt-5"
+    github_api_base: str = "https://api.github.com"
+    ui_title: str = "LLM Translation Reviewer (PR) — MCP Tools"
+    ui_share: bool = True
+    ui_launch_mcp_server: bool = True
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    if not path.is_file():
+        return {}
+    if yaml is None:
+        # yaml 없으면 config 없이 동작
+        return {}
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def load_settings(config_path: str = "configs/default.yaml") -> AppSettings:
+    cfg_path = Path(config_path)
+    data = _load_yaml(cfg_path)
+
+    provider_cfg = data.get("provider", {}) if isinstance(data.get("provider"), dict) else {}
+    github_cfg = data.get("github", {}) if isinstance(data.get("github"), dict) else {}
+    ui_cfg = data.get("ui", {}) if isinstance(data.get("ui"), dict) else {}
+
+    default_provider = os.getenv("DEFAULT_PROVIDER", provider_cfg.get("default", "openai"))
+    default_model = os.getenv("DEFAULT_MODEL", provider_cfg.get("model", "gpt-5"))
+    github_api_base = os.getenv("GITHUB_API_BASE", github_cfg.get("api_base", "https://api.github.com"))
+    ui_title = ui_cfg.get("title", "LLM Translation Reviewer (PR) — MCP Tools")
+    ui_share = bool(ui_cfg.get("share", True))
+    ui_launch_mcp_server = bool(ui_cfg.get("launch_mcp_server", True))
+
+    return AppSettings(
+        default_provider=default_provider,
+        default_model=default_model,
+        github_api_base=github_api_base,
+        ui_title=ui_title,
+        ui_share=ui_share,
+        ui_launch_mcp_server=ui_launch_mcp_server,
+    )
+
+
+# 전역 설정 인스턴스
+SETTINGS: AppSettings = load_settings()

external/mcp-servers/hf-translation-reviewer/tools.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from services import (
+    prepare_translation_context,
+    review_and_emit_payload,
+    submit_review_to_github,
+    run_end_to_end,
+)
+
+
+def tool_prepare(
+    github_token: str,
+    pr_url: str,
+    original_path: str,
+    translated_path: str,
+) -> Dict[str, object]:
+    """
+    Tool 1: Fetch Files + Build Prompts
+    """
+    return prepare_translation_context(
+        github_token=github_token,
+        pr_url=pr_url,
+        original_path=original_path,
+        translated_path=translated_path,
+    )
+
+
+def tool_review_and_emit(
+    provider: str,
+    provider_token: str,
+    model_name: str,
+    pr_url: str,
+    translated_path: str,
+    original: str,
+    translated: str,
+) -> Dict[str, object]:
+    """
+    Tool 2: LLM Review + Emit Payload
+    """
+    return review_and_emit_payload(
+        provider=provider,
+        provider_token=provider_token,
+        model_name=model_name,
+        pr_url=pr_url,
+        translated_path=translated_path,
+        original=original,
+        translated=translated,
+    )
+
+
+def tool_submit_review(
+    github_token: str,
+    pr_url: str,
+    translated_path: str,
+    payload_or_review: Dict[str, object],
+    allow_self_request_changes: bool = True,
+) -> Dict[str, object]:
+    """
+    Tool 3: Submit Review
+    """
+    return submit_review_to_github(
+        github_token=github_token,
+        pr_url=pr_url,
+        translated_path=translated_path,
+        payload_or_review=payload_or_review,
+        allow_self_request_changes=allow_self_request_changes,
+    )
+
+
+def tool_end_to_end(
+    provider: str,
+    provider_token: str,
+    model_name: str,
+    github_token: str,
+    pr_url: str,
+    original_path: str,
+    translated_path: str,
+    save_review: bool = False,
+    save_path: str = "review.json",
+    submit_review_flag: bool = False,
+) -> Dict[str, object]:
+    """
+    Tool 4: End-to-End
+    """
+    return run_end_to_end(
+        provider=provider,
+        provider_token=provider_token,
+        model_name=model_name,
+        github_token=github_token,
+        pr_url=pr_url,
+        original_path=original_path,
+        translated_path=translated_path,
+        save_review=save_review,
+        save_path=save_path,
+        submit_review_flag=submit_review_flag,
+    )