Plan Tracker MCP

English | 中文

中文

简介

Plan Tracker 是一个 MCP (Model Context Protocol) 服务器，为 AI 助手提供长期计划管理能力。支持里程碑追踪、进度打卡、计划分析和定时提醒。

无论是学习路线、项目规划、健身计划还是读书清单，Plan Tracker 都能帮你把大目标拆解成可执行的里程碑，并持续追踪进度。

功能

计划管理 — 创建、查看、更新、删除计划，支持分类（学习/项目/健身/阅读/自定义）
里程碑管理 — 添加/更新里程碑，查看当前和即将到期的里程碑
进度打卡 — 记录每个里程碑的完成百分比、投入时间、心得体会、阻碍和心情
计划分析 — 计算进度偏差、节奏系数、剩余工时预估、心情趋势
定时提醒 — 守护进程每 5 分钟轮询，检测过期/即将到期/停滞的里程碑
每日提醒 — 早晚两次提醒：早晨进度提醒（默认 08:30）+ 晚间完成确认（默认 21:30），支持 10 分钟超时自动判定
自动拉起 — MCP Server 启动时自动检查并拉起守护进程，附带 watchdog 线程守护存活
通知投递 — 通过 CLI 拉取通知队列，配合任意定时任务即可投递到消息平台

环境要求

Python >= 3.12
MCP >= 1.0.0

安装

方式一：OpenClaw 插件市场（推荐）

# 一键安装
openclaw plugins install clawhub:plan-tracker

# 初始化配置（Python 依赖 + MCP 注册 + launchd + daemon）
bash ~/.openclaw/extensions/plan-tracker/scripts/setup.sh

方式二：PyPI / pip

# 从 GitHub Releases 安装
pip install https://github.com/hinayoung23/plan-tracker/releases/download/v1.4.1/plan_tracker-1.4.1-py3-none-any.whl

# 或从源码安装
git clone https://github.com/hinayoung23/plan-tracker.git
cd plan-tracker
pip install -e .

初始化配置

安装后运行 setup 完成 MCP 注册和守护进程启动：

# 一条命令完成配置
python -m plan_tracker.cli setup

# 试运行：预览改动但不写入
python -m plan_tracker.cli setup --dry-run

setup 自动完成：

✅ 在 ~/.openclaw/openclaw.json 中注册 MCP Server（自动检测 Python 路径）
✅ 安装 launchd plist（Mac 重启后自动拉起 daemon）
✅ 启动守护进程

通知投递由 agent 平台负责。如果你使用 OpenClaw，可运行 python -m plan_tracker.cli cron-setup --help 查看定时任务配置选项。

安装后重启 OpenClaw 生效：

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

可用工具

计划 (Plan)

工具	说明
`plan_create`	创建新计划
`plan_get`	查看计划详情
`plan_list`	列出所有计划
`plan_update`	更新计划字段
`plan_delete`	删除计划
`plan_analysis`	获取计划分析数据

里程碑 (Milestone)

工具	说明
`milestone_add`	添加里程碑
`milestone_update`	更新里程碑
`milestone_current`	查看当前活跃里程碑
`milestone_upcoming`	查看即将到期的里程碑

打卡 (Check-in)

工具	说明
`checkin_add`	记录一次进度打卡

每日确认 (Daily)

工具	说明
`daily_confirm`	确认当天计划完成情况
`daily_status`	查看当天提醒和确认状态

提醒 (Reminder)

工具	说明
`reminder_configure`	配置提醒参数（含每日提醒时间）
`reminder_toggle`	开启/关闭提醒
`reminder_check_now`	手动触发一次检查
`email_configure`	配置邮件通知

数据模型

Plan
├── name            (kebab-case, 唯一标识)
├── title           (可读标题)
├── goal            (1-2 句目标描述)
├── category        (learning | project | fitness | reading | custom)
├── target_end_date (YYYY-MM-DD)
├── weekly_hours_target
├── milestones      [Milestone, ...]
└── reminders       ReminderConfig

Milestone
├── id, title, description
├── status          (pending | in_progress | completed | blocked)
├── target_date     (YYYY-MM-DD)
├── completion_pct  (0-100)
├── effort_hours_estimate / effort_hours_actual
└── checkins        [Checkin, ...]

Checkin
├── date, progress_pct, hours_spent
├── notes, blockers
└── morale          (struggling | neutral | good | great)

部署（首次使用）

Plan Tracker 的提醒功能通过独立守护进程运行。守护进程支持两种自动拉起方式，无需手动管理：

方式一：MCP Server 自动拉起（推荐）

当 AI 助手首次调用 plan-tracker MCP 工具时，server.py 会自动检查并启动守护进程，同时启动 watchdog 线程每 5 分钟检测守护进程存活状态，挂了自动拉起。

# 无需手动操作 —— MCP Server 启动时自动完成

方式二：CLI 轮询自愈

notifications --ack 命令在执行前会自动检查守护进程是否在运行，未运行则自动拉起。配合定时任务即可实现全自动运维。

# 查看通知（自动拉起守护进程 + 标记已投递）
python -m plan_tracker.cli notifications --ack

# 单独管理守护进程（一般不需要）
python -m plan_tracker.cli daemon start
python -m plan_tracker.cli daemon status
python -m plan_tracker.cli daemon stop

通知投递

守护进程将提醒写入 data/notification_queue.json。外部系统通过 CLI 拉取并投递给用户：

python -m plan_tracker.cli notifications --ack

--ack 确保每条通知只投递一次。将此命令配置到定时任务（如 cron）中即可实现自动通知投递。

