# git-worklog-mcp

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

[![npm version](https://badge.fury.io/js/git-worklog-mcp.svg)](https://www.npmjs.com/package/git-worklog-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 特性

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

---

## 快速开始

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

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

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

### 方式二：全局安装

```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 配置 |

---

## 配置选项详解

### 完整配置示例

```json
{
  "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：最简配置（中文日报）

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

### 示例 2：周报模式

```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"
      ]
    }
  }
}
```

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

```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"
  ]
}
```

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

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

### 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 - 日报模板

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

```markdown
# 工作日志 - {{date_range}}

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

## 工作内容

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

### Bug 修复
- ...
```

### weekly - 周报模板

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

```markdown
# 周报 - {{date_range}}

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

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

### monthly - 月报模板

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

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

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

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

### simple - 简单列表

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

```markdown
# 工作记录 {{date_range}}

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

共 {{total_commits}} 项
```

---

## 自定义模板

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

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"
  ]
}
```

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

```json
{
  "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}}` | 作者邮箱 | `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 按模板格式，用专业语言描述每项工作的价值

### 自动分类规则

基于 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 用户名或邮箱：

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

### 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，这是正常的。后续提交会正常显示统计。

---

## 开发

```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