mcp-gitlab-explorer 0.1.0__py3-none-any.whl

mcp_gitlab_explorer/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-gitlab-explorer: GitLab user push activity MCP server."""
+
+__version__ = "0.1.0"

mcp_gitlab_explorer/gitlab_client.py

@@ -0,0 +1,209 @@
+"""GitLab REST API client (PRIVATE-TOKEN auth)."""
+
+from __future__ import annotations
+
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_GITLAB_URL = "http://gitlab.beisencorp.com"
+API_PREFIX = "/api/v4"
+EVENTS_PAGE_SIZE = 100  # events 分页步长,GitLab per_page 上限 100
+EVENTS_MAX_PAGES = 200  # events 分页保护上限,防死循环(3 个月数据远触不到)
+PROJECT_CONCURRENCY = 10  # 并发查 project 详情的线程数
+REQUEST_MAX_RETRIES = 3  # 429 / 网络错误重试次数
+
+
+class GitLabAuthError(RuntimeError):
+    """Token 缺失或失效。"""
+
+
+class GitLabNotFoundError(RuntimeError):
+    """资源不存在(404)。"""
+
+
+def _seg(value: Any) -> str:
+    """URL-encode a single path segment."""
+    return quote(str(value), safe="")
+
+
+class GitLabClient:
+    """通过 PRIVATE-TOKEN 访问 GitLab REST API。
+
+    持有一个长生命周期的 httpx.Client(连接池复用):单次工具调用内所有请求
+    (含并发查 project)共享连接池,避免反复 TCP/TLS 握手。httpx.Client 线程
+    安全,可被 ThreadPoolExecutor 多线程共享。project 详情额外做进程内缓存,
+    同一 project 只查一次(项目元数据基本不变)。
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 20.0,
+    ) -> None:
+        self.base_url = (
+            base_url
+            or os.environ.get("GITLAB_URL")
+            or DEFAULT_GITLAB_URL
+        ).rstrip("/")
+        self.token = (token or os.environ.get("GITLAB_PRIVATE_TOKEN", "")).strip()
+        if not self.token:
+            raise GitLabAuthError("Missing GITLAB_PRIVATE_TOKEN environment variable.")
+        self.timeout = timeout
+        self._client = httpx.Client(
+            timeout=timeout,
+            follow_redirects=False,
+            limits=httpx.Limits(
+                max_keepalive_connections=PROJECT_CONCURRENCY * 2,
+                max_connections=PROJECT_CONCURRENCY * 2,
+            ),
+        )
+        self._project_cache: dict[int, dict] = {}
+
+    def _headers(self) -> dict[str, str]:
+        return {"PRIVATE-TOKEN": self.token, "Accept": "application/json"}
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """统一 GET:401/403->AuthError,404->NotFoundError,429->重试,>=4xx->RuntimeError。
+
+        429 优先读 Retry-After(秒),否则指数退避;网络错误同样重试。
+        重试耗尽抛 RuntimeError。token 失效/404 不重试(立即抛出)。
+        """
+        url = f"{self.base_url}{API_PREFIX}{path}"
+        for attempt in range(REQUEST_MAX_RETRIES):
+            try:
+                resp = self._client.get(
+                    url,
+                    headers=self._headers(),
+                    params=params,
+                    timeout=self.timeout,
+                )
+            except httpx.RequestError as exc:
+                if attempt < REQUEST_MAX_RETRIES - 1:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise RuntimeError(f"GitLab request failed: {exc}") from exc
+
+            if resp.status_code in (401, 403):
+                raise GitLabAuthError(
+                    f"GitLab auth failed (HTTP {resp.status_code}). Token invalid or expired."
+                )
+            if resp.status_code == 404:
+                raise GitLabNotFoundError(f"GitLab 404: {path}")
+            if resp.status_code == 429:
+                retry_after = resp.headers.get("Retry-After")
+                try:
+                    wait = float(retry_after) if retry_after else 2 ** (attempt + 1)
+                except ValueError:
+                    wait = 2 ** (attempt + 1)
+                time.sleep(min(wait, 30.0))
+                continue
+            if resp.status_code >= 400:
+                raise RuntimeError(f"GitLab HTTP {resp.status_code}: {resp.text[:200]}")
+            try:
+                return resp.json()
+            except ValueError:
+                return resp.text
+        raise RuntimeError(
+            f"GitLab request failed after {REQUEST_MAX_RETRIES} retries (429): {path}"
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> GitLabClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ---- events --------------------------------------------------------------
+
+    def list_pushed_events(
+        self,
+        user: int | str,
+        after: str,
+        before: str,
+        max_pages: int = EVENTS_MAX_PAGES,
+    ) -> list[dict]:
+        """分页拉取用户 pushed 事件,返回原始事件列表(GitLab 默认按时间倒序)。
+
+        GET /users/:id/events?action=pushed&after=&before=&per_page=100&page=N
+        page 1-based;三重终止: 空页 / 本页未满 / 触及 max_pages。
+        :id 路径段接受数字 id 或 username。
+
+        after/before 均为 YYYY-MM-DD,按 UTC 解释,均含当天(闭区间 [after, before])。
+        """
+        all_events: list[dict] = []
+        page = 1
+        while page <= max_pages:
+            data = self._get(
+                f"/users/{_seg(user)}/events",
+                params={
+                    "action": "pushed",
+                    "after": after,
+                    "before": before,
+                    "per_page": EVENTS_PAGE_SIZE,
+                    "page": page,
+                    "sort": "desc",
+                },
+            )
+            if not isinstance(data, list):
+                break
+            if not data:
+                break
+            all_events.extend(e for e in data if isinstance(e, dict))
+            if len(data) < EVENTS_PAGE_SIZE:
+                break
+            page += 1
+        return all_events
+
+    # ---- project(并发 + 缓存) ------------------------------------------------
+
+    def _fetch_project(self, project_id: int | str) -> dict:
+        """查单个 project 详情;404(已删除/无权限)容错为 {_missing: True}。
+
+        其它异常(含 429 重试耗尽、5xx)向上冒泡,由并发层兜底记 _error。
+        """
+        try:
+            return self._get(f"/projects/{_seg(project_id)}")
+        except GitLabNotFoundError:
+            return {"id": project_id, "_missing": True}
+
+    def get_projects_concurrent(
+        self,
+        project_ids: list[int],
+        max_workers: int = PROJECT_CONCURRENCY,
+    ) -> dict[int, dict]:
+        """并发查 project 详情,返回 {project_id: project_dict}。
+
+        - 进程内缓存:同一 project 只查一次(命中缓存零开销)
+        - 线程池并发:httpx.Client 线程安全,共享连接池
+        - 404 容错:已删除/无权限的项目记 {_missing: True},不抛错
+        - 其它异常记 {_error: str},不影响其它 project
+        """
+        unique_ids: list[int] = list(
+            dict.fromkeys(pid for pid in project_ids if pid is not None)
+        )
+        miss = [pid for pid in unique_ids if pid not in self._project_cache]
+        if miss:
+            workers = max(1, min(max_workers, len(miss)))
+            with ThreadPoolExecutor(max_workers=workers) as pool:
+                future_to_pid = {
+                    pool.submit(self._fetch_project, pid): pid for pid in miss
+                }
+                for fut in as_completed(future_to_pid):
+                    pid = future_to_pid[fut]
+                    try:
+                        self._project_cache[pid] = fut.result()
+                    except Exception as exc:  # noqa: BLE001
+                        self._project_cache[pid] = {"id": pid, "_error": str(exc)}
+        return {
+            pid: self._project_cache.get(pid, {"id": pid, "_error": "unknown"})
+            for pid in unique_ids
+        }

mcp_gitlab_explorer/server.py

@@ -0,0 +1,126 @@
+"""MCP server for GitLab user push activity (PRIVATE-TOKEN auth)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_gitlab_explorer.gitlab_client import GitLabClient
+
+mcp = FastMCP("mcp-gitlab-explorer")
+
+
+def _client() -> GitLabClient:
+    """从环境变量构造 client(token / base_url)。单次调用内复用连接池。"""
+    return GitLabClient()
+
+
+# ---- 聚合 helper -----------------------------------------------------------
+# 纯函数,不依赖网络,便于单测。pushed event 的 project_id 在顶层;
+# push_data.ref 为分支/tag 名。
+
+
+def _event_project_id(ev: dict) -> Any:
+    """从 pushed event 取 project_id。
+
+    正常 push event 顶层即 project_id;兜底看 target_type=project 时的 target_id。
+    """
+    pid = ev.get("project_id")
+    if pid is None:
+        tgt = ev.get("target_id")
+        if tgt and ev.get("target_type") == "project":
+            pid = tgt
+    return pid
+
+
+def _aggregate_by_project(events: list[dict]) -> dict[int, dict]:
+    """把 pushed events 按 project_id 聚合:
+
+    - push_count: 该仓库被 push 的次数(仅用于排序,不输出)
+    - branches: 时间范围内推送过的分支/tag 名集合
+    - last_push_at: 最近一次 push 时间(created_at,ISO8601 字典序=时间序)
+    """
+    by_project: dict[int, dict] = {}
+    for ev in events:
+        pid = _event_project_id(ev)
+        if pid is None:
+            continue
+        entry = by_project.setdefault(
+            pid, {"push_count": 0, "branches": set(), "last_push_at": ""}
+        )
+        entry["push_count"] += 1
+        ref = (ev.get("push_data") or {}).get("ref")
+        if ref:
+            entry["branches"].add(ref)
+        created = ev.get("created_at") or ""
+        if created > entry["last_push_at"]:
+            entry["last_push_at"] = created
+    return by_project
+
+
+@mcp.tool()
+def gitlab_user_pushed_repos(
+    user: int | str,
+    after: str,
+    before: str,
+) -> dict[str, Any]:
+    """查询指定用户在某时间范围内 push 过代码的仓库列表。
+
+    先分页拉取 /users/:id/events?action=pushed,按 project_id 聚合后并发查
+    仓库详情(连接池复用 + 进程内缓存),返回去重仓库列表。
+
+    Args:
+        user: GitLab 用户 id 或 username(均支持,直接作为 /users/:id 路径段)
+        after: 起始日期 YYYY-MM-DD(含)
+        before: 结束日期 YYYY-MM-DD(含,闭区间 [after, before])
+
+    Returns:
+        {user, after, before, total_events, repo_count,
+         repos:[{name, web_url, branches, last_push_at, missing}]}
+        repos 按 push 次数倒序(活跃仓库在前);branches 为时间范围内推送过的
+        分支/tag 列表;last_push_at 为最近一次 push 时间(ISO8601);
+        missing=true 表示仓库已删除或 token 无权限查看(此时 name/web_url 为 null)。
+
+    注意:
+        - 适合查近 3 个月内的数据;GitLab events 有保留期,更早的历史可能查不到
+        - after/before 按 UTC 日期解释,跨时区边界可能有 1 天偏差
+    """
+    with _client() as client:
+        events = client.list_pushed_events(user, after, before)
+        by_project = _aggregate_by_project(events)
+        projects = client.get_projects_concurrent(list(by_project.keys()))
+
+    rows: list[tuple[int, dict[str, Any]]] = []
+    for pid, agg in by_project.items():
+        proj = projects.get(pid) or {}
+        rows.append(
+            (
+                agg["push_count"],
+                {
+                    "name": proj.get("name"),
+                    "web_url": proj.get("web_url"),
+                    "branches": sorted(agg["branches"]),
+                    "last_push_at": agg["last_push_at"],
+                    "missing": bool(proj.get("_missing")),
+                },
+            )
+        )
+    rows.sort(key=lambda x: x[0], reverse=True)
+    repos = [repo for _, repo in rows]
+    return {
+        "user": user,
+        "after": after,
+        "before": before,
+        "total_events": len(events),
+        "repo_count": len(repos),
+        "repos": repos,
+    }
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_gitlab_explorer-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: mcp-gitlab-explorer
+Version: 0.1.0
+Summary: MCP server for GitLab user push activity (which repos a user pushed to in a time range) via PRIVATE-TOKEN
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.2.0

mcp_gitlab_explorer-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_gitlab_explorer/__init__.py,sha256=Yp2uRLEw3ZrSCYdanCwrrL7jZ1sTCR-nqbhKX42kzPQ,88
+mcp_gitlab_explorer/gitlab_client.py,sha256=gQEIpWn1N1rCxTiySHiUyrTVOhVuiOtPg96V3Afn9UM,7852
+mcp_gitlab_explorer/server.py,sha256=a2KzP7QUdbvm__WCAWvHUKonhoBS-s9sGi35y1gy8O8,4202
+mcp_gitlab_explorer-0.1.0.dist-info/METADATA,sha256=kUqK-UyLXXIL5JRNJlbIJMAS3nNA2j4ZWhgX-EIAQlk,262
+mcp_gitlab_explorer-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mcp_gitlab_explorer-0.1.0.dist-info/entry_points.txt,sha256=GWZCH_TWtEl6SS9OZqSMLN25YsF8F6b-72ZDGYwC5qs,72
+mcp_gitlab_explorer-0.1.0.dist-info/RECORD,,

mcp_gitlab_explorer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_gitlab_explorer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-gitlab-explorer = mcp_gitlab_explorer.server:main