{"id":"68b87996-4d63-4a0a-aee8-7f159d467bef","slug":"plan-tracker","kind":"mcp","name":"plan-tracker","summary":"MCP server for long-term plan tracking — milestones, daily check-ins, webhook push notifications, and AI-assisted progress analysis. OpenClaw plugin.","owner":"hinayoung23","repoUrl":"https://github.com/hinayoung23/plan-tracker","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-29T02:28:22.000Z","addedAt":"2026-10-21T09:03:16.796Z","logoUrl":"https://avatars.githubusercontent.com/u/156584397?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","productivity","cloud-infra"],"tags":["ai-assistant","clawhub","milestone","openclaw","productivity","python","reminder","webhook"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T17:40:28.933Z","sample":false,"url":"https://conduits.dev/tools/plan-tracker","language":"Python","transports":["stdio"],"install":{"pypi":"plan-tracker"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Plan Tracker MCP\n\n### 2.14.1: isolated OpenClaw runtime\n\nOpenClaw 2026.9.7 rejects plugin packages containing Python virtual-environment\nsymlinks that point outside the package. This release builds an immutable,\ncontent-addressed runtime containing only JavaScript, plugin metadata, skills,\ndocumentation and the license. Python services and private data stay outside it.\n\nClawHub and the plugin archive now ship this lightweight runtime without install\nhooks. Install the Python wheel separately as shown below; existing deployments\ncan keep their Python environment and data. Building or upgrading the runtime\ndoes not clear notification queues or resend past reminders.\n\n### 2.14.0: bounded notification delivery\n\nNotification CLI attempts now have a 90-second total budget, including startup\nand the 15-second gateway send timeout. Each attempt owns a separate process\ngroup and private temporary directory; success, failure and timeout all reclaim\nremaining child processes and scratch copies. Delivery pauses below 1 GiB of\nfree temporary disk space.\n\nA transport failure stops the current batch without acknowledging unsent items.\nRetries wait 30, 60, 120, 240, 480 and 600 seconds, then probe at most once per\nhour until recovery. Incoming webhooks cannot shorten failure backoff. Successful\ndelivery resets the failure delay. Plugin command activation is declared in the\nmanifest, and CLI errors return control to the host for cleanup.\n\n[English](#english) | [中文](#chinese)\n\n---\n\n<a id=\"english\"></a>\n## English\n\n### Overview\n\n**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**.\n\nWhether 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.\n\n### Features\n\n- **Plan CRUD** — Create, view, update, delete plans with categories (learning/project/fitness/reading/custom)\n- **Milestones** — Add and update milestones, view current and upcoming ones\n- **Check-ins** — Record progress percentage, time spent, notes, blockers, and morale for each milestone\n- **Analysis** — Progress deviation, pace ratio, remaining effort estimates, morale trends\n- **Daily Reminders** — Morning check-in (default 08:30) + evening review (default 21:30) with 10-min auto-timeout\n- **Milestone Reminders** — Event-scheduled engine fires reminders at exact configured times, with startup catch-up for missed reminders\n- **Persistent Daemon** — macOS uses a launchd `KeepAlive` service so reminder delivery never inherits an AI/MCP sandbox; other platforms retain the MCP watchdog fallback\n- **Notification delivery** — Webhook real-time push + queue fallback; each notification is sent and acknowledged independently; supports QQ/Telegram/Slack etc.\n\n### Requirements\n\n- Python >= 3.12\n- MCP >= 1.0.0\n\n### Installation\n\n#### Option 1: OpenClaw Plugin Marketplace (recommended)\n\n```bash\nopenclaw plugins install clawhub:plan-tracker\npython3 -m venv \"$HOME/.local/share/plan-tracker/venv\"\n\"$HOME/.local/share/plan-tracker/venv/bin/python\" -m pip install https://github.com/hinayoung23/plan-tracker/releases/download/v2.14.1/plan_tracker-2.14.1-py3-none-any.whl\n\"$HOME/.local/share/plan-tracker/venv/bin/python\" -m plan_tracker.cli setup\n```\n\nThe marketplace package has no `scripts/setup.sh` or automatic Python install.\nExisting installations should keep their configured Python environment and data\ndirectory, and upgrade the wheel there. Activate that environment before running\nthe Python commands below. Both the plugin and Python service are needed for\nnotification delivery.\n\n#### Option 2: pip\n\n```bash\npip install https://github.com/hinayoung23/plan-tracker/releases/download/v2.14.1/plan_tracker-2.14.1-py3-none-any.whl\n```\n\n### Setup\n\n```bash\n# One command to register MCP server + install/start the daemon service\npython -m plan_tracker.cli setup\n```\n\n`setup` automates:\n1. ✅ Registers the MCP server in `~/.openclaw/openclaw.json` (auto-detects Python path)\n2. ✅ Installs and starts a persistent launchd daemon on macOS (MCP watchdog fallback on other platforms)\n\n> Notification delivery: webhook real-time push is recommended (`webhook-setup`), with queue polling as fallback.\n\nRestart OpenClaw afterwards:\n```bash\nopenclaw gateway restart\n```\n\n### Notification Delivery\n\n**Option 1: Webhook real-time push (recommended)**\n\n```bash\n# Auto-detect channel and install\npython -m plan_tracker.cli webhook-setup\n\n# Or read it from a private file (must be chmod 600)\npython -m plan_tracker.cli webhook-setup --delivery-config /path/to/private-delivery.json\n```\n\nThe private JSON file uses\n`{\"channel\":\"qqbot\",\"to\":\"qqbot:c2c:<id>\",\"agentId\":\"main\"}`.\n`agentId` is optional and defaults to `main`; set it when notifications should\nbe owned by another agent in a multi-agent OpenClaw setup.\nEdit it with a local editor or secret manager; the target is never accepted as\na command-line value. The daemon POSTs notifications to a local webhook\nreceiver, which delivers them through the privacy-safe\n`openclaw plan-tracker-deliver` stdin command. Notifications are also written\nto the queue as fallback.\n\n**Option 2: Queue polling**\n\n```bash\npython -m plan_tracker.cli deliver\n```\n\nAtomically fetches and acks pending notifications.\n\n### Available Tools\n\n| Category | Tool | Description |\n|----------|------|-------------|\n| Plan | `plan_create` / `plan_get` / `plan_list` / `plan_update` / `plan_delete` | Plan CRUD |\n| Plan | `plan_analysis` | Progress statistics and trends |\n| Milestone | `milestone_add` / `milestone_update` / `milestone_current` / `milestone_upcoming` | Milestone management |\n| Check-in | `checkin_add` | Record a progress check-in |\n| Daily | `daily_confirm` / `daily_status` | Daily plan confirmation |\n| Reminder | `reminder_configure` / `reminder_toggle` / `reminder_check_now` | Reminder config |\n| Notification | `webhook_configure` / `email_configure` | Delivery channel setup |\n\n### Project Structure\n\n```\nplan-tracker/\n├── plan_tracker/\n│   ├── server.py              # FastMCP server (20 tools)\n│   ├── daemon.py              # Standalone daemon (double-fork)\n│   ├── reminder.py            # Scheduled reminder engine\n│   ├── plan_manager.py        # Plan CRUD + analysis\n│   ├── milestone_manager.py   # Milestone + check-in logic\n│   ├── daily_tracker.py       # Daily state (reminders/timeout/archive)\n│   ├── storage.py             # JSON file storage\n│   ├── notification_queue.py  # Notification producer-consumer queue\n│   ├── cli.py                 # CLI (setup, webhook, deliver, cron)\n│   └── notification/          # Delivery channels\n│       ├── webhook_channel.py # Webhook push (real-time)\n│       ├── email_channel.py   # Email via HMAC-SHA256\n│       └── mcp_channel.py     # MCP protocol (queue)\n├── scripts/\n│   ├── webhook_receiver.py    # HTTP server for webhook delivery\n│   └── setup.sh               # One-command install\n├── skill/SKILL.md             # AI skill definition\n└── data/                      # Runtime data (gitignored)\n```\n\n### License\n\nMIT\n\n---\n\n<a id=\"chinese\"></a>\n## 中文\n\n### 简介\n\n**Plan Tracker** 是一个 MCP (Model Context Protocol) 服务器，为 AI 助手提供长期计划管理能力。支持里程碑追踪、进度打卡、计划分析和定时提醒。\n\n无论是学习路线、项目规划、健身计划还是读书清单，Plan Tracker 都能帮你把大目标拆解成可执行的里程碑，并持续追踪进度。\n\n### 功能\n\n- **计划管理** — 创建、查看、更新、删除计划，支持分类（学习/项目/健身/阅读/自定义）\n- **里程碑管理** — 添加/更新里程碑，查看当前和即将到期的里程碑\n- **进度打卡** — 记录每个里程碑的完成百分比、投入时间、心得体会、阻碍和心情\n- **计划分析** — 计算进度偏差、节奏系数、剩余工时预估、心情趋势\n- **定时提醒** — 基于事件调度，按时触发每日早晚提醒、过期/即将到期/停滞的里程碑检测\n- **每日提醒** — 早晚两次提醒：早晨进度提醒（默认 08:30）+ 晚间完成确认（默认 21:30），支持 10 分钟超时自动判定\n- **持久守护进程** — macOS 使用 launchd `KeepAlive`，避免继承 AI/MCP 运行环境的网络沙箱；其他平台保留 MCP watchdog 兜底\n- **通知投递** — Webhook 实时推送 + 通知队列兜底，每条通知独立发送、独立确认，支持 QQ/Telegram/Slack 等平台\n\n### 环境要求\n\n- Python >= 3.12\n- MCP >= 1.0.0\n\n### 安装\n\n#### 方式一：OpenClaw 插件市场（推荐）\n\n```bash\n# 安装轻量 OpenClaw 插件\nopenclaw plugins install clawhub:plan-tracker\n\n# 将 Python 服务安装到插件目录以外\npython3 -m venv \"$HOME/.local/share/plan-tracker/venv\"\n\"$HOME/.local/share/plan-tracker/venv/bin/python\" -m pip install https://github.com/hinayoung23/plan-tracker/releases/download/v2.14.1/plan_tracker-2.14.1-py3-none-any.whl\n\"$HOME/.local/share/plan-tracker/venv/bin/python\" -m plan_tracker.cli setup\n```\n\n市场包不再包含 `scripts/setup.sh`，也不会自动创建 Python 虚拟环境。已有部署应保留原 Python 环境和数据目录，在原环境升级 wheel，避免重复配置服务。执行下方 Python 命令前先激活所选环境。通知投递需要同时安装插件和 Python 服务。\n\n#### 方式二：PyPI / pip\n\n```bash\n# 从 GitHub Releases 安装\npip install https://github.com/hinayoung23/plan-tracker/releases/download/v2.14.1/plan_tracker-2.14.1-py3-none-any.whl\n\n# 或从源码安装\ngit clone https://github.com/hinayoung23/plan-tracker.git\ncd plan-tracker\npip install .\n```\n\n### 初始化配置\n\n安装后运行 `setup` 完成 MCP 注册和守护进程启动：\n\n```bash\n# 一条命令完成配置\npython -m plan_tracker.cli setup\n\n# 试运行：预览改动但不写入\npython -m plan_tracker.cli setup --dry-run\n```\n\n`setup` 自动完成：\n1. ✅ 在 `~/.openclaw/openclaw.json` 中注册 MCP Server（自动检测 Python 路径）\n2. ✅ macOS 安装并启动 launchd 持久守护服务（其他平台由 MCP watchdog 自动拉起）\n\n> 通知投递推荐使用 Webhook 实时推送（`webhook-setup`），也支持队列轮询（`deliver` + cron）。\n\n安装后重启 OpenClaw 生效：\n```bash\nopenclaw gateway restart\n```\n\n### 可用工具\n\n#### 计划 (Plan)\n| 工具 | 说明 |\n|------|------|\n| `plan_create` | 创建新计划 |\n| `plan_get` | 查看计划详情 |\n| `plan_list` | 列出所有计划 |\n| `plan_update` | 更新计划字段 |\n| `plan_delete` | 删除计划 |\n| `plan_analysis` | 获取计划分析数据 |\n\n#### 里程碑 (Milestone)\n| 工具 | 说明 |\n|------|------|\n| `milestone_add` | 添加里程碑 |\n| `milestone_update` | 更新里程碑 |\n| `milestone_current` | 查看当前活跃里程碑 |\n| `milestone_upcoming` | 查看即将到期的里程碑 |\n\n#### 打卡 (Check-in)\n| 工具 | 说明 |\n|------|------|\n| `checkin_add` | 记录一次进度打卡 |\n\n#### 每日确认 (Daily)\n| 工具 | 说明 |\n|------|------|\n| `daily_confirm` | 确认当天计划完成情况 |\n| `daily_status` | 查看当天提醒和确认状态 |\n\n#### 提醒 (Reminder)\n| 工具 | 说明 |\n|------|------|\n| `reminder_configure` | 配置提醒参数（含每日提醒时间） |\n| `reminder_toggle` | 开启/关闭提醒 |\n| `reminder_check_now` | 手动触发一次检查 |\n| `webhook_configure` | 配置 Webhook 实时推送 |\n| `email_configure` | 配置邮件通知（HMAC-SHA256 签名） |\n\n### 数据模型\n\n```\nPlan\n├── name            (kebab-case, 唯一标识)\n├── title           (可读标题)\n├── goal            (1-2 句目标描述)\n├── category        (learning | project | fitness | reading | custom)\n├── target_end_date (YYYY-MM-DD)\n├── weekly_hours_target\n├── milestones      [Milestone, ...]\n└── reminders       ReminderConfig\n\nMilestone\n├── id, title, description\n├── status          (pending | in_progress | completed | blocked)\n├── target_date     (YYYY-MM-DD)\n├── completion_pct  (0-100)\n├── effort_hours_estimate / effort_hours_actual\n└── checkins        [Checkin, ...]\n\nCheckin\n├── date, progress_pct, hours_spent\n├── notes, blockers\n└── morale          (struggling | neutral | good | great)\n```\n\n### 部署\n\nPlan Tracker 的提醒功能通过**独立守护进程**运行，支持自动拉起，无需手动管理：\n\n#### 持久化与自动拉起\n\n在 macOS 上，`setup` 会安装 `com.plan-tracker.daemon` LaunchAgent，并由 launchd `KeepAlive` 托管。这样 daemon 不会继承 OpenClaw、Codex 等宿主的网络沙箱。其他平台由 `server.py` 的 watchdog 每 5 分钟检测并自动拉起。\n\n#### 手动管理\n\n```bash\npython -m plan_tracker.cli daemon start\npython -m plan_tracker.cli daemon status\npython -m plan_tracker.cli daemon stop\n```\n\n#### 通知投递\n\n**OpenClaw 2026.9.7+ 本地源码部署兼容性**\n\nPython 虚拟环境、计划数据与 OpenClaw 加载包必须分开。不要将含 `.venv/`、`data/` 的项目根目录直接加入 `plugins.load.paths`；新版加载器会拒绝包内指向系统 Python 的软链接。\n\n```bash\npython3 scripts/build_openclaw_runtime.py\n```\n\n此命令输出 `dist/openclaw-runtime/<内容哈希>/`，只含 JS 入口、插件清单、技能说明、安装文档和许可证，不含 Python 环境、数据或安装钩子。通过 `openclaw config set plugins.load.paths ... --strict-json` 将旧的项目根路径替换为该输出目录，保留其他插件路径。用 `openclaw plan-tracker-deliver --help` 验证命令加载，再恢复发送服务。源码更新后重新构建并切换到新目录；已有目录保持不变，便于回滚。\n\nMCP、daemon、webhook receiver 继续使用原项目和原数据目录。不要对生成的轻量目录执行 `scripts/setup.sh`；Python 环境的安装仍在项目根目录执行。构建本身不修改 OpenClaw 配置、不发送通知。\n\n**方式一：Webhook 实时推送（推荐）**\n\n```bash\n# 一键安装 webhook receiver，自动发现投递渠道\npython -m plan_tracker.cli webhook-setup\n\n# 从私密文件读取（文件权限必须为 0600）\npython -m plan_tracker.cli webhook-setup --delivery-config /path/to/private-delivery.json\n```\n\n私密 JSON 格式为 `{\"channel\":\"qqbot\",\"to\":\"qqbot:c2c:<id>\",\"agentId\":\"main\"}`。`agentId` 可省略，默认使用 `main`；多 Agent 环境需要投递到其他 Agent 时请显式设置。请通过本地编辑器或密钥管理器创建，接收目标不再接受命令行传值。Daemon 生成通知后通过 Webhook POST 到本地 receiver，receiver 通过 stdin 调用 `openclaw plan-tracker-deliver` 实时推送到消息平台。通知同时写入队列作为兜底。\n\n**方式二：队列轮询**\n\n```bash\npython -m plan_tracker.cli deliver\n```\n\n### 提醒机制\n\n#### 每日提醒\n- **早晨进度提醒**（默认 08:30）— 提醒当天的计划安排和当前里程碑\n- **晚间完成确认**（默认 21:30）— 确认当天计划完成情况（已完成/部分完成/未完成）\n- **10 分钟超时** — 晚间确认发出后 10 分钟内未回复，自动标记为未完成\n- **补确认归档** — 超时后的补确认将归档到第二天的计划记录中\n\n#### 里程碑提醒\n- 基于事件调度，每天在早晨提醒时间触发一次里程碑检查\n- 过期里程碑（超过目标日期未完成）→ 推送提醒\n- 即将到期（before_due_days 内）→ 推送提醒\n- 停滞里程碑（7 天未更新进度）→ 推送提醒\n- 每周检查（指定星期几）→ 推送周进度回顾\n- 同类型通知 12 小时内不重复推送\n- Daemon 启动时自动补检遗漏的提醒\n\n### 项目结构\n\n```\nplan-tracker/\n├── plan_tracker/\n│   ├── server.py              # FastMCP 工具服务入口\n│   ├── daemon.py              # 独立守护进程（提醒引擎常驻运行）\n│   ├── reminder.py            # 事件调度提醒引擎\n│   ├── plan_manager.py        # Plan CRUD + 分析\n│   ├── milestone_manager.py   # 里程碑 + 打卡操作\n│   ├── daily_tracker.py       # 每日状态管理（提醒/确认/超时/归档）\n│   ├── storage.py             # JSON 文件存储\n│   ├── notification_queue.py  # 通知队列（daemon 写，外部系统读）\n│   ├── cli.py                 # 命令行管理工具\n│   └── notification/          # 通知通道\n│       ├── webhook_channel.py # Webhook 实时推送\n│       ├── email_channel.py   # 邮件通知（HMAC-SHA256）\n│       └── mcp_channel.py     # MCP 通道通知\n├── scripts/\n│   ├── webhook_receiver.py    # Webhook 接收端 HTTP 服务\n│   └── setup.sh               # 一键安装脚本\n├── skill/SKILL.md             # AI Skill 定义\n└── data/                      # 运行时数据（gitignore）\n```\n\n### License\n\nMIT\n"}