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用户名，如 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. 配置参数示例：

   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. 配置示例：

   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. 配置示例：

   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-DD
• username (可选)：GitLab 用户名，默认使用配置的用户名
• projectId (可选)：项目 ID，不指定则查询所有项目

使用示例：

1. 获取今天的提交记录：

{
  "date": "2024-01-15"
}

2. 获取指定用户的提交记录：

{
  "date": "2024-01-15",
  "username": "zhangsan"
}

3. 获取特定项目的提交记录：

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

使用示例：

1. 发送普通文本消息：

{
  "message": "今日代码提交总结：完成了3个功能模块的开发",
  "messageType": "text"
}

2. 发送Markdown格式消息：

{
  "message": "## 今日工作总结\n\n- ✅ 完成登录功能\n- ✅ 修复样式问题\n- 🔄 正在开发支付模块",
  "messageType": "markdown"
}

返回结果示例：

{
  "success": true,
  "message": "消息发送成功"
}

3. generate_daily_report

生成并发送 GitLab 提交记录的日报到企业微信。

参数：

• date (必需)：查询日期，格式 YYYY-MM-DD
• username (可选)：GitLab 用户名，默认使用配置的用户名
• projectId (可选)：项目 ID，不指定则查询所有项目

使用示例：

1. 生成今日日报：

{
  "date": "2024-01-15"
}

2. 生成指定用户的日报：

{
  "date": "2024-01-15",
  "username": "john.doe"
}

3. 生成特定项目的日报：

{
  "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)

完整使用流程示例

场景：每日自动生成并发送工作日报

1. 配置完成后，测试连接：

npm test

2. 手动获取今日提交记录： 使用MCP工具 get_gitlab_commits：

{
  "date": "2024-01-15"
}

3. 生成并发送日报： 使用MCP工具 generate_daily_report：

{
  "date": "2024-01-15",
  "username": "zhangsan"
}

4. 查看企业微信群消息： 日报会自动发送到配置的企业微信群中。

与 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提交记录"
• "生成今日工作日报并发送到企业微信"
• "查看昨天的代码提交情况"

故障排除

常见问题

1. GitLab Token 权限不足

   • 确保 Token 具有 read_api 和 read_repository 权限
   • 检查 Token 是否过期

2. 企业微信消息发送失败

   • 检查 Webhook URL 是否正确
   • 确认机器人是否被正确添加到群组
   • 验证企业微信 API 配置是否完整

3. 找不到用户或项目

   • 确认用户名拼写正确
   • 检查项目 ID 是否存在
   • 验证 Token 是否有访问相应项目的权限

调试模式

设置环境变量启用详细日志：

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 协议支持