git-worklog-mcp

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


特性

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

---

快速开始

$3

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

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

$3

`bash
npm install -g git-worklog-mcp
`

安装后配置：

`json
{
"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 配置 |

---

配置选项详解

$3

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

$3

| 参数 | 简写 | 环境变量 | 说明 | 可选值 | 默认值 |
|------|------|----------|------|--------|--------|
| --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（当指定模板文件时，预设模板参数被忽略）

---

配置示例

$3

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

$3

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

$3

`json
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"-t", "daily",
"-a", "your-name@example.com",
"-l", "en"
]
}
}
}
`

$3

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

macOS/Linux 路径示例：
`json
{
"args": [
"git-worklog-mcp",
"-f", "/Users/yourname/projects/.worklog-template.md"
]
}
`

$3

`json
{
"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 | 获取当前配置的模板信息，查看可用模板列表 |

$3

| 参数 | 必填 | 类型 | 说明 | 示例 |
|------|------|------|------|------|
| 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 说：

$3


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

$3

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

$3

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

$3

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

---

预设模板

$3

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

`markdown


工作日志 - {{date_range}}

今日概要

- 提交次数: {{total_commits}}
- 代码变更: +{{total_insertions}}/-{{total_deletions}} 行

工作内容

$3

- {{message}} ({{short_hash}})

$3

- ...
`

$3

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

`markdown


周报 - {{date_range}}

本周概览

| 指标 | 数值 |
|------|------|
| 提交次数 | {{total_commits}} |
| 活跃天数 | {{active_days}} 天 |

工作分类

$3

- {{message}}
`

$3

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

`markdown


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

月度总览

- 总提交: {{total_commits}} 次
- 活跃天数: {{active_days}} 天

工作分类统计

| 类型 | 数量 | 占比 |
|------|------|------|
| {{name}} | {{count}} | {{percentage}}% |
`

$3

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

`markdown


工作记录 {{date_range}}

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

共 {{total_commits}} 项
`

---

自定义模板

$3

1. 创建模板文件

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

`markdown


我的工作日志 - {{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 配置中指定模板文件

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

$3

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

$3

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

$3

#### 汇总变量（全局可用）

| 变量 | 说明 | 示例值 |
|------|------|--------|
| {{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}} | 作者邮箱 | xxx@example.com |
| {{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 按模板格式，用专业语言描述每项工作的价值

$3

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

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

---

常见问题

$3

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

`json
{
"args": ["git-worklog-mcp", "-a", "your-email@example.com"]
}
`

$3

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

$3

支持所有兼容 MCP 协议的工具：
- Claude Desktop
- Cursor
- VS Code + Copilot（需配置 MCP）
- 其他 MCP 兼容客户端

$3

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

---

开发

`bash


克隆仓库

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