Git Worklog Mcp

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