使用说明

Git时间线MCP服务器🚀

一个模型上下文协议（MCP）服务器，用于分析项目的git历史并生成美观、交互式的视觉时间线。通过可视化功能开发和工具采用随时间的变化来跟踪项目的演变。

v3.0中的新功能： 🤖 基于Agent的人工智能分析 -不需要API密钥！AI代理（Claude/Copilot）使用自己的身份验证来分析数据。

特性

🎯 三种分析模式

📅 快速模式（基于模式）

使用文件模式和启发式方法进行即时分析：

分析源文件修改以识别特征添加
从文件路径、函数名和代码模式中检测域
通过智能分类按日期对功能进行分组
将实际文件名显示为标签（控制器、服务、页面等）
即时结果 -不需要API调用

🤖 智能模式（基于代理的AI）

卓越的语义理解质量：

收集提交数据 （差异、文件内容、元数据）
返回AI代理 用于使用其现有身份验证进行分析
不需要设置API密钥 -与Claude、Copilot或任何AI代理合作
透明分析 -你可以看到并控制整个过程
上下文感知描述 这解释了建造了什么以及为什么它很重要
按业务能力分组 而不是技术模式

🔧 工具时间线

跟踪技术栈的演变：

监控package.json更改的依赖关系
从配置文件（eslint、bearer、docker等）中检测工具
从npm注册表获取包描述以获取上下文
仅显示新引入的工具（过滤掉版本更新）

📊 交互式仪表板

项目洞察的中心枢纽：

特征和工具的并排比较
在时间线之间快速导航
桌面和移动设备的响应式设计
漂亮的渐变UI，基于卡片的布局

为什么是基于代理的分析？

新的v3.0架构更简单、更好：

✅ 无设置 -没有API键，没有环境变量，没有配置
✅ 适用于所有地方 -与Claude、GitHub Copilot或任何AI代理兼容
✅ 透明 -您可以查看数据并控制分析
✅ 性价比高 -使用您现有的AI订阅
✅ 卓越品质 -AI代理比自动呼叫更了解上下文

先决条件

Node.js>=18.0.0
要分析的git存储库
VS代码与GitHub Copilot（用于MCP集成）
对于智能模式： 主动人工智能代理（Claude/Copilot）

安装

选项1：从npm安装（推荐）

全局安装以在任何地方使用CLI命令：

npm install -g @pramodyadav027/git-timeline

# Then use the CLI command in any git repository
cd /path/to/your/project
git-timeline

或者在不通过npx安装的情况下使用：

npx @pramodyadav027/git-timeline

选项2：本地开发/测试

git clone <repo-url>
cd git-timeline
npm install
npm start

MCP与VS Code+GitHub Copilot集成

快速设置

打开VS代码设置（Cmd+，在Mac上，Ctrl+，在Windows上）
搜索“mcp”
点击“GitHub Copilot>MCP:Servers”下的“在settings.json中编辑”
添加Git Timeline服务器配置：

{
  "github.copilot.chat.mcp.enabled": true,
  "github.copilot.chat.mcp.servers": {
    "git-timeline": {
      "command": "npx",
      "args": ["@pramodyadav027/git-timeline"]
    }
  }
}

验证安装

在VS代码中打开GitHub Copilot聊天
类型 @workspace 你应该看到Git Timeline工具可用

用法

在VS代码聊天中使用MCP工具

服务器提供6个MCP工具，可通过GitHub Copilot Chat访问：

快速模式工具（即时结果）

生成功能时间线：

@workspace Use the generateFeatureTimeline tool to analyze this repository

生成工具时间线：

@workspace Use the generateToolingTimeline tool to show tooling evolution

生成所有时间线：

@workspace Use the generateAllTimelines tool to generate complete dashboard

智能模式工具（基于代理的AI）

智能特征分析：

@workspace Use the generateSmartFeatureTimeline tool to gather commit data for AI analysis

该工具将：

收集提交数据（文件内容、差异、元数据）
返回带有分析提示的结构化数据
您分析数据并用时间线事件进行响应
根据您的分析生成HTML/Markdown文件（可选）

智能工具分析：

@workspace Use the generateSmartToolingTimeline tool for enhanced tooling insights

综合智能分析：

@workspace Use the generateSmartTimelines tool for complete AI-powered timeline

使用CLI

直接在任何git仓库中运行：

# Generate all timelines with dashboard (fast mode)
git-timeline

# Or specify max commits
git-timeline --max-commits 500

# Generate only feature timeline
git-timeline --features-only

# Generate only tooling timeline
git-timeline --tooling-only

输出文件

生成的文件保存在 .timeline/ 存储库的目录：

快速模式：

{projectName}_feature_timeline.html -交互式功能时间线
{projectName}_feature_timeline.md -Markdown版本
{projectName}_tooling_timeline.html -交互式工具时间线
{projectName}_tooling_timeline.md -Markdown版本
index.html -主仪表板结合了两个时间线

智能模式（根据您的分析生成）：

基于人工智能分析的自定义时间表
可以导出为您喜欢的任何格式

智能模式的工作原理

基于Agent的流

您请求分析：

@workspace Analyze my git history with smart mode

MCP工具收集数据：
- 扫描git提交
- 提取文件更改和差异
- 读取文件内容
- 编译元数据
返回数据+提示：
- 结构化提交数据（JSON）
- 分析说明
- 最佳实践指南
您使用AI进行分析：
- 查看数据
- 使用AI识别模式
- 生成以业务为中心的描述
- 创建时间线事件
可选文件生成：
- 要求根据您的分析生成HTML/Markdown
- 创建仪表板可视化
- 以任何格式导出

工作流示例

You: @workspace Use generateSmartFeatureTimeline to analyze the last 50 commits

