Convert MCP server submodules to regular directories

.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

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

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"]

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()

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"

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

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

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,  # 필요 없다면 제거 가능
+    }

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()

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),
+    )