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