Timeline Generator MCP

Timeline Generator MCP

Generate beautiful timeline visualizations from milestone data

Installation • Quick Start • Examples • MCP Server • Documentation

______________________________________________________________________

强大的CLI工具和MCP服务器，可从里程碑数据生成令人惊叹的时间线图像和动画GIF。非常适合项目时间表、产品路线图、公司历史和个人里程碑。

特性

• 5种时间线样式：水平、垂直、甘特图、路线图、信息图
• 4内置主题：简约、企业、创意、黑暗
• 多种输出格式：PNG、SVG、GIF、MP4
• 灵活的时间尺度：每小时、每天、每周、每月、每季度、每年
• 动画支持：以可配置的速度生成动画GIF
• 自定义颜色：通过配置或CLI覆盖主题颜色
• 透明背景：导出时无背景覆盖
• 智能布局：自动碰撞检测可防止标签重叠
• MCP服务器：通过模型上下文协议与AI助手集成

例子

横向时间线（企业主题）

垂直时间线（最小主题）

甘特图（深色主题）

产品路线图（创意主题）

信息图表风格（创意主题）

GIF动画示例

安装

先决条件

• Python 3.10或更高版本
• 开罗图形库

macOS

brew install cairo

Ubuntu/Debian

sudo apt-get install libcairo2-dev

使用紫外线进行安装（推荐）

git clone https://github.com/kbichave/timeline-generator-mcp.git
cd timeline-generator-mcp

uv venv
source .venv/bin/activate
uv pip install -e .

使用pip安装

pip install -e .

快速开始

1.创建配置文件

timeline-gen init -o my_timeline.yaml

2.编辑您的日程表

title: "My Project Timeline"
scale: monthly
style: horizontal
theme: corporate

milestones:
  - date: "2024-01-15"
    title: "Project Start"
    highlight: true
    
  - date: "2024-06-01"
    title: "Launch"

# Optional: Custom colors
colors:
  accent: "#FF5733"

# Optional: Text wrapping
text_wrap: true  # Set to false to disable text wrapping

output:
  format: png
  transparent: false

3.生成时间线

timeline-gen generate my_timeline.yaml -o timeline.png

CLI命令

generate -从配置文件生成

timeline-gen generate config.yaml [OPTIONS]

Options:
  -o, --output PATH       Output file path
  -f, --format TEXT       Output format (png, svg, gif, mp4)
  -s, --style TEXT        Timeline style
  -t, --theme TEXT        Theme name
  -w, --width INTEGER     Output width
  -h, --height INTEGER    Output height
  --fps INTEGER           Frames per second for animations (default: 30)
  -d, --duration FLOAT    Animation duration in seconds (default: 5.0)
  --transparent           Use transparent background
  --accent-color TEXT     Custom accent color (e.g., #FF5733)
  --text-wrap/--no-text-wrap  Enable/disable text wrapping (default: enabled)

quick -快速内联生成

timeline-gen quick "2024-01-01:Start" "2024-06-01:Launch" "2024-12-01:Scale" \
  --style horizontal --theme dark -o timeline.png

其他命令

timeline-gen styles      # List available styles
timeline-gen themes      # List available themes
timeline-gen preview     # Preview configuration
timeline-gen init        # Create template file
timeline-gen version     # Show version

生成所有示例

运行附带的脚本以生成所有示例输出：

./generate_examples.sh

MCP服务器

时间线生成器MCP包括 模型上下文协议（MCP）服务器 使用FastMCP构建，可与Claude、Cursor和其他代理AI系统等AI助手无缝集成。

运输方式

AI助手设置（STDIO模式）

选项1：使用uvx（推荐-无需安装）

{
  "mcpServers": {
    "timeline-generator-mcp": {
      "command": "uvx",
      "args": ["timeline-generator-mcp"]
    }
  }
}

保存到 ~/.cursor/mcp.json （光标）或 ~/Library/Application Support/Claude/claude_desktop_config.json （克劳德桌面）。

选项2：本地安装

git clone https://github.com/kbichave/timeline-generator-mcp.git
cd timeline-generator-mcp
uv pip install -e .

{
  "mcpServers": {
    "timeline-generator-mcp": {
      "command": "timeline-mcp"
    }
  }
}

重启你的AI助手 配置后。

HTTP模式（持久服务器）

对于web API访问或持久部署，请使用HTTP模式：

# Start HTTP server on port 8000
timeline-mcp-http

# Or with uvicorn directly (production)
uvicorn timeline_generator.fastmcp_server:http_app --host 0.0.0.0 --port 8000

服务器将在以下位置可用：

• MCP端点： http://localhost:8000/mcp
• 健康检查： http://localhost:8000/health

生产部署

码头工人

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libcairo2-dev && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .
RUN pip install -e .

EXPOSE 8000
CMD ["uvicorn", "timeline_generator.fastmcp_server:http_app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t timeline-mcp .
docker run -p 8000:8000 timeline-mcp

带反向代理的HTTPS

对于HTTPS，使用nginx或caddy作为反向代理：

server {
    listen 443 ssl;
    server_name timeline.example.com;
    
    ssl_certificate /etc/ssl/certs/timeline.crt;
    ssl_certificate_key /etc/ssl/private/timeline.key;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

可用工具

TOON格式（推荐用于AI）

与JSON相比，TOON（面向令牌的对象表示法）将令牌使用量减少了30-60%：

# TOON example - compact and token-efficient
title: Project Timeline
style: horizontal
theme: corporate
milestones[3]: date title description highlight
2024-01-15 Kickoff "Project begins" true
2024-06-01 Launch "Go live" false
2024-12-01 "Year End" "Review" false

等效的YAML多使用了约40%的令牌：

title: "Project Timeline"
style: horizontal
theme: corporate
milestones:
  - date: "2024-01-15"
    title: "Kickoff"
    description: "Project begins"
    highlight: true
  # ... etc

AI提示示例

简单时间线：

“创建一个时间表，显示我的项目阶段：1月计划，2月开发，5月测试，7月发布”

甘特图：

“用这些任务及其进度百分比为我们的冲刺生成甘特图…”

自定义样式：

“制作一个2020年至2024年公司历史的黑暗主题垂直时间表”

有生气的：

“创建一个动态GIF时间线，显示我们产品的演变”

工具文档

每个工具都包括AI助手可见的全面文档：

• 详细说明 解释何时以及如何使用每种工具
• 输入模式 通过验证和示例
• 错误消息 提供有益的建议
• 模板 用于快速配置

TOON格式示例

这 examples/ 目录包括TOON格式文件，演示了令牌高效格式：

示例：TOON与YAML

TOON格式 （代币减少30-60%）：

title: Website Redesign Project
style: horizontal
theme: corporate

milestones[4]: date title description highlight
2024-01-15 "Project Kickoff" "Initial planning" true
2024-03-15 "Design Approval" "Stakeholder sign-off" true
2024-06-15 "Beta Release" "External testing" true
2024-08-01 Launch "Public release" true

output:
  format: png
  width: 1920
  height: 800

等效YAML （约多40%的代币）：

title: Website Redesign Project
style: horizontal
theme: corporate
milestones:
  - date: "2024-01-15"
    title: "Project Kickoff"
    description: "Initial planning"
    highlight: true
  - date: "2024-03-15"
    title: "Design Approval"
    description: "Stakeholder sign-off"
    highlight: true
  # ... and so on
output:
  format: png
  width: 1920
  height: 800

从TOON生成

# Generate PNG from TOON file
timeline-gen generate examples/project_timeline.toon -o output/timeline.png

# Generate animated GIF from TOON
timeline-gen generate examples/project_timeline.toon -o output/timeline.gif -f gif --fps 20 -d 4

TOON示例输出

自 project_timeline.toon

自 sprint_gantt.toon

时间线样式

主题

自定义颜色

覆盖配置中的主题颜色：

colors:
  background: "#FFFFFF"
  text: "#333333"
  accent: "#007AFF"
  secondary: "#6C757D"
  highlight: "#FFD700"
  axis: "#E0E0E0"

自定义字体

控制不同元素的字体大小：

fonts:
  badge: 28       # Text inside milestone markers (default: theme title size)
  title: 18       # Milestone titles (default: theme label size)
  description: 14 # Descriptions (default: theme date size)

自定义徽章

这 badge 字段允许您自定义里程碑标记内显示的内容（信息图风格的圆圈，其他风格的数字）：

# YAML format
milestones:
  - date: "2025-02-01"
    badge: "Feb"          # Shows "Feb" instead of "1"
    title: "Project Start"
  - date: "2025-06-01"
    badge: "Q2"           # Shows "Q2" instead of "2"
    title: "Mid-Year Review"

# TOON format
milestones[2]: date badge title
2025-02-01 "Feb" "Project Start"
2025-06-01 "Q2" "Mid-Year Review"

这对于以下情况特别有用：

• 月份名称：“一月”、“二月”、“三月”
• 宿舍：“Q1”、“Q2”、“Q3”、“Q4”
• 年: "2020", "2021", "2022"
• 自定义标签：“MVP”、“v1.0”、“GA”

文本换行

控制长标题和描述是否换行为多行：

text_wrap: true   # Enable wrapping (default)
text_wrap: false  # Disable wrapping - text will be truncated

或者通过CLI：

timeline-gen generate config.yaml --no-text-wrap -o timeline.png
timeline-gen quick "2024-01:Long Title Here" --no-text-wrap

透明背景

导出没有背景的时间线，以便在幻灯片、网站或视频上叠加：

output:
  format: gif        # Works with PNG and GIF
  transparent: true  # No background - just the timeline elements

或者通过CLI：

timeline-gen generate config.yaml --transparent -o timeline.png

发展

设置

git clone https://github.com/kbichave/timeline-generator-mcp.git
cd timeline-generator-mcp
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

运行测试

pytest

贡献

欢迎投稿！请阅读我们的 贡献指南 和 行为准则.

许可证

MIT许可证-请参阅 许可证 了解详情。