git-worklog-mcp

一个 MCP (Model Context Protocol) 服务器，让 AI 从 Git 提交历史自动生成专业的工作日志。

特性

• AI 智能分析 - AI 理解代码变更语义，生成有价值的工作描述
• 可配置模板 - 支持日报、周报、月报等预设模板，支持自定义模板文件
• 统一工具前缀 - 所有工具使用 worklog_ 前缀，方便唤起
• 多语言支持 - 支持中文 (zh) 和英文 (en) 输出
• 零配置启动 - 通过 npx 直接运行，无需安装

快速开始

方式一：npx 直接使用（推荐）

无需安装，在 MCP 配置中直接使用 npx：

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": ["git-worklog-mcp"]
    }
  }
}

方式二：全局安装

npm install -g git-worklog-mcp

安装后配置：

{
  "mcpServers": {
    "git-worklog": {
      "command": "git-worklog-mcp"
    }
  }
}

MCP 配置文件位置

| 工具 | 配置文件路径 | |------|-------------| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Cursor | ~/.cursor/mcp.json | | VS Code | .vscode/mcp.json 或用户级 MCP 配置 |

配置选项详解

完整配置示例

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": [
        "git-worklog-mcp",
        "--template", "daily",
        "--lang", "zh"
      ]
    }
  }
}

所有参数说明

| 参数 | 简写 | 环境变量 | 说明 | 可选值 | 默认值 | |------|------|----------|------|--------|--------| | --template | -t | WORKLOG_TEMPLATE | 预设模板名称 | daily, weekly, monthly, simple | daily | | --template-file | -f | WORKLOG_TEMPLATE_FILE | 自定义模板文件的绝对或相对路径 | 任意 .md 文件路径 | - | | --author | -a | WORKLOG_AUTHOR | 默认筛选的 Git 作者（可用名字或邮箱） | 字符串 | - | | --lang | -l | WORKLOG_LANG | 输出语言，影响分类名称显示 | zh（中文）, en（英文） | zh |

优先级: --template-file > --template（当指定模板文件时，预设模板参数被忽略）

配置示例

示例 1：最简配置（中文日报）

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": ["git-worklog-mcp"]
    }
  }
}

示例 2：周报模式

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": [
        "git-worklog-mcp",
        "--template", "weekly",
        "--lang", "zh"
      ]
    }
  }
}

示例 3：指定作者 + 英文输出

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": [
        "git-worklog-mcp",
        "-t", "daily",
        "-a", "[email protected]",
        "-l", "en"
      ]
    }
  }
}

示例 4：使用自定义模板文件

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": [
        "git-worklog-mcp",
        "--template-file", "D:\\projects\\.worklog-template.md"
      ]
    }
  }
}

macOS/Linux 路径示例：

{
  "args": [
    "git-worklog-mcp",
    "-f", "/Users/yourname/projects/.worklog-template.md"
  ]
}

示例 5：使用环境变量配置

{
  "mcpServers": {
    "git-worklog": {
      "command": "npx",
      "args": ["git-worklog-mcp"],
      "env": {
        "WORKLOG_TEMPLATE": "monthly",
        "WORKLOG_AUTHOR": "cherish",
        "WORKLOG_LANG": "zh"
      }
    }
  }
}

可用工具

配置完成后，AI 可以调用以下工具（均以 worklog_ 为前缀）：

| 工具名 | 说明 | |--------|------| | worklog_get_data | 核心工具 - 获取 Git 提交数据，返回结构化 JSON + 模板内容供 AI 生成日志 | | worklog_get_diff | 获取指定提交的代码差异（diff），用于深入分析变更内容 | | worklog_list_authors | 列出仓库的所有贡献者及其提交统计 | | worklog_get_template | 获取当前配置的模板信息，查看可用模板列表 |

worklog_get_data 参数

| 参数 | 必填 | 类型 | 说明 | 示例 | |------|------|------|------|------| | repo_path | ✅ | string | Git 仓库路径 | "D:\\my-project" 或 "." | | author | ❌ | string | 按作者筛选 | "your-name" | | since | ❌ | string | 开始日期 | "yesterday", "1 week ago", "2024-01-01" | | until | ❌ | string | 结束日期 | "today", "2024-01-31" | | max_commits | ❌ | number | 最大提交数量 | 50（默认 100） |

使用方法

配置好 MCP 后，直接对 AI 说：

生成今日工作日志

请用 worklog_get_data 获取 D:\my-project 仓库今天的提交，按模板生成工作日志

生成本周周报

请获取 D:\my-project 仓库最近一周的 Git 提交，生成周报

生成指定作者的月报

请获取仓库 2024 年 1 月 cherish 的所有提交，生成月度工作报告

查看当前模板配置

请调用 worklog_get_template 查看当前使用的模板

预设模板

daily - 日报模板

按分类展示今日工作内容，适合每日汇报：

# 工作日志 - {{date_range}}

## 今日概要
- 提交次数: {{total_commits}}
- 代码变更: +{{total_insertions}}/-{{total_deletions}} 行

## 工作内容

### 功能开发
- {{message}} (`{{short_hash}}`)

### Bug 修复
- ...

weekly - 周报模板

按周汇总，包含分类统计和模块分布，适合周会汇报：

# 周报 - {{date_range}}

## 本周概览
| 指标 | 数值 |
|------|------|
| 提交次数 | {{total_commits}} |
| 活跃天数 | {{active_days}} 天 |

## 工作分类
### {{category_name}} ({{count}}项)
- {{message}}

monthly - 月报模板

完整的月度工作报告，含统计表格，适合月度总结：

# 月度工作报告 - {{month}}

## 月度总览
- 总提交: {{total_commits}} 次
- 活跃天数: {{active_days}} 天

## 工作分类统计
| 类型 | 数量 | 占比 |
|------|------|------|
| {{name}} | {{count}} | {{percentage}}% |

simple - 简单列表

极简模式，仅列出提交信息，适合快速查看：

# 工作记录 {{date_range}}

- {{message}}
- {{message}}

共 {{total_commits}} 项

自定义模板

方式一：使用模板文件（推荐）

1. 创建模板文件

在项目中创建 .worklog-template.md：

# 我的工作日志 - {{date_range}}

## 今日完成

{{#each commits}}
- [{{date_formatted}}] {{message}} (`{{short_hash}}`)
  - 变更: {{stats.files_changed}} 文件, +{{stats.insertions}}/-{{stats.deletions}}
{{/each}}

## 统计汇总
- 提交: {{total_commits}} 次
- 代码变更: +{{total_insertions}}/-{{total_deletions}} 行
- 涉及模块: {{module_count}} 个

---
*由 AI 自动生成*

2. 在 MCP 配置中指定模板文件

{
  "args": [
    "git-worklog-mcp",
    "--template-file", "/path/to/.worklog-template.md"
  ]
}

方式二：通过环境变量指定

{
  "env": {
    "WORKLOG_TEMPLATE_FILE": "/path/to/template.md"
  }
}

模板语法

| 语法 | 说明 | 示例 | |------|------|------| | {{variable}} | 变量替换 | {{total_commits}} | | {{#each items}}...{{/each}} | 循环遍历数组 | {{#each commits}}...{{/each}} | | {{#category:名称}}...{{/category}} | 按分类筛选提交 | {{#category:功能开发}}...{{/category}} |

可用变量一览

汇总变量（全局可用）

| 变量 | 说明 | 示例值 | |------|------|--------| | {{date_range}} | 日期范围 | 2024-01-01 ~ 2024-01-07 | | {{total_commits}} | 总提交数 | 15 | | {{total_insertions}} | 新增代码行数 | 342 | | {{total_deletions}} | 删除代码行数 | 128 | | {{active_days}} | 活跃天数 | 5 | | {{module_count}} | 涉及模块数量 | 8 |

提交变量（在 {{#each commits}} 中使用）

| 变量 | 说明 | 示例值 | |------|------|--------| | {{hash}} | 完整提交哈希 | a1b2c3d4e5f6... | | {{short_hash}} | 短哈希（7位） | a1b2c3d | | {{message}} | 提交信息 | feat: add user login | | {{date_formatted}} | 格式化日期 | 2024-01-15 | | {{category_name}} | 分类名称 | 功能开发 | | {{author.name}} | 作者名 | cherish | | {{author.email}} | 作者邮箱 | [email protected] | | {{stats.files_changed}} | 变更文件数 | 3 | | {{stats.insertions}} | 新增行数 | 45 | | {{stats.deletions}} | 删除行数 | 12 |

分类变量（在 {{#each categories}} 中使用）

| 变量 | 说明 | 示例值 | |------|------|--------| | {{name}} | 分类名称 | 功能开发 | | {{count}} | 该分类的提交数 | 8 | | {{percentage}} | 占比百分比 | 53 |

模块变量（在 {{#each modules}} 中使用）

| 变量 | 说明 | 示例值 | |------|------|--------| | {{name}} | 模块名称（基于文件路径首级目录） | src | | {{count}} | 变更次数 | 12 |

工作原理

┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
│  Git 仓库   │ ──▶ │  MCP Server     │ ──▶ │    AI       │
│  提交历史   │     │  数据 + 模板    │     │  智能生成   │
└─────────────┘     └─────────────────┘     └─────────────┘

1. MCP 提取数据 - 从 Git 仓库读取提交历史，自动分类
2. 返回结构化数据 - JSON 格式的提交数据 + 模板内容
3. AI 智能生成 - AI 按模板格式，用专业语言描述每项工作的价值

自动分类规则

基于 commit message 的前缀或关键词自动判断：

| 分类 | 触发关键词 | |------|-----------| | 功能开发 | feat、add、new | | Bug修复 | fix、bug、issue | | 代码优化 | refactor、optimize、improve | | 文档更新 | docs、readme、document | | 测试相关 | test | | 代码风格 | style、format、lint | | 日常维护 | chore、deps、upgrade | | 性能优化 | perf、performance |

常见问题

Q: 如何只获取我自己的提交？

使用 --author 参数，可以填写 Git 用户名或邮箱：

{
  "args": ["git-worklog-mcp", "-a", "[email protected]"]
}

Q: 模板文件路径怎么写？

• Windows: "D:\\project\\.worklog-template.md" 或 "D:/project/.worklog-template.md"
• macOS/Linux: "/home/user/project/.worklog-template.md"
• 相对路径: "./.worklog-template.md"（相对于启动 MCP 的工作目录）

Q: 支持哪些 AI 工具？

支持所有兼容 MCP 协议的工具：

• Claude Desktop
• Cursor
• VS Code + Copilot（需配置 MCP）
• 其他 MCP 兼容客户端

Q: 为什么提交统计显示 0？

首次提交（没有父提交）无法计算 diff，这是正常的。后续提交会正常显示统计。

开发

# 克隆仓库
git clone https://github.com/CherishMvp/git-worklog-mcp.git
cd git-worklog-mcp

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 使用 MCP Inspector 测试
npm run inspect

License

MIT