Agent: ✅ Gathered data for 50 commits

Here's the commit data with analysis prompt...

[Data + Prompt displayed]

You: [Review the data and respond with timeline JSON]

{
  "timeline": [
    {
      "date": "2024-01-15",
      "title": "User Authentication",
      "description": "Implemented secure login with JWT tokens",
      "category": "authentication",
      "icon": "🔐"
    },
    ...
  ]
}

Agent: Great! Want me to generate HTML/Markdown files from this timeline?

You: Yes, generate the HTML dashboard

Agent: ✅ Generated timeline dashboard at .timeline/custom_timeline.html

高级配置

基于时间的聚合选项

智能模式支持三个聚合级别对提交进行分组：

日（默认）-最适合活动项目：

按天数分组提交
显示详细的每日速度
建议用于：30-90天的回顾窗口
例子： aggregation: 'day' 随着 days: 90

周 -适用于更长的时间范围：

按周分组提交
在保持清晰度的同时减小数据大小
推荐用于：90-180天回顾窗口
例子： aggregation: 'week' 随着 days: 120

月 -从长远来看最好：

按月提交的组
提供高级项目演变
推荐用于：180天以上的回顾窗口或整个项目历史
例子： aggregation: 'month' 随着 days: 365

# Use week aggregation for 6-month analysis
@workspace Use generateSmartFeatureTimeline with aggregation=week and days=180

# Use month aggregation for full project history
@workspace Use generateSmartFeatureTimeline with aggregation=month and days=730

自定义提交扫描限制

默认情况下，智能模式为100次提交（以避免令牌限制）。根据需要进行调整：

@workspace Use generateSmartFeatureTimeline with maxCommits=50

排除文件

服务器会自动过滤掉：

配置文件（package-lock.json、yarn.lock等）
构建工件
文档（除非是主要更改）
锁定文件

自定义时间线生成

您可以要求代理人：

专注于特定功能
按时间段分组（每周、每月）
突出特定技术
创建自定义可视化

例子

示例1：快速功能概述

@workspace Generate a feature timeline for the last 100 commits

示例2：分组智能分析

@workspace Use smart mode to analyze commits and group related changes by feature

示例3：工具演变

@workspace Show me how our tech stack evolved over time

示例4：自定义日期范围

@workspace Analyze commits from the last 6 months and create a timeline

故障排除

常见问题

Q：智能工具返回的数据太多
A：减少maxCommits参数（默认值为100，尝试50或25）

Q：分析耗时过长
A：使用快速模式获得即时结果，或减少提交次数

Q：找不到文件错误
A：确保你在一个有提交历史记录的git存储库中

Q： MCP工具未在Copilot中显示
A：验证MCP是否在VS Code设置中启用，并重新启动VS Code

获取帮助

建筑

基于Agent的设计

┌─────────────────┐
│   AI Agent      │
│ (Claude/Copilot)│
│                 │
│ ┌─────────────┐ │
│ │  Analysis   │ │
│ │  Engine     │ │
│ └─────────────┘ │
└────────┬────────┘
         │ Request Data
         ↓
┌─────────────────┐
│  MCP Server     │
│                 │
│ ┌─────────────┐ │
│ │ Data Gatherer│ │
│ │ • Read git  │ │
│ │ • Extract   │ │
│ │ • Structure │ │
│ └─────────────┘ │
└────────┬────────┘
         │ Read
         ↓
┌─────────────────┐
│  Git Repository │
└─────────────────┘

这种架构的好处

关注点分离：数据收集与分析
灵活性：适用于任何AI代理
透明度：用户看到并控制分析
安全：没有要管理的API密钥
成本：使用现有的AI订阅

v3.0中的新增功能

重大变化

✅ 基于Agent的体系结构 -AI代理分析而不是直接的API调用
✅ 不需要API密钥 -使用代理的现有身份验证
✅ 删除依赖关系 -@anthropic ai/sdk不再需要
✅ 简化设置 -无需配置
✅ 更高的透明度 -您可以看到分析过程
✅ 通用兼容性 -与Claude、Copilot等合作

从v2.0迁移

快速模式工具没有中断更改。智能工具现在：

返回数据而不是自动生成文件
要求您进行分析并作出回应
根据您的分析生成文件（可选）

看更改日志.md 了解详情。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

作者

普拉莫德·库马尔·亚达夫

致谢

内置于模型上下文协议
由人工智能代理（Claude，GitHub Copilot）提供支持
受更好的项目可视化需求的启发

⭐ 如果你觉得这个仓库有用，就把它标上！
🐛 发现bug了吗？打开一个问题
💡 有主意吗？开始讨论

生成代理报告工具

v3.0中的新功能：HTML报告生成

使用智能模式分析git历史记录后，使用 generateAgentReport 创建精美视觉报告的工具。

用途：

@workspace Use generateAgentReport with these timeline events: [your JSON events]

特征：

📄 带有渐变UI的交互式HTML时间线
📝 Markdown文档
🎨 基于卡片布局的响应式设计
🗂️ 文件保存在 .timeline/ 目录
✨ 可定制的标题和文件名

工作流程示例：

收集提交数据：

@workspace Use generateSmartFeatureTimeline on /path/to/repo

分析并创建时间线（您提供JSON）：

[
  {
    "date": "2024-02-04",
    "title": "Feature Name",
    "description": "What was built and why",
    "category": "authentication",
    "icon": "🔐",
    "files": ["src/auth.ts"],
    "commitHashes": ["abc123"],
    "tags": ["security", "oauth"]
  }
]

生成报告：

@workspace Use generateAgentReport with the timeline events above

在浏览器中打开HTML文件！

输出文件：

FEATURE_TIMELINE.html -交互式可视化
FEATURE_TIMELINE.md -Markdown文档