# mcp-git-weekly-report **Repository Path**: li-cube/mcp-git-weekly-report ## Basic Information - **Project Name**: mcp-git-weekly-report - **Description**: 周报生成mcp，再也不用为写周报发愁啦 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-04 - **Last Updated**: 2025-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: 周报生成mcp ## README # 周报助手 MCP 实现总结 ## 📦 项目概述 成功实现了一个基于 MCP (Model Context Protocol) 和 FastMCP 框架的周报生成工具，能够自动从 Git 提交记录生成专业的工作周报。 ## ✨ 核心特性 ### 1. 多项目支持 - 支持同时管理多个项目 - 通过环境变量配置（`PROJECT_PATHS`），路径用 `|` 分隔 - 自动验证项目是否为有效的 Git 仓库 - 自动提取项目名称（基于目录名） ### 2. 智能周报生成 - **提交汇总**：汇总所有项目的提交记录和统计信息 - **周报生成**：基于 AI 提示词模板生成专业周报 - AI 自动分类整理（功能开发、Bug修复、优化、文档更新等） - 量化工作成果（提交次数统计） - 去除冗余信息，不体现具体时间和日期 ### 3. 灵活配置 - 可配置时间范围（默认7天，支持自定义） - 自动获取 Git 作者信息（git config user.name） - 支持动态添加/删除项目（通过修改环境变量） ### 4. 专业的周报模板 - 工作概述：2-3句话总结 - 详细工作内容：分类展示（功能开发、Bug修复、性能优化、其他工作） - 技术总结：技术亮点和经验总结 - 使用清晰的 Markdown 格式 ## 🏗️ 技术架构 ### 架构设计 ``` ┌─────────────────────────────────────────┐ │ Cursor / Claude Desktop │ │ (MCP Client) │ └────────────────┬────────────────────────┘ │ stdio ▼ ┌─────────────────────────────────────────┐ │ Weekly Report MCP Server │ │ (FastMCP Framework) │ │ │ │ ┌──────────────────────────────────┐ │ │ │ MCP Tools │ │ │ │ - repo_git_summary() │ │ │ │ - git_commits_report() │ │ │ └──────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ Helper Functions │ │ │ │ - get_projects() │ │ │ │ - get_git_commits() │ │ │ └──────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ Git Integration │ │ │ │ - git config user.name │ │ │ │ - git log --author --since │ │ │ └──────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ Templates │ │ │ │ - summary_template │ │ │ │ - report_prompt_template │ │ │ └──────────────────────────────────┘ │ └────────────────┬────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 本地 Git 仓库 │ │ (通过 PROJECT_PATHS 环境变量配置) │ └─────────────────────────────────────────┘ ``` ### 技术栈 - **语言**：Python 3.x - **框架**：FastMCP (MCP 协议的 Python 实现) - **依赖管理**：uv / pip - **版本控制集成**：Git 命令行工具 - **运行模式**：stdio (本地运行) ## 📂 项目结构 ``` /Users/ltb/PycharmProjects/mcp-git-weekly-report/ ├── weekly_report.py # MCP Server 主程序 (核心实现) ├── README.md # 完整文档 ├── QUICK_START.md # 快速开始指南 ├── IMPLEMENTATION_SUMMARY.md # 本文件 (实现总结) ├── MIGRATION_COMPLETE.md # 迁移文档 ├── TROUBLESHOOTING.md # 故障排查指南 ├── mcp_config_example.json # 配置示例 ├── pyproject.toml # 项目配置和依赖 ├── uv.lock # 依赖锁定文件 └── .python-version # Python 版本指定 配置文件位置: ~/.cursor/mcp.json # Cursor MCP 配置 或 ~/Library/Application Support/Claude/claude_desktop_config.json # Claude Desktop 配置 ``` ## 🔧 配置说明 ### MCP 配置示例 #### Cursor (`~/.cursor/mcp.json`) uvx从远程拉取代码启动 ```json { "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": "/Users/ltb/PycharmProjects/or-tools" } } } } ``` 本地代码启动 ```json { "mcpServers": { "weekly-report": { "command": "uv", "args": [ "run", "--directory", "/你的项目路径/mcp-git-weekly-report/src/mcp_git_weekly_report", "weekly_report.py" ], "env": { "PROJECT_PATHS": "/Users/ltb/PycharmProjects/or-tools" } } } } ``` ### 环境变量 | 变量名 | 说明 | 格式 | 示例 | |--------|------|------|------| | `PROJECT_PATHS` | 项目路径列表（必需） | 绝对路径，用 `\|` 分隔 | `/Users/ltb/project1\|/Users/ltb/project2` | **注意事项**： - 每个路径必须是有效的 Git 仓库（包含 `.git` 目录） - 使用绝对路径，避免使用 `~` 符号 - 路径之间使用 `|` 分隔，不要有多余空格 ## 🎯 实现的功能 ### MCP Tools #### 1. `repo_git_summary(days: int = 7) -> str` - **功能**：生成所有配置项目的 Git 提交汇总 - **参数**： - `days`: 统计最近几天的工作（默认 7 天） - **返回**：每个项目的汇总信息，包括： - 项目名称 - 提交次数 - 提交记录（日期|提交信息） - **用途**：查看原始提交数据，便于调试和验证 #### 2. `git_commits_report(days: int = 7) -> str` - **功能**：生成专业周报的 AI 提示词模板和提交数据 - **参数**： - `days`: 统计最近几天的工作（默认 7 天） - **返回**：包含以下内容的完整提示词： - 周报生成要求和规范 - 输出格式模板 - 所有项目的 Git 提交记录 - **用途**：直接提供给 AI 生成专业周报 ### 辅助函数 #### `get_projects() -> List[Dict[str, str]]` - 从环境变量 `PROJECT_PATHS` 读取并验证项目配置 - 返回包含项目名称和路径的列表 - 自动过滤无效路径和非 Git 仓库 #### `get_git_commits(repo_path: str, days: int = 7) -> Dict[str, str]` - 获取指定仓库的 Git 提交记录 - 自动获取当前 Git 用户名 - 返回作者、提交记录、提交次数、仓库路径 ### 周报模板 #### 汇总模板 (`summary_template`) 用于展示每个项目的基本统计信息： - 项目名称 - 提交次数 - 提交记录列表 #### 周报生成提示模板 (`report_prompt_template`) 指导 AI 生成专业周报，包含： 1. **生成要求**： - 分类整理（功能开发、Bug修复、性能优化、文档更新等） - 提炼要点（去除冗余，不体现具体时间日期） - 量化成果 - 专业表述 - 格式规范 - 跨项目视角 2. **输出格式**： - 一、工作概述 - 二、详细工作内容（含子分类） - 三、技术总结 ## 🧪 使用示例 ### 生成提交汇总 ``` 用户：使用 repo_git_summary 查看最近 7 天的提交 AI：[调用 repo_git_summary(days=7)] 返回： 项目名称: project1 提交次数: 15 提交记录: 2025-11-06|feat: 添加新功能 2025-11-05|fix: 修复登录问题 ... ``` ### 生成专业周报 ``` 用户：使用 git_commits_report 生成本周工作周报 AI：[调用 git_commits_report(days=7) 获取提示词和数据] AI：[基于返回的提示词和提交数据生成专业周报] 返回：格式化的专业周报文档 ``` ### 自定义时间范围 ``` 用户：生成最近 3 天的工作汇总 AI：[调用 repo_git_summary(days=3)] ``` ## 💡 设计亮点 ### 1. 简洁的配置方式 - 采用单一环境变量 `PROJECT_PATHS` 配置 - 使用 `|` 分隔多个项目路径 - 避免了复杂的配置文件 - 易于理解和维护 ### 2. FastMCP 框架 - 使用 FastMCP 简化 MCP 服务器开发 - 通过装饰器 `@mcp.tool()` 快速注册工具 - 代码简洁，易于扩展 - 自动处理 MCP 协议细节 ### 3. 完善的路径验证 - 自动验证每个项目路径是否存在 - 检查是否为有效的 Git 仓库（是否包含 `.git` 目录） - 提供警告信息，跳过无效路径 - 确保数据获取的可靠性 ### 4. 智能的 Git 集成 - 自动获取当前 Git 用户名（`git config user.name`） - 按作者过滤提交记录 - 支持自定义时间范围查询 - 使用 `subprocess` 安全执行 Git 命令 ### 5. 清晰的职责分离 - **MCP Tools**：负责数据获取（Git 提交记录） - **AI Assistant**：负责内容生成和格式化 - **模板系统**：提供标准化的提示词和格式 - 各模块独立，易于维护和测试 ### 6. 灵活的工具设计 - `repo_git_summary`：提供原始数据，用于调试和验证 - `git_commits_report`：提供完整提示词，直接用于生成周报 - 两个工具互补，满足不同使用场景 ### 7. 专业的周报模板 - 内置详细的周报生成指南 - 规范的 Markdown 格式 - 明确的分类结构 - 量化指标要求 - 去除冗余信息的指导 ## 🎨 使用体验 ### 一键生成 ``` 用户：生成本周工作周报 AI：[调用 git_commits_report] AI：[基于提示词和提交数据生成专业周报] ``` ### 自动化程度高 - 自动读取配置的所有项目 - 自动获取 Git 作者信息 - 自动提取提交记录 - 自动汇总多项目数据 - AI 自动分类整理和格式化 ### 灵活可控 - 支持多项目统一汇报 - 支持自定义时间范围（天数） - 支持查看原始提交数据 - 支持调试和验证数据 ## 📊 适用场景 1. **日常工作汇报**：每周/每月工作总结，快速生成专业周报 2. **项目进度汇报**：向上级/客户汇报多个项目的进度 3. **团队分享**：分享技术工作和经验，记录工作轨迹 4. **个人记录**：记录工作历程，便于复盘和总结 5. **跨项目总结**：统一管理多个项目的工作内容 ## 🚀 后续优化方向 ### 功能增强 - [ ] 支持排除特定类型的提交（如 merge commit、Merge branch 等） - [ ] 支持自定义周报模板（可配置的模板文件） - [ ] 支持导出周报为 Markdown 文件 - [ ] 支持按分支过滤提交记录 - [ ] 支持团队周报（多个作者汇总） - [ ] 支持提交分类规则配置（根据 commit message 前缀） - [ ] 支持 Git 标签（tag）相关的版本统计 ### 性能优化 - [ ] 缓存 Git 数据，避免重复查询 - [ ] 并发处理多个项目（使用 asyncio） - [ ] 增量更新提交记录 - [ ] 优化大仓库的查询性能 ### 用户体验 - [ ] 添加进度提示（处理多个项目时） - [ ] 支持周报历史记录存储 - [ ] 可视化工作统计（提交趋势图） - [ ] 集成代码统计（行数、文件数、修改量等） - [ ] 支持交互式配置（添加/移除项目） - [ ] 提供 Web UI 界面 ### 数据分析 - [ ] 提交频率分析 - [ ] 工作时间分布 - [ ] 文件修改热力图 - [ ] 代码贡献量统计 ## 🔐 安全考虑 1. **本地运行**： - 所有数据处理在本地进行 - 不上传任何数据到远程服务器 - 完全离线工作 2. **权限控制**： - 仅读取 Git 信息，不修改仓库 - 使用 `subprocess` 安全执行 Git 命令 - 不执行任何写操作 3. **数据隐私**： - 仅访问显式配置的项目 - 不扫描系统文件 - 不记录敏感信息 4. **依赖安全**： - 使用 FastMCP 官方框架 - 最小化依赖数量 - 定期更新依赖版本 ## 📖 相关文档 - [README.md](README.md) - 完整文档和安装指南 - [QUICK_START.md](QUICK_START.md) - 快速开始指南 - [MIGRATION_COMPLETE.md](MIGRATION_COMPLETE.md) - 迁移说明 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - 故障排查 - [mcp_config_example.json](mcp_config_example.json) - 配置示例 ## 🎓 技术参考 - [MCP 官方文档](https://modelcontextprotocol.io/) - Model Context Protocol 规范 - [FastMCP](https://github.com/jlowin/fastmcp) - FastMCP 框架文档 - [Git 命令文档](https://git-scm.com/docs) - Git 命令参考 - [Python subprocess](https://docs.python.org/3/library/subprocess.html) - subprocess 模块文档 ## 🏆 项目特点 ### 已实现特性 - ✅ 基于 FastMCP 框架的 MCP 服务器 - ✅ 多项目 Git 提交记录汇总 - ✅ 智能周报生成（AI 驱动） - ✅ 灵活的配置方式（环境变量） - ✅ 自动验证 Git 仓库 - ✅ 自定义时间范围查询 - ✅ 完善的文档和示例 ### 技术优势 - 🚀 简单易用：一个环境变量完成配置 - 🔧 易于扩展：清晰的模块化设计 - 📦 轻量级：最小化依赖 - 🔒 安全可靠：本地运行，数据隐私 - 📝 专业输出：结构化的周报格式 ## 📊 核心数据流 ``` 配置 (PROJECT_PATHS) ↓ get_projects() - 读取并验证项目 ↓ get_git_commits() - 获取每个项目的提交记录 ↓ repo_git_summary() - 汇总提交数据 ↓ git_commits_report() - 生成带提示词的完整数据 ↓ AI Assistant - 基于提示词生成专业周报 ``` ## 📅 版本历史 - **v1.0.0** (2025-11-06)： - 基于 FastMCP 的初始实现 - 支持多项目 Git 提交汇总 - 支持智能周报生成 - 完整的文档和示例 ---