Plan Tracker MCP

2.14.0: bounded notification delivery

Notification CLI attempts now have a 90-second total budget, including startup and the 15-second gateway send timeout. Each attempt owns a separate process group and private temporary directory; success, failure and timeout all reclaim remaining child processes and scratch copies. Delivery pauses below 1 GiB of free temporary disk space.

A transport failure stops the current batch without acknowledging unsent items. Retries wait 30, 60, 120, 240, 480 and 600 seconds, then probe at most once per hour until recovery. Incoming webhooks cannot shorten failure backoff. Successful delivery resets the failure delay. Plugin command activation is declared in the manifest, and CLI errors return control to the host for cleanup.

English | 中文

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 with real-time webhook push delivery.

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 — Event-scheduled engine fires reminders at exact configured times, with startup catch-up for missed reminders
• Persistent Daemon — macOS uses a launchd KeepAlive service so reminder delivery never inherits an AI/MCP sandbox; other platforms retain the MCP watchdog fallback
• Notification delivery — Webhook real-time push + queue fallback; each notification is sent and acknowledged independently; supports QQ/Telegram/Slack etc.

Requirements

• Python >= 3.12
• MCP >= 1.0.0

Installation

Option 1: OpenClaw Plugin Marketplace (recommended)

openclaw plugins install clawhub:plan-tracker
bash ~/.openclaw/extensions/plan-tracker/scripts/setup.sh

Option 2: pip

pip install https://github.com/hinayoung23/plan-tracker/releases/latest/download/plan_tracker-2.14.0-py3-none-any.whl

Setup

# One command to register MCP server + install/start the daemon service
python -m plan_tracker.cli setup

setup automates:

1. ✅ Registers the MCP server in ~/.openclaw/openclaw.json (auto-detects Python path)
2. ✅ Installs and starts a persistent launchd daemon on macOS (MCP watchdog fallback on other platforms)

Notification delivery: webhook real-time push is recommended (webhook-setup), with queue polling as fallback.

Restart OpenClaw afterwards:

openclaw gateway restart

Notification Delivery

Option 1: Webhook real-time push (recommended)

# Auto-detect channel and install
python -m plan_tracker.cli webhook-setup

# Or read it from a private file (must be chmod 600)
python -m plan_tracker.cli webhook-setup --delivery-config /path/to/private-delivery.json

The private JSON file uses {"channel":"qqbot","to":"qqbot:c2c:<id>","agentId":"main"}. agentId is optional and defaults to main; set it when notifications should be owned by another agent in a multi-agent OpenClaw setup. Edit it with a local editor or secret manager; the target is never accepted as a command-line value. The daemon POSTs notifications to a local webhook receiver, which delivers them through the privacy-safe openclaw plan-tracker-deliver stdin command. Notifications are also written to the queue as fallback.

Option 2: Queue polling

python -m plan_tracker.cli deliver

Atomically fetches and acks pending notifications.

Available Tools

Project Structure

plan-tracker/
├── plan_tracker/
│   ├── server.py              # FastMCP server (20 tools)
│   ├── daemon.py              # Standalone daemon (double-fork)
│   ├── reminder.py            # Scheduled reminder engine
│   ├── plan_manager.py        # Plan CRUD + analysis
│   ├── milestone_manager.py   # Milestone + check-in logic
│   ├── daily_tracker.py       # Daily state (reminders/timeout/archive)
│   ├── storage.py             # JSON file storage
│   ├── notification_queue.py  # Notification producer-consumer queue
│   ├── cli.py                 # CLI (setup, webhook, deliver, cron)
│   └── notification/          # Delivery channels
│       ├── webhook_channel.py # Webhook push (real-time)
│       ├── email_channel.py   # Email via HMAC-SHA256
│       └── mcp_channel.py     # MCP protocol (queue)
├── scripts/
│   ├── webhook_receiver.py    # HTTP server for webhook delivery
│   └── setup.sh               # One-command install
├── skill/SKILL.md             # AI skill definition
└── data/                      # Runtime data (gitignored)

License

MIT

中文

简介

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

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

功能

• 计划管理 — 创建、查看、更新、删除计划，支持分类（学习/项目/健身/阅读/自定义）
• 里程碑管理 — 添加/更新里程碑，查看当前和即将到期的里程碑
• 进度打卡 — 记录每个里程碑的完成百分比、投入时间、心得体会、阻碍和心情
• 计划分析 — 计算进度偏差、节奏系数、剩余工时预估、心情趋势
• 定时提醒 — 基于事件调度，按时触发每日早晚提醒、过期/即将到期/停滞的里程碑检测
• 每日提醒 — 早晚两次提醒：早晨进度提醒（默认 08:30）+ 晚间完成确认（默认 21:30），支持 10 分钟超时自动判定
• 持久守护进程 — macOS 使用 launchd KeepAlive，避免继承 AI/MCP 运行环境的网络沙箱；其他平台保留 MCP watchdog 兜底
• 通知投递 — Webhook 实时推送 + 通知队列兜底，每条通知独立发送、独立确认，支持 QQ/Telegram/Slack 等平台

环境要求

• Python >= 3.12
• MCP >= 1.0.0

安装

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

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

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

方式二：PyPI / pip

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

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

初始化配置

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

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

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

setup 自动完成：

1. ✅ 在 ~/.openclaw/openclaw.json 中注册 MCP Server（自动检测 Python 路径）
2. ✅ macOS 安装并启动 launchd 持久守护服务（其他平台由 MCP watchdog 自动拉起）

通知投递推荐使用 Webhook 实时推送（webhook-setup），也支持队列轮询（deliver + cron）。

安装后重启 OpenClaw 生效：

openclaw gateway restart

可用工具

计划 (Plan)

里程碑 (Milestone)

打卡 (Check-in)

每日确认 (Daily)

提醒 (Reminder)

数据模型

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 的提醒功能通过独立守护进程运行，支持自动拉起，无需手动管理：

持久化与自动拉起

在 macOS 上，setup 会安装 com.plan-tracker.daemon LaunchAgent，并由 launchd KeepAlive 托管。这样 daemon 不会继承 OpenClaw、Codex 等宿主的网络沙箱。其他平台由 server.py 的 watchdog 每 5 分钟检测并自动拉起。

手动管理

python -m plan_tracker.cli daemon start
python -m plan_tracker.cli daemon status
python -m plan_tracker.cli daemon stop

通知投递

方式一：Webhook 实时推送（推荐）

# 一键安装 webhook receiver，自动发现投递渠道
python -m plan_tracker.cli webhook-setup

# 从私密文件读取（文件权限必须为 0600）
python -m plan_tracker.cli webhook-setup --delivery-config /path/to/private-delivery.json

私密 JSON 格式为 {"channel":"qqbot","to":"qqbot:c2c:<id>","agentId":"main"}。agentId 可省略，默认使用 main；多 Agent 环境需要投递到其他 Agent 时请显式设置。请通过本地编辑器或密钥管理器创建，接收目标不再接受命令行传值。Daemon 生成通知后通过 Webhook POST 到本地 receiver，receiver 通过 stdin 调用 openclaw plan-tracker-deliver 实时推送到消息平台。通知同时写入队列作为兜底。

方式二：队列轮询

python -m plan_tracker.cli deliver

提醒机制

每日提醒

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

里程碑提醒

• 基于事件调度，每天在早晨提醒时间触发一次里程碑检查
• 过期里程碑（超过目标日期未完成）→ 推送提醒
• 即将到期（before_due_days 内）→ 推送提醒
• 停滞里程碑（7 天未更新进度）→ 推送提醒
• 每周检查（指定星期几）→ 推送周进度回顾
• 同类型通知 12 小时内不重复推送
• Daemon 启动时自动补检遗漏的提醒

项目结构

plan-tracker/
├── plan_tracker/
│   ├── server.py              # FastMCP 工具服务入口
│   ├── daemon.py              # 独立守护进程（提醒引擎常驻运行）
│   ├── reminder.py            # 事件调度提醒引擎
│   ├── plan_manager.py        # Plan CRUD + 分析
│   ├── milestone_manager.py   # 里程碑 + 打卡操作
│   ├── daily_tracker.py       # 每日状态管理（提醒/确认/超时/归档）
│   ├── storage.py             # JSON 文件存储
│   ├── notification_queue.py  # 通知队列（daemon 写，外部系统读）
│   ├── cli.py                 # 命令行管理工具
│   └── notification/          # 通知通道
│       ├── webhook_channel.py # Webhook 实时推送
│       ├── email_channel.py   # 邮件通知（HMAC-SHA256）
│       └── mcp_channel.py     # MCP 通道通知
├── scripts/
│   ├── webhook_receiver.py    # Webhook 接收端 HTTP 服务
│   └── setup.sh               # 一键安装脚本
├── skill/SKILL.md             # AI Skill 定义
└── data/                      # 运行时数据（gitignore）

License

MIT