Metadata-Version: 2.4
Name: superred-gitlab-report
Version: 0.1.2
Summary: GitLab MCP服务，用于生成GitLab用户活动报告和获取项目列表
Author-email: zhangjiyuan <zhangjiyuan1994@outlook.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: requests>=2.32.5

# SuperRed GitLab Report MCP 服务

本项目实现了一个基于 MCP (Model Context Protocol) 的 GitLab 活动获取服务，可以在 Cherry Studio 等 MCP 客户端中使用，获取 GitLab 用户的活跃记录。

## 功能

- **获取用户活跃记录**：支持按日、周、月、年获取 GitLab 用户的活跃记录

## 环境要求

- Python 3.10+
- GitLab API 访问权限

## 安装

1. 克隆项目：
   ```bash
   git clone <repository-url>
   cd superred-gitlab-report
   ```

2. 安装依赖：
   ```bash
   uv install
   ```

## 配置

### 环境变量

需要设置以下环境变量：

| 环境变量 | 描述 | 示例值 |
|---------|------|-------|
| GITLAB_URL | GitLab 服务地址 | https://gitlab.superred.com.cn/ |
| GITLAB_TOKEN | GitLab 访问令牌 | your_token_here |
| GITLAB_USERNAME | GitLab 用户名 | your_username_here |

### MCP 配置

在 Cherry Studio 等 MCP 客户端中配置：

```json
{
  "mcpServers": {
    "superred-gitlab-report-server": {
      "command": "uv",
      "args": [
        "run",
        "gitlab_server.py"
      ],
      "env": {
        "GITLAB_URL": "https://gitlab.superred.com.cn/",
        "GITLAB_TOKEN": "your_token_here",
        "GITLAB_USERNAME": "your_username_here"
      }
    }
  }
}
```

## 使用

### 运行服务

```bash
# 使用 uv 运行
uv run gitlab_server.py

# 或使用配置的脚本
uv run run-server
```

### 在 Cherry Studio 中使用

```python
# 获取当日活跃记录
activity = get_gitlab_user_activity(time_range="day")

# 获取本周活跃记录
activity = get_gitlab_user_activity(time_range="week")

# 获取本月活跃记录
activity = get_gitlab_user_activity(time_range="month")

# 获取本年活跃记录
activity = get_gitlab_user_activity(time_range="year")

# 自定义用户名和限制
activity = get_gitlab_user_activity(time_range="week", username="your_username", limit=200)
```

## 项目结构

```
superred-gitlab-report/
├── superred_gitlab_report/
│   ├── clients/
│   │   ├── __init__.py
│   │   └── gitlab_client.py        # GitLab API 客户端
│   ├── exceptions/
│   │   ├── __init__.py
│   │   └── gitlab_exceptions.py    # GitLab 异常类
│   ├── services/
│   │   ├── __init__.py
│   │   ├── gitlab_service.py       # GitLab 业务逻辑
│   │   └── mcp_service.py          # MCP 服务接口
│   └── __init__.py
├── gitlab_server.py                # MCP 服务器实现
├── pyproject.toml                  # 项目配置文件
├── README.md                       # 项目说明
└── uv.lock                         # 依赖锁定文件
```

## 工具说明

### get_gitlab_user_activity

**功能**：获取 GitLab 用户活跃记录

**参数**：
- `time_range`：时间范围，可选值：day（日）、week（周）、month（月）、year（年）
- `username`：GitLab 用户名，默认为环境变量中的用户名
- `limit`：返回记录数限制，默认 100

**返回**：
- 用户活跃记录列表，每条记录包含操作名称、目标类型、仓库名称、分支等信息
- 如果发生错误，返回包含 error 字段的字典

## 错误处理

如果缺少必需的环境变量，服务启动时会抛出错误：
```
ValueError: 缺少必需的环境变量: GITLAB_URL, GITLAB_TOKEN, GITLAB_USERNAME
```

确保在启动服务前设置所有必需的环境变量。

## 许可证

MIT
