Mcpp Plan

A persistent task and step tracker for AI coding agents. Gives Claude Code (or any MCP-compatible agent) the ability to break work into tasks, track steps within each task, and remember exactly where it left off across sessions.

New here? See RAPIDSTART.md — clone, configure, and start using it in under 10 minutes.

Dogfooded daily. This module is developed, maintained, and continuously improved using itself. Every feature gets real-world testing the moment it's built.

Agent-portable. Start a task in one agent, pick it up in another — no context lost. The state lives in the database, not the conversation.

Why

AI agents lose context between sessions. When you resume a conversation, the agent doesn't know what it was doing, which steps are done, or what's next. mcpp-plan solves this by giving agents a structured, persistent task manager backed by SQLite.

The agent talks to it through MCP tools. You talk to the agent in plain English. The agent manages the rest.

How it works

project
  └── user (auto-detected from $USER)
        └── task (a focus area, like "build login page")
              └── step (individual action, like "create user table")

• Tasks are top-level work items (features, bugs, refactors)
• Steps are ordered actions within a task
• One task and one step are active at a time -- the agent always knows what to do next
• State persists in plan.db within the module directory
• Multi-user -- each OS user gets independent task cursors within a shared database

Installation

mcpp-plan is an mcpp tool module. Install it by adding the tool path to your mcpp configuration.

Prerequisites

• Python 3.10+
• SQLite 3 (bundled with Python)
• An MCP-compatible agent (Claude Code, etc.)

Setup

1. Clone both repos as siblings:

cd ~/projects
git clone [email protected]:pacmac/mcpp.git
git clone [email protected]:pacmac/mcpp-plan.git

mcpp's default tools.yaml already includes ../mcpp-plan, so no extra configuration is needed if they're side by side.

2. Register the MCP server with Claude Code:

claude mcp add mcpp --scope user \
  --env MCPP_LOG_LEVEL=error \
  --env MCPP_TIMEOUT_SECONDS=30 \
  -- python3 ~/projects/mcpp/mcpp.py

Replace ~/projects with your install folder.

3. The database is created automatically as plan.db in the module directory on first use. No setup required.

Tools

All tools are exposed via MCP with the plan_ prefix.

Task tools

Tool	Description
plan_task_new	Create a task with initial steps; optional area to assign a functional area
plan_task_list	List tasks (yours by default, show_all for everyone); optional area to filter
plan_task_show	Show a task and its steps
plan_task_status	Show active task and progress
plan_task_switch	Switch to a different task
plan_task_complete	Mark a task as completed
plan_task_move	Move a task to a different project (reports attached files to move manually)
plan_task_rename	Rename a task's display title (slug unchanged, history preserved)
plan_step_retitle	Retitle a step (status/completed_at/order unchanged)
plan_task_adopt	Adopt (deep-copy) another user's task into your own list
plan_task_set_area	Set or clear the functional area on a task
plan_task_notes_set	Set a note on a task (upsert: goal/plan replace by kind, note updates by ID or creates new)
plan_task_notes_get	View notes on a task (returns notes with IDs)
plan_task_notes_delete	Delete a note from a task by ID

Area tools

Tool	Description
plan_area_new	Define a functional area for this project (stored in plan.db)
plan_area_list	List functional areas defined for this project
plan_area_rename	Rename an area; cascades to all tasks assigned to it
plan_area_delete	Delete an area (refuses if tasks are still assigned)

Step tools

Tool	Description
plan_step_list	List steps in a task
plan_step_show	Show step details
plan_step_switch	Switch to a specific step
plan_step_done	Mark a step as complete
plan_step_new	Add a step to a task
plan_step_delete	Soft-delete a step
plan_step_reorder	Reorder steps within a task
plan_step_notes_set	Set a note on a step (upsert: updates by ID or creates new)
plan_step_notes_get	View notes on a step (returns notes with IDs)
plan_step_notes_delete	Delete a note from a step by ID

User tools

Tool	Description
plan_user_show	Show current user info
plan_user_set	Set your display name

Project tools

