GitHub - artpar/longterm-planner-mcp: MCP server for long-term planning management in Claude Code

longterm-planner-mcp

A Model Context Protocol (MCP) server for long-term planning management in Claude Code. Track plans, tasks, goals, and progress across coding sessions with persistent SQLite storage.

Features

• Persistent Planning - SQLite database stores plans and tasks across sessions
• Task Management - Full lifecycle: backlog → ready → in_progress → review → completed
• State Machine - Enforced status transitions prevent invalid task states
• Task Dependencies - Define blocking relationships with circular dependency detection
• Plan Templates - 10 built-in templates for common project types (web apps, APIs, etc.)
• Search & Filter - Find tasks across plans by text, status, priority, dates, tags, assignee
• Task Tags - Categorize tasks with custom labels for organization
• Task Comments - Add timestamped notes and updates to tasks
• Bulk Operations - Update status, priority, tags, or delete multiple tasks at once
• Progress Tracking - Track estimated vs actual hours, completion stats
• Git Integration - Link commits to tasks via branch names or commit messages
• Export/Import - Export plans to JSON or Markdown, import from JSON
• Session Continuity - Pick up where you left off with context preservation
• Backup & Restore - Automated backups with rotation

When to Use

Worth it for:

• Multi-session projects where context is lost between conversations
• Team handoffs - persisted state others can pick up
• Complex features with many task dependencies
• Audit trail of decisions and progress

Overhead for:

• Single-session tasks (Claude Code's built-in TodoWrite is lighter)
• Solo work where you remember context
• Simple bug fixes or quick features

Roadmap

• Auto-summarize progress when starting a new session
• Deeper git integration (auto-link commits to tasks)
• Session continuity prompts ("Last time you were working on X...")
• Time tracking and estimates vs actuals reporting

Installation

For Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "planning": {
      "command": "npx",
      "args": ["-y", "longterm-planner-mcp"]
    }
  }
}

Restart Claude Code to load the server.

Standalone

Or install globally:

npm install -g longterm-planner-mcp
longterm-planner-mcp

Usage

Once installed, Claude Code gains access to planning tools, resources, and prompts.

Quick Start

Create a plan for my current project with tasks for the authentication feature

Claude will use the MCP tools to:

1. Create a plan linked to your project
2. Add tasks for the feature
3. Track progress as you work

Example Workflow

# Start a planning session
> Let's plan the user authentication feature

# Claude creates plan and tasks via MCP tools

# Start working on a task
> I'm starting work on the login form task

# Claude marks task as in_progress

# Complete the task
> The login form is done, tests passing

# Claude moves task to completed, logs progress

Tools

Plan Management

Task Management

Templates

Built-in templates: web-app, rest-api, cli-tool, library, bug-fix, feature, project-kickoff, sprint, release, migration

Dependencies

Search & Filter

Export/Import

Tags

Bulk Operations

Comments

Session

Example output:

Last session: 2d ago
Auth System: 5/12 (42%)
  active: Login form, OAuth setup
  blocked: DB migration
  ready: 3 task(s)
Last: Completed login validation (2d ago)

Resources

Access plan data via MCP resources:

Prompts

Pre-built prompts for common planning scenarios:

Data Storage

Plans are stored in SQLite at .claude/planning/plans.db within each project directory. This keeps planning data isolated per project and version-controllable if desired.

Upgrading from v0.2.9 or earlier

Previous versions stored all plans in a global database at ~/.claude/planning/plans.db. Version 0.2.10+ automatically migrates your data:

1. Update the package: Just restart Claude Code - it uses npx -y which fetches the latest version
2. Migration runs automatically: On first startup, existing plans are copied to their respective project directories
3. Global database archived: The old database is renamed to plans.db.migrated as a backup

No action required - the migration is seamless and preserves all your data.

Schema

• plans - Project plans with status, dates, context
• tasks - Tasks with status, priority, estimates, tags, assignments
• task_comments - Timestamped comments on tasks
• goals - High-level goals (hierarchical)
• objectives - Measurable objectives under goals
• milestones - Time-bound checkpoints
• dependencies - Task/goal dependencies
• blockers - Issues blocking progress
• progress_logs - Activity history
• sessions - Planning session tracking

Task States

Tasks follow a defined state machine:

                    ┌──────────┐
                    │ CANCELLED│
                    └──────────┘
                         ↑
┌────────┐    ┌───────┐  │  ┌─────────────┐    ┌────────┐    ┌───────────┐
│BACKLOG │ →  │ READY │ ─┼→ │ IN_PROGRESS │ →  │ REVIEW │ →  │ COMPLETED │
└────────┘    └───────┘  │  └─────────────┘    └────────┘    └───────────┘
                         │         ↓ ↑
                         │    ┌─────────┐
                         └────│ BLOCKED │
                              └─────────┘

Valid transitions:

• backlog → ready, cancelled
• ready → in_progress, backlog, cancelled
• in_progress → review, blocked, cancelled
• blocked → in_progress, cancelled
• review → completed, in_progress, cancelled

Git Integration

Link commits to tasks automatically:

Via Commit Message

git commit -m "Add login validation #task-abc123"

Via Branch Name

git checkout -b feature/task-abc123-login-form

The server parses task references and links commits for traceability.

Programmatic Usage

import {
  PlanningServer,
  Database,
  PlanRepository,
  TaskService
} from 'longterm-planner-mcp';

// Use the server
const server = new PlanningServer({
  dbPath: './my-plans.db'
});
await server.start();

// Or use components directly
const db = new Database('./plans.db');
const planRepo = new PlanRepository(db);
const plan = planRepo.create({
  projectPath: '/my/project',
  name: 'My Plan'
});

Configuration

Environment variables:

Development

# Clone the repo
git clone https://github.com/artpar/longterm-planner-mcp
cd longterm-planner-mcp

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run locally
npm start

Testing

# Run all tests
npm run test:run

# Watch mode
npm test

# Coverage
npm run test:coverage

Requirements

• Node.js >= 18.0.0
• Claude Code (for MCP integration)

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines and submit PRs.

Related

• Model Context Protocol - MCP specification
• Claude Code - AI coding assistant