README.md•11.6 kB
# GitLab WeChat MCP 工具
一个用于获取 GitLab 代码提交记录并发送到企业微信的 MCP (Model Context Protocol) 工具。
## 功能特性
- 🔍 **获取 GitLab 提交记录**：支持按日期查询指定用户的代码提交
- 📊 **智能日报生成**：自动生成格式化的代码提交日报
- 💬 **企业微信集成**：支持 Webhook 和 API 两种方式发送消息
- 🛠 **MCP 协议支持**：可与支持 MCP 的 AI 助手无缝集成
- ⚙️ **灵活配置**：支持环境变量和配置文件
- 🔒 **错误处理**：完善的错误处理和日志记录
## 安装
### 1. 获取项目代码
由于这是一个本地开发的项目，您已经有了完整的代码。如果需要在其他地方使用，可以：
**方式1：直接使用当前目录（推荐）**
```bash
# 当前项目已在 d:\wwwroot\azWork\workBook 目录
# 打开PowerShell或命令提示符，进入项目目录
cd d:\wwwroot\azWork\workBook
# 验证项目文件是否存在
dir
# 应该能看到：package.json, README.md, src文件夹等
```
**方式2：复制到其他位置使用**
如果您想在其他位置使用这个工具，比如复制到桌面：
```bash
# 1. 复制整个项目文件夹到桌面
# 在文件管理器中：
# - 右键点击 d:\wwwroot\azWork\workBook 文件夹
# - 选择"复制"
# - 进入桌面，右键选择"粘贴"
# - 重命名为 gitlab-wechat-mcp（可选）
# 2. 进入复制后的项目目录
cd C:\Users\%USERNAME%\Desktop\gitlab-wechat-mcp
# 3. 验证文件完整性
dir
```
**方式3：使用Git管理（如果需要版本控制）**
```bash
# 在项目目录中初始化Git仓库
cd d:\wwwroot\azWork\workBook
git init
git add .
git commit -m "初始化GitLab WeChat MCP工具"
# 如果要推送到远程仓库
# git remote add origin https://your-git-server.com/your-repo.git
# git push -u origin main
```
### 2. 安装依赖
```bash
npm install
```
**如果遇到网络问题，可以使用国内镜像：**
```bash
npm install --registry=https://registry.npmmirror.com
```
### 3. 测试连接
```bash
npm test
```
**测试输出示例：**
```
✓ GitLab连接测试成功
✓ 企业微信连接测试成功
✓ 获取提交记录测试成功
✓ 发送测试消息成功
```
### 4. 配置环境变量
复制环境变量模板：
```bash
# Windows PowerShell
copy .env.example .env
# 或者手动复制文件
# 右键点击 .env.example 文件 -> 复制 -> 粘贴 -> 重命名为 .env
```
编辑 `.env` 文件，填入你的配置：
```env
# GitLab 配置
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_USERNAME=zhangsan
# 企业微信配置（选择一种方式）
# 方式1：使用 Webhook（推荐）
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 方式2：使用企业微信 API（如果不用Webhook，可以用这种方式）
# WECHAT_CORP_ID=wwxxxxxxxxxxxxxxxx
# WECHAT_CORP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# WECHAT_AGENT_ID=1000002
# MCP 配置（一般不需要修改）
MCP_SERVER_NAME=gitlab-wechat-mcp
MCP_SERVER_VERSION=1.0.0
```
**配置示例说明：**
- `GITLAB_TOKEN`: 类似 `glpat-xxxxxxxxxxxxxxxxxxxx` 的格式
- `GITLAB_USERNAME`: 你的GitLab用户名，如 `zhangsan`
- `WECHAT_WEBHOOK_URL`: 企业微信机器人的完整URL地址
## 配置说明
### GitLab 配置
1. **获取 Personal Access Token**：
- 登录 GitLab（如 https://gitlab.com）
- 点击右上角头像 → Settings（设置）
- 左侧菜单选择 "Access Tokens"（访问令牌）
- 填写表单：
- Token name: `mcp-daily-report`（可自定义）
- Expiration date: 选择过期时间（建议1年）
- Scopes: 勾选 `read_api` 和 `read_repository`
- 点击 "Create personal access token"
- **重要**：复制生成的token（格式如：`glpat-xxxxxxxxxxxxxxxxxxxx`），离开页面后无法再次查看
2. **配置参数示例**：
```env
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_USERNAME=zhangsan
```
### 企业微信配置
支持两种方式：
#### 方式1：Webhook（推荐，简单易用）
1. **创建企业微信群机器人**：
- 在企业微信中创建或进入一个群聊
- 点击群聊右上角 "..." → 群机器人 → 添加机器人
- 选择 "自定义机器人"
- 填写机器人名称：`GitLab日报机器人`
- 点击 "添加"
- **重要**：复制生成的Webhook URL（格式如：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）
2. **配置示例**：
```env
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
#### 方式2：企业微信 API（高级用法）
1. **获取企业信息**：
- 登录企业微信管理后台（https://work.weixin.qq.com）
- 我的企业 → 企业信息 → 复制 "企业ID"
2. **创建应用**：
- 应用管理 → 自建 → 创建应用
- 填写应用名称：`GitLab日报`
- 选择可见范围
- 创建后获取 "AgentId" 和 "Secret"
3. **配置示例**：
```env
WECHAT_CORP_ID=wwxxxxxxxxxxxxxxxx
WECHAT_CORP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WECHAT_AGENT_ID=1000002
```
## 使用方法
### 作为 MCP 服务器运行
```bash
npm start
```
### 开发模式（自动重启）
```bash
npm run dev
```
## MCP 工具说明
本工具提供以下 3 个 MCP 工具：
### 1. get_gitlab_commits
获取 GitLab 用户在指定日期的代码提交记录。
**参数：**
- `date` (必需)：查询日期，格式 YYYY-MM-DD
- `username` (可选)：GitLab 用户名，默认使用配置的用户名
- `projectId` (可选)：项目 ID，不指定则查询所有项目
**使用示例：**
1. **获取今天的提交记录**：
```json
{
"date": "2024-01-15"
}
```
2. **获取指定用户的提交记录**：
```json
{
"date": "2024-01-15",
"username": "zhangsan"
}
```
3. **获取特定项目的提交记录**：
```json
{
"date": "2024-01-15",
"projectId": "123"
}
```
**返回结果示例：**
```json
{
"success": true,
"data": {
"date": "2024-01-15",
"username": "zhangsan",
"total_commits": 3,
"commits": [
{
"project_name": "web-frontend",
"commit_message": "修复登录页面样式问题",
"commit_id": "abc123",
"time": "09:30"
}
]
}
}
```
### 2. send_to_wechat
发送消息到企业微信。
**参数：**
- `message` (必需)：要发送的消息内容
- `messageType` (可选)：消息类型，`text` 或 `markdown`，默认 `text`
**使用示例：**
1. **发送普通文本消息**：
```json
{
"message": "今日代码提交总结：完成了3个功能模块的开发",
"messageType": "text"
}
```
2. **发送Markdown格式消息**：
```json
{
"message": "## 今日工作总结\n\n- ✅ 完成登录功能\n- ✅ 修复样式问题\n- 🔄 正在开发支付模块",
"messageType": "markdown"
}
```
**返回结果示例：**
```json
{
"success": true,
"message": "消息发送成功"
}
```
### 3. generate_daily_report
生成并发送 GitLab 提交记录的日报到企业微信。
**参数：**
- `date` (必需)：查询日期，格式 YYYY-MM-DD
- `username` (可选)：GitLab 用户名，默认使用配置的用户名
- `projectId` (可选)：项目 ID，不指定则查询所有项目
**使用示例：**
1. **生成今日日报**：
```json
{
"date": "2024-01-15"
}
```
2. **生成指定用户的日报**：
```json
{
"date": "2024-01-15",
"username": "john.doe"
}
```
3. **生成特定项目的日报**：
```json
{
"date": "2024-01-15",
"username": "john.doe",
"projectId": "456"
}
```
**返回结果示例：**
```json
{
"success": true,
"message": "日报已成功发送到企业微信",
"data": {
"commits_count": 3,
"projects_count": 2,
"report_sent": true
}
}
```
## 日报格式示例
生成的日报包含以下信息：
```markdown
# john.doe 的代码提交日报
**日期**: 2024-01-15
**提交数量**: 3
**涉及项目**: project-a, project-b
## 提交详情
### 1. 修复用户登录问题
- **项目**: project-a
- **时间**: 2024-01-15 09:30:00
- **分支**: main
- **详情**: 解决了用户登录时的验证码问题
- **链接**: [查看提交](https://gitlab.com/project-a/-/commit/abc123)
### 2. 添加新功能模块
- **项目**: project-b
- **时间**: 2024-01-15 14:20:00
- **分支**: feature/new-module
- **链接**: [查看提交](https://gitlab.com/project-b/-/commit/def456)
```
## 完整使用流程示例
### 场景：每日自动生成并发送工作日报
1. **配置完成后，测试连接**：
```bash
npm test
```
2. **手动获取今日提交记录**：
使用MCP工具 `get_gitlab_commits`：
```json
{
"date": "2024-01-15"
}
```
3. **生成并发送日报**：
使用MCP工具 `generate_daily_report`：
```json
{
"date": "2024-01-15",
"username": "zhangsan"
}
```
4. **查看企业微信群消息**：
日报会自动发送到配置的企业微信群中。
## 与 AI 助手集成
本工具支持 MCP 协议，可以与支持 MCP 的 AI 助手（如 Claude Desktop）集成使用。
### Claude Desktop 配置
在 Claude Desktop 的配置文件中添加：
```json
{
"mcpServers": {
"gitlab-wechat": {
"command": "node",
"args": ["D:\\wwwroot\\azWork\\workBook\\src\\index.js"],
"env": {
"GITLAB_TOKEN": "your_token",
"GITLAB_USERNAME": "your_username",
"WECHAT_WEBHOOK_URL": "your_webhook_url"
}
}
}
}
```
**配置文件位置：**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
**配置后的使用方式：**
在Claude Desktop中直接对话：
- "帮我获取今天的GitLab提交记录"
- "生成今日工作日报并发送到企业微信"
- "查看昨天的代码提交情况"
## 故障排除
### 常见问题
1. **GitLab Token 权限不足**
- 确保 Token 具有 `read_api` 和 `read_repository` 权限
- 检查 Token 是否过期
2. **企业微信消息发送失败**
- 检查 Webhook URL 是否正确
- 确认机器人是否被正确添加到群组
- 验证企业微信 API 配置是否完整
3. **找不到用户或项目**
- 确认用户名拼写正确
- 检查项目 ID 是否存在
- 验证 Token 是否有访问相应项目的权限
### 调试模式
设置环境变量启用详细日志：
```bash
export LOG_LEVEL=debug
npm start
```
### 测试连接
可以通过 MCP 工具测试各个服务的连接状态：
1. 测试 GitLab 连接
2. 测试企业微信连接
3. 发送测试消息
## 开发
### 项目结构
```
src/
├── index.js # MCP 服务器主文件
├── config/
│ └── index.js # 配置管理
├── services/
│ ├── gitlab.js # GitLab API 服务
│ └── wechat.js # 企业微信服务
└── utils/
├── logger.js # 日志工具
└── errors.js # 错误处理
```
### 添加新功能
1. 在相应的服务文件中添加新方法
2. 在 `index.js` 中注册新的 MCP 工具
3. 更新文档和示例
## 许可证
MIT License
## 贡献
欢迎提交 Issue 和 Pull Request！
## 更新日志
### v1.0.0
- 初始版本发布
- 支持 GitLab 提交记录获取
- 支持企业微信消息发送
- 支持自动日报生成
- 完整的 MCP 协议支持