Tool	Description
plan_project_show	Show project metadata
plan_project_list	List all known projects
plan_project_set	Set project name and description (key-gated when web.key is set)
plan_project_select	Select active project by ID (hidden from agents, requires web.key)
plan_project_relink	Relink an existing project after moving or renaming its workspace
plan_project_purge	Permanently delete a project and all its data from the database (exports a markdown backup first)

File attachment tools

Tool	Description
plan_file_attach	Attach a workspace-relative file to a project, task, or step
plan_file_detach	Remove an attachment by ID (does not delete the file)
plan_file_list	List attachments for the active project, task, or step, with inline content

Report tools

Tool	Description
plan_project_report	Generate a project report (.md) with all tasks, goals, plans, and steps
plan_task_report	Generate a task report (.md) with goal, plan, steps, and notes

Reports are written to the workspace directory with date-stamped filenames (e.g. project_report_260215.md, task_report_build-auth_260215.md). Same-day files are overwritten.

Version control

Git operations (checkpoint, commit, push, log, status, diff, file history, file restore) are provided by mcpp-git as dev_* tools. Calling the old plan_* git tool names returns a redirect message pointing to the correct dev_* equivalent.

Web API (project selection)

When mcpp-plan is accessed from a web server (no workspace_dir context), the server needs to explicitly select which project to operate on.

Setup: Add a secret key to config.yaml:

web:
  key: "your-secret-key-here"

How it works:

1. The web server calls plan_project_list to show available projects
2. The user picks a project
3. The web server calls plan_project_select with the project ID and key
4. All subsequent tool calls use that project instead of auto-detecting from workspace
5. Pass project_id: 0 to clear the override and revert to auto-detect

Security:

• plan_project_select is hidden from MCP discovery — agents never see it
• Both plan_project_select and plan_project_set require the key parameter when web.key is configured
• plan_project_list is open — agents can list projects but cannot select or modify them
• When web.key is empty (default), the key gate is inactive and plan_project_set works without a key

Config tools

Tool	Description
plan_config_show	Show current configuration (merged defaults + overrides)

Utility

Tool	Description
plan_readme	Display the user-facing README

Usage

You interact with plan through your agent in natural language. Examples:

"Create a task called build-auth with steps: design schema, implement JWT, add middleware, write tests"

"What am I working on?"

"Mark step 1 as done"

"Switch to step 2"

"Add a note: decided to use refresh tokens"

"Show me all my tasks"

"Switch to the fix-search task"

The agent translates these into MCP tool calls automatically.

Step lifecycle

planned  →  started  →  complete

Only one step can be started at a time within a task. When you switch steps, the new one becomes started. Completing a step marks it complete.

Note kinds

Notes have a kind field that classifies their purpose:

Kind	Purpose	When to use
goal	What needs to be achieved	Before starting work -- defines the objective
plan	How it will be done	Before starting work -- defines the approach
note	Observations and updates	During execution -- freeform (default)

Setting notes

Use _set tools to create or update notes. For goal/plan kinds, the note is upserted by kind (only one goal and one plan per task). For regular notes, pass an id to update or omit to create new:

plan_task_notes_set  text="Implement user authentication"  kind="goal"
plan_task_notes_set  text="Use JWT with refresh tokens"    kind="plan"
plan_task_notes_set  text="Decided to skip OAuth for now"

Setting goal or plan again replaces the existing one — no duplicates.

Reading notes

Use _get tools to view notes. Notes are returned with IDs so you can update or delete them:

plan_task_notes_get                  # all notes
plan_task_notes_get  kind="goal"     # only goal notes

Updating and deleting notes

Pass the note id (returned by _get, _set, show, and switch) to update or delete:

plan_task_notes_set     text="Revised note"  id=42    # update note 42
plan_task_notes_delete  id=42                          # delete note 42

Workflow enforcement

By default, tasks require at least one goal and one plan note before steps can be switched or completed. This ensures every task has a clear objective and approach before implementation begins. Disable this in config.yaml:

workflow:
  require_goal_and_plan: false

Display

plan_task_show and plan_task_switch display goal and plan notes inline and return all notes with IDs, so the purpose and approach are always visible and notes can be updated in a single follow-up call. plan_step_show and plan_step_switch similarly include step notes with IDs.

Migrated tasks

Tasks that existed before note kinds were introduced have migration placeholder notes ("(migrated — no goal defined)"). These are not displayed in plan_task_show and do not satisfy workflow enforcement. Replace them by adding real goal and plan notes to those tasks.

Task adoption

Use plan_task_adopt to deep-copy another user's task (or clone your own) into your task list. This is useful when multiple agents or users want to work on similar tasks independently, or when you want to fork a task as a starting point.

plan_task_adopt  name="build-auth"  new_name="build-auth-v2"

What gets copied:

• Task metadata (name, description)
• All steps (with parent references remapped)
• All task-level notes (goal, plan, note)
• All step-level notes

What does not get copied:

• Changelog — a single "Adopted from {user}/{task}" entry is created instead

By default, all step statuses are reset to planned so you start fresh. Pass reset=false to preserve original statuses.

The adopted task becomes active automatically. A new_name is required if a task with the source name already exists in the project.

Database

All state lives in a single SQLite database at plan.db in the module directory, shared across all projects. Each project is identified by its absolute filesystem path. If you move or rename a workspace, call plan_project_relink with exactly one selector (project_id, old_path, or unique name) to update the saved path to the current workspace. If an empty placeholder project was already created at the new path, relinking removes it; if the target path already has tasks or user state, relinking stops with a conflict.

Schema

Core tables:

• project -- workspace metadata (name, path, description)
• users -- OS users with optional display names
• contexts -- tasks (name, status, owner, project)
• tasks -- steps within a task (title, status, ordering)
• context_state -- active step cursor per task
• user_state -- active task cursor per user per project
• user_prefs -- per-user preferences (active project override for web access)
• context_notes / task_notes -- typed notes (goal, plan, note)
• changelog -- audit log of all state changes

Schema migrations are applied automatically via numbered patches in schema_patches/.

Configuration

Global settings live in config.yaml in the module directory (alongside plan.db). The file is optional — all keys have sensible defaults. Settings are organized by section.

workflow:
  require_goal_and_plan: true      # require goal and plan notes before step progress
  allow_reopen_completed: false    # allow switching to completed tasks (reopens them)
  daily_backup: true               # create one backup per day on first use
  backup_retain_days: 7            # delete backups older than this many days
  enable_steps: true               # set false to hide step tools and strip step data
  stale_task_days: 0               # nag when a task has no activity for N days (0 = disabled)

web:
  key: ""                          # web API key (empty = disabled, set to enable project selection)

Feature Toggles

Disable features you don't need:

workflow:
  enable_steps: false        # hide step tools, strip step data from results

When disabled:

• Tools are hidden from MCP discovery (tools/list)
• Direct calls return a clear error: "Tool 'X' is disabled (enable_Y: false in config.yaml)"
• Step data is stripped from task results and display text

Defaults

Section	Key	Default	Description
workflow	require_goal_and_plan	true	Require goal and plan notes before step progress
workflow	allow_reopen_completed	false	Allow switching to completed tasks (sets them back to active)
workflow	daily_backup	true	Create one backup per day on first use
workflow	backup_retain_days	7	Delete backups older than this many days
workflow	enable_steps	true	Set false to hide step tools and strip step data
web	key	""	Web API key for project selection (empty = disabled)
attachments	inline_lines	100	Max lines of an attached file to inline in show output

Behavior

• Missing file = all defaults
• Missing keys = defaults for those keys
• Unknown keys are preserved in the file but ignored by the system
• Invalid YAML falls back to all defaults

Tools

• plan_config_show -- show current settings (merged defaults + overrides)
• Config is read-only from MCP — edit config.yaml directly to change settings

File Attachments

Attach workspace files (specs, design docs, READMEs) to a project, task, or step as a single source of truth. The file path is stored in the database; content is read from the file at display time — no duplication.

plan_file_attach  file_path="specs/feature.md"  scope=task  label="Feature spec"
plan_file_attach  file_path="ARCHITECTURE.md"   scope=project
plan_file_attach  file_path="steps/step1.md"    scope=step  kind=plan

plan_file_list               # active task's attachments (with inline content)
plan_file_list  scope=project
plan_file_detach  id=3

Scope

Scope	Attached to
task (default)	Active task (context)
project	The current project
step	The active step

Kind

Kind	Purpose
ref (default)	General reference document
goal	The file defines what needs to be achieved
plan	The file defines how it will be done

Path rules

• Must be relative to the workspace root (specs/feature.md, not /home/user/specs/feature.md)
• Must not escape the workspace (no ../ traversal)
• The file does not need to exist at attach time — broken links are flagged with ⚠ on list

Inline display

plan_file_list, plan_project_show, plan_task_show, and plan_step_show inline attached file content up to attachment_inline_lines (default 100). Files longer than that show a truncation notice.

Automated reminders

mcpp-plan injects contextual reminders into tool responses to keep the project clean.

Done-but-not-closed nag

Every tool response checks whether any task in the current project has all steps marked complete but was never closed with plan_task_complete. If found, a warning is appended:

⚠ 2 task(s) have all steps complete but are not closed: `build-auth`, `fix-search`.
  Call plan_task_complete for each.

This fires on every call until the tasks are closed. The goal is zero outstanding tasks per project. Suppressed during a plan_task_complete call itself.

Project info nudge

If the current project has no name or description set, a one-time nudge prompts the agent to call plan_project_set. Suppressed once set.

Migration safety

Schema migrations are protected by a multi-layer safety pipeline (backup.py):

1. Verified backup -- plan.db is copied to .backups/plan.db.YYMMDDx and the SHA-256 checksum is verified to match the live DB before proceeding.
2. Trial migration on a copy -- all patches are applied to a temporary copy of the database first. If the trial fails (SQL error or data loss), the live DB is never touched.
3. Row count validation -- after the trial, every table's row count is compared to pre-migration counts. Any decrease aborts the migration.
4. Live migration + re-validation -- only after the trial passes are patches applied to the live DB, followed by a second row count validation.

If anything fails at any step, the migration aborts with a clear error message and the path to the backup file. The live database is left untouched.

Backups use letter suffixes (a-z) for multiple backups on the same day. Migration backups are created when patches are applied. Additionally, a daily auto-backup runs on first use each day (configurable via daily_backup), with automatic pruning of backups older than backup_retain_days.

Hints & Tips

Orient the agent on a new project. When starting work on a fresh codebase, have the agent explore it first:

> Discover what this project is about, including its structure,
> and add what you learn to the project notes.

This lets the agent build its own understanding of the codebase -- what's where, how things connect, what conventions are used -- and persist that context for future sessions.

Capture ideas without losing focus. If you spot an unrelated issue or think of something while working on a task, tell the agent to note it and carry on:

> Add a task: "refactor the cache expiry logic" -- then continue
> what you were doing.

This keeps your current flow intact while making sure the thought doesn't get lost.

Let the agent plan first. For complex tasks, have it think before writing code:

> Plan how you'd approach this before writing code.

Use help for discovery. Agents can call the built-in help tool to see what's available — no need to remember tool names:

> What mcpp tools do you have?

Architecture

tool.yaml          MCP tool definitions (schema for all plan_* tools)
mcpptool.py        MCP entry point -- routes tool calls to Python API
context.py         Business logic (create/switch/complete tasks and steps)
config.py          Global configuration (config.yaml loading + defaults)
db.py              SQLite connection, schema management, user/project helpers
backup.py          Migration safety pipeline (verified backup, trial-on-copy, row validation)
schema.sql         Base schema
schema_patches/    Incremental migrations (patch-4.sql through patch-11.sql)

Entry points

• execute(tool_name, arguments, context) -- called by the MCP host for every tool invocation
• get_info(context) -- returns tool metadata and existing task names for autocomplete

How a tool call flows

1. MCP host calls execute("plan_step_done", {"number": 3}, {"workspace_dir": "/my/project"})
2. mcpptool.py routes to _cmd_step_done
3. Handler builds a command list and calls _run_plan_cmd
4. _run_plan_cmd dynamically imports db.py and context.py, opens the central DB, and dispatches
5. context.py runs the operation in a transaction
6. Result dict is returned with structured data and a display string for the user

Inspired By

This project was inspired by Andreas Spiess (GitHub) and his video on AI-assisted coding.

Release Notes

See RELEASE.md for the full version history.

License

PolyForm Noncommercial 1.0.0

Free for personal use, research, education, non-profits, and government. Not permitted for commercial use. See LICENSE for the full text.