如果你使用 OpenClaw，可用 python -m plan_tracker.cli cron-setup 生成定时轮询配置，具体参数由你的 agent 平台决定。

提醒机制

每日提醒

早晨进度提醒（默认 08:30）— 提醒当天的计划安排和当前里程碑
晚间完成确认（默认 21:30）— 确认当天计划完成情况（已完成/部分完成/未完成）
10 分钟超时 — 晚间确认发出后 10 分钟内未回复，自动标记为未完成
补确认归档 — 超时后的补确认将归档到第二天的计划记录中
两种提醒的触发时间均可在 reminder_configure 中自定义

里程碑提醒

后台线程每 5 分钟检查一次所有计划
过期里程碑（超过目标日期未完成）→ 推送提醒
即将到期（before_due_days 内）→ 推送提醒
停滞里程碑（7 天未更新进度）→ 推送提醒
每周检查（指定星期几）→ 推送周进度回顾
同类型通知 12 小时内不重复推送

项目结构

plan-tracker/
├── daemon.py              # 独立守护进程（提醒引擎常驻运行）
├── server.py              # FastMCP 工具服务入口
├── cli.py                 # 命令行管理工具
├── notification_queue.py  # 通知队列（daemon 写，外部系统读）
├── plan_manager.py        # Plan CRUD + 分析
├── milestone_manager.py   # 里程碑 + 打卡操作
├── daily_tracker.py       # 每日状态管理（提醒/确认/超时/归档）
├── storage.py             # JSON 文件存储
├── reminder.py            # 提醒引擎逻辑
├── notification/
│   ├── __init__.py
│   ├── base.py            # 通知通道基类
│   ├── mcp_channel.py     # MCP 通道通知
│   └── email_channel.py   # 邮件通知
├── skill/
│   └── SKILL.md           # AI Skill 定义
├── data/                  # 计划数据（gitignore）
└── pyproject.toml

License

MIT

English

Overview

Plan Tracker is an MCP (Model Context Protocol) server that gives AI assistants long-term plan management capabilities. It supports milestone tracking, progress check-ins, plan analysis, and scheduled reminders.

Whether it's a learning roadmap, project plan, fitness goal, or reading list, Plan Tracker helps break big goals into executable milestones and continuously tracks progress.

Features

Plan CRUD — Create, view, update, delete plans with categories (learning/project/fitness/reading/custom)
Milestones — Add and update milestones, view current and upcoming ones
Check-ins — Record progress percentage, time spent, notes, blockers, and morale for each milestone
Analysis — Progress deviation, pace ratio, remaining effort estimates, morale trends
Daily Reminders — Morning check-in (default 08:30) + evening review (default 21:30) with 10-min auto-timeout
Milestone Reminders — Daemon polls every 5 minutes for overdue, upcoming, and stale milestones
Auto-start Daemon — MCP Server auto-starts the daemon on first use with a watchdog thread; CLI --ack also self-heals
Notification delivery — CLI-based queue polling; pair with any scheduler to forward to your messaging platform

Requirements

Python >= 3.12
MCP >= 1.0.0

Installation

Option 1: OpenClaw Plugin Marketplace (recommended)

# Install from local path (cloned repository)
openclaw plugins install ./plan-tracker

# Install Python dependencies + initial setup
bash ~/.openclaw/extensions/plan-tracker/scripts/setup.sh

Option 2: PyPI / pip

# From GitHub Releases
pip install https://github.com/hinayoung23/plan-tracker/releases/download/v1.4.1/plan_tracker-1.4.1-py3-none-any.whl

# Or from source
git clone https://github.com/hinayoung23/plan-tracker.git
cd plan-tracker
pip install -e .

Setup

Run setup to register the MCP server and start the daemon:

# One command to configure plan-tracker
python -m plan_tracker.cli setup

# Preview changes without writing
python -m plan_tracker.cli setup --dry-run

setup automates:

✅ Registers the MCP server in ~/.openclaw/openclaw.json (auto-detects Python path)
✅ Installs a launchd plist (auto-restarts daemon after Mac reboots)
✅ Starts the daemon

Notification delivery is handled by your agent platform. If you use OpenClaw, run python -m plan_tracker.cli cron-setup --help for scheduling options.

Restart OpenClaw afterwards:

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Notification delivery

The daemon writes notifications to data/notification_queue.json. External systems poll them via:

python -m plan_tracker.cli notifications --ack

The --ack flag ensures each notification is delivered exactly once. Set up a periodic task (e.g. cron) to run this command and forward output to the user.

If you use OpenClaw, python -m plan_tracker.cli cron-setup generates a ready-to-use scheduling config. The specific delivery parameters depend on your agent platform.


### License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
data		data
plan_tracker		plan_tracker
scripts		scripts
skill		skill
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
openclaw.plugin.json		openclaw.plugin.json
package.json		package.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Plan Tracker MCP

中文

简介

功能

环境要求

安装

方式一：OpenClaw 插件市场（推荐）

方式二：PyPI / pip

初始化配置

可用工具

计划 (Plan)

里程碑 (Milestone)

打卡 (Check-in)

每日确认 (Daily)

提醒 (Reminder)

数据模型

部署（首次使用）

方式一：MCP Server 自动拉起（推荐）

方式二：CLI 轮询自愈

通知投递

提醒机制

每日提醒

里程碑提醒

项目结构

License

English

Overview

Features

Requirements

Installation

Option 1: OpenClaw Plugin Marketplace (recommended)

Option 2: PyPI / pip

Setup

Notification delivery

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages