前言
相信大多数程序员都有过这样的体验：周一到周五忙得不可开交，但到了周五下班前写周报时，却怎么也想不起来具体完成了哪些工作——感觉做了很多事，却又好像什么都没做成。为了应对这种情况，我养成了在每天完成一项任务或需求后立即记录的习惯，但偶尔忘记时，就不得不重新翻查需求清单。
与其他职业不同，程序员的工作主要与代码打交道，我们一周的具体工作内容往往体现在项目的git提交记录中。因此，我们可以基于一周内的git提交记录，按照周报模板的提示自动生成周报。先来看一下实际效果：
开发准备
安装 python3.12 和 uv，使用 Homebrew 安装非常简单，只需执行以下两条命令：
-
安装 python
brew install python@3.12 -
安装 uv
brew install uv -
新建项目 mcp-git-weekly-report 并创建 weekly_report.py 文件
-
在 weekly_report.py 中安装 fastmcp 依赖并创建 mcp
使用uv pip install fastmcp或pip install fastmcp安装依赖后，创建 mcp：from fastmcp import FastMCP # 默认使用 Stdio 协议，因此该 mcp 服务器实际上在本地运行 mcp = FastMCP("weekly-report")
这里简要介绍一下 FastMCP 框架。FastMCP 是一个 Python 框架，旨在极大简化 MCP 服务器的开发流程。其名称中的 “Fast” 正体现了其目标：帮助开发者快速构建 MCP 服务器。
FastMCP 的核心特点与优势：
- 极简的 API：通过装饰器（如
@mcp.tool）将普通 Python 函数直接转换为 MCP 工具，几乎无需关注底层协议细节。 - 基于 Pydantic：天然支持使用 Pydantic 模型定义工具输入输出的数据类型，确保类型安全并生成清晰文档。
- 资源管理：提供简便的资源管理方式（如数据库连接），可在服务器启动时建立连接，并在结束时自动关闭。
- 内置常用功能：预置了多种常见的 MCP 服务器功能，例如：
- 文件系统访问：允许 AI 读写指定目录的文件。
- SQL 数据库查询：使 AI 能够直接查询数据库。
- 代码执行：提供安全的代码执行环境。
- HTTP 请求：简化对外部 API 的调用。
- 开发友好：支持通过简单的命令行指令运行和测试服务器。
若希望对 mcp 服务进行更精细的控制和定制，可使用官方提供的底层 SDK，详情请参阅官方文档：https://github.com/modelcontextprotocol/python-sdk?tab=readme-ov-file#tools
开发
设计思路
我们通过 git log 命令获取提交记录，完整指令格式如下：
git log --author=cube.li --since='3 days ago' --pretty='format:%ad|%s' --date=short要成功执行该命令，需要明确以下参数：
-
项目地址：由于周报 MCP 服务运行在本地，项目地址应为本地绝对路径。为便于灵活配置，我们将项目地址作为 MCP 服务器的环境变量注入，并使用“|”作为分隔符以支持多项目场景。
-
Git 用户名称：可通过
git config user.name获取，无需额外传入。 - 日期范围：周报默认覆盖当前周（7 天内），同时支持指定日期范围（如“3 天内工作总结”“15 天内工作总结”）。该参数由大模型识别后传递给 MCP 服务器。
获取 Git 提交记录后，MCP 服务将其返回给 AI 应用。但仅凭提交记录无法有效控制周报的内容、格式和字数。为避免每次生成周报时重复输入要求，我们在 MCP 服务器中预置了周报模板 Prompt，将其与提交记录一并返回给 AI 应用，从而确保生成内容符合规范。
周报模板 Prompt 内容如下：
你是一个专业的周报生成器，根据 Git 提交记录生成一份专业的工作周报。
## 📋 要求
1. **分类整理**：将提交按功能开发、Bug 修复、性能优化、文档更新等分类整理，若某分类无相关提交则无需体现。
2. **提炼要点**：从 Commit Message 中提取关键信息，对内容相似的提交进行汇总，避免冗余表述。
3. **专业表述**：使用简洁、专业的技术语言。
4. **格式规范**：采用清晰的 Markdown 格式。
5. **跨项目视角**：总结跨项目的技术积累和工作思路。
6. **字数控制**：全文控制在 100–300 字，确保内容精炼、明确。
输出格式如下：
## 一、工作概述
[用 2–3 句话总结本周主要工作内容和成果]
## 二、详细工作内容
### 2.1 功能开发
- [功能1]：[详细描述功能内容和技术实现]
- [功能2]：[详细描述]
### 2.2 Bug 修复
- [问题1]：[问题描述] → [解决方案]
- [问题2]：[问题描述] → [解决方案]
### 2.3 性能优化
- [优化项1]：[优化内容和效果]
### 2.4 其他工作
- [文档更新、代码重构等]
## 三、技术总结
[本周工作中的技术亮点、经验总结或遇到的技术挑战]
## Git 提交记录：为了方便调试开发中的 MCP，您可以安装官方提供的 MCP Inspector，也可以选择使用 Claude Desktop 或 Cursor 进行调试。由于我本人是 Cursor 的深度使用者，后续将基于该工具展示周报 MCP 的实际效果并提供使用示例。
代码实现
-
从环境变量中获取项目地址
def get_projects() -> List[Dict[str, str]]:
"""
从环境变量读取项目配置信息Returns: 包含项目名称和路径的字典列表 """ paths_str = os.getenv("PROJECT_PATHS", "") if not paths_str: return [] projects = [] for path in paths_str.split("|"): path = path.strip() if not path: continue # 检查路径是否存在且为 Git 仓库 if os.path.exists(path) and os.path.exists(os.path.join(path, ".git")): projects.append({ "name": os.path.basename(path), "path": path }) else: print(f"警告：{path} 不是有效的 Git 仓库", file=sys.stderr) return projects - 获取提交记录
* **获取提交记录**
def get_git_commits(repo_path: str, days: int = 7) -> Dict[str, str]:
"""
提取指定 Git 仓库在特定时间范围内的提交记录
Args:
repo_path: 目标仓库的本地路径
days: 追溯最近若干天的提交历史（默认7天）
Returns:
包含作者信息、提交详情、仓库路径的字典对象
"""
# 提取仓库配置的作者名称
result = subprocess.run(
["git", "config", "user.name"],
cwd=repo_path,
capture_output=True,
text=True,
check=False
)
author = result.stdout.strip() or "未知作者"
# 查询指定作者的提交历史
result = subprocess.run(
["git", "log", f"--author={author}",
f"--since='{days} days ago'",
"--pretty=format:%ad|%s", "--date=short"],
cwd=repo_path,
capture_output=True,
text=True,
check=False
)
commits = result.stdout.strip()
# 计算有效提交数量
commit_count = len([line for line in commits.split('\n') if line.strip()]) if commits else 0
return {
"author": author,
"commits": commits or "（暂无提交记录）",
"commit_count": commit_count,
"repo_path": repo_path
}
* **将 git_commits_report 方法定义为 MCP 工具并对外暴露```
```markdown
# 注意这个装饰器，使用 @mcp.tool() 修饰后，该方法将作为 MCP 工具暴露给 AI 应用
@mcp.tool()
def git_commits_report(days: int = 7) -> str:
"""根据指定项目的 Git 提交记录生成工作周报
Args:
days: 统计最近几天的工作（默认统计当前天及过去6天，即 days=7；若用户明确指定时间范围，如三天内，则 days=3）
"""
projects: List[Dict[str, str]] = get_projects()
commit_str: str = ''
for proj in projects:
commit_str += get_git_commits(proj['path'], days).get('commits', '')
return f"{report_prompt_template}\n{commit_str}"
使用该装饰器时需注意以下两点：
1. **方法注释应尽可能详尽**
详细的注释有助于在 AI 应用中清晰展示该 MCP 工具的功能说明。在 `cursor` 中的效果如下所示：
2. **关于 @mcp.tool()**
实际上，MCP 服务器支持三种方式对外暴露能力：
* _**tool**_
允许模型执行操作或检索信息的可执行函数，使用装饰器 `@mcp.tool()`。通常，涉及数据处理的功能适合作为 tool 对外提供。
* _**prompt**_
预设模板或指令，用于引导语言模型进行交互，使用装饰器 `@mcp.prompt()`。例如，我们可以使用 `@mcp.prompt()` 装饰 `git_commits_report` 方法。重启 MCP 服务后，在 `cursor` 对话框中输入 `/` 时，系统会自动列出已有的 MCP prompt 选项：
使用 `@mcp.prompt()` 不仅能提升人机交互效率，还能为 AI 应用提供可组合、可管理、可解释的提示上下文机制。
* _**resource**_
为模型提供结构化数据或附加上下文的内容，使用装饰器 `@mcp.resource()`。
需要注意的是，一个 MCP 服务器可以同时提供多种类型、多个数量的 MCP 工具（包括 tool、prompt、resource）。配置
在 Cursor 的 mcp.json 文件中添加以下配置：
{
"mcpServers": {
"weekly-report": {
"command": "uv",
"args": [
"run",
"--directory",
"/Users/ltb/PycharmProjects/mcp-git-weekly-report/src/mcp_git_weekly_report",
"weekly_report.py"
],
"env": {
"PROJECT_PATHS": "/Users/ltb/PycharmProjects/mcp-git-weekly-report"
}
}
}
}只需将配置中的 mcp_git_weekly_report 绝对路径替换为本地项目实际路径，并将 PROJECT_PATHS 环境变量设置为对应的项目路径。若有多个项目，可使用 | 进行分隔。
使用示例：
完整代码仓库地址：https://gitee.com/li-cube/mcp-git-weekly-report
你也可以使用以下配置，直接从远端拉取代码并启动 MCP 服务：
{
"mcpServers": {
"weekly-report": {
"command": "uvx",
"args": [
"--from",
"git+https://gitee.com/li-cube/mcp-git-weekly-report.git",
"mcp-git-weekly-report"
],
"env": {
"PROJECT_PATHS": "项目1绝对路径|项目2绝对路径"
}
}
}
}共同学习，写下你的评论
评论加载中...
作者其他优质文章
