planer-mcp 0.1.0

MCP server for intelligent planning and task management

Planer MCP Server

An intelligent planning and task management MCP server built with FastMCP that provides sophisticated planning tools optimized for software engineering projects.

Features

• 🤖 LLM-Powered Task Generation: Uses LLM sampling to generate context-aware, high-quality task breakdowns
• 💬 Interactive Elicitation: Asks clarifying questions to ensure requirements are well-understood
• ✅ Plan Validation: Preview and confirm plans before saving, with regeneration option
• 📊 Progress Reporting: Real-time progress updates during plan creation
• 🎯 Engineering-Focused: Optimized prompts for coding, debugging, system design, and feature development
• ⏱️ Automatic Time Tracking: Track actual time via plan/task creation and completion timestamps
• 📄 Pagination: Efficient handling of large plan lists (30 plans per page)
• 🔍 Smart Filtering: Hide completed plans by default, focus on active work
• 💾 Persistent Storage: SQLite database for reliable data persistence
• 🏷️ Category-based Planning: Different planning strategies based on task categories

How It Works

When you create a new plan, the server uses an intelligent, LLM-driven workflow:

1. 🧠 LLM Analyzes Requirements (10% progress)

   • The LLM evaluates if there's enough information
   • Determines what's missing (if anything)
   • Only asks for clarification when truly needed
   • Users are NOT bothered unnecessarily!

2. 💬 Smart Elicitation (Conditional)

   • IF LLM needs more info → Asks specific, targeted questions
   • ELSE → Proceeds directly to task generation
   • Example: "Build REST API" might not need questions
   • Example: "Migrate system" likely needs clarification on tech stack

3. 🤖 Generates Tasks with LLM (30-60% progress)

   • Uses LLM sampling to create context-aware tasks
   • Applies category-specific planning strategies
   • Considers dependencies and priorities
   • Generates detailed task descriptions

4. 👀 Shows Preview & Confirms (80% progress)

   • Displays the proposed plan
   • You can: accept, request modifications, or cancel

5. 🔁 Regenerates if Needed

   • If you request changes, LLM regenerates with your feedback
   • Iterative refinement until you're satisfied

6. 💾 Saves to Database (95-100% progress)

   • Stores the validated, high-quality plan

Tools Available

new_plan ⭐ Enhanced with Intelligent LLM-Driven Workflow

Creates a new plan with intelligent task breakdown. The LLM decides when to ask for clarification - users are only bothered when necessary!

Smart Workflow:

1. LLM analyzes your request (10% progress)
2. Conditionally elicits only if LLM needs more info
3. Generates tasks using LLM sampling (30-60% progress)
4. Shows preview and asks for confirmation (80% progress)
5. Regenerates if you request modifications
6. Saves validated plan (95-100% progress)

Parameters:

• title: Plan title (max 200 chars)
• goal: Main goal or objective (max 500 chars)
• category: One of: project, personal, learning, business, creative, research, maintenance
• description (optional): Detailed description
• additional_context (optional): Additional context for better planning

Key Features:

• 🧠 Smart Elicitation: LLM decides when questions are needed
• 🎯 No Unnecessary Interruptions: Only asks when truly required
• 📊 Progress Reporting: Real-time updates (10%, 30%, 60%, 80%, 95%, 100%)
• 📝 Comprehensive Logging: Info, warning, error, debug messages
• 🤖 LLM-Powered: High-quality, context-aware task generation
• 🔁 Feedback Loop: Request modifications and regenerate
• 🛡️ Reliable: Falls back to templates if LLM fails

list_plans

List plans with pagination and filtering.

Parameters:

• include_completed (optional, default: False): Include completed plans
• page (optional, default: 1): Page number (30 plans per page)

get_plan

Retrieve detailed information about a specific plan.

Parameters:

• plan_id: ID of the plan to retrieve

update_task_status

Update the status of specific tasks within a plan.

Parameters:

• plan_id: ID of the plan containing the tasks
• task_ids: List of task IDs to update
• status: One of: pending, in_progress, completed, deleted
• notes (optional): Notes about the status change

update_plan

Update existing plan by adding new tasks or changing plan info.

Parameters:

• plan_id: ID of the plan to update
• title (optional): New title
• description (optional): New description
• new_tasks (optional): List of new task titles to add
• additional_context (optional): Additional context for the update

delete_plan

Permanently delete a plan and all its tasks from the database.

Parameters:

• plan_id: ID of the plan to delete

Installation

For Users (with uvx)

The easiest way to use Planer MCP is with uvx:

uvx planer-mcp

Or add it to your MCP configuration (e.g., in Cursor):

{
  "mcpServers": {
    "planer": {
      "command": "uvx",
      "args": ["planer-mcp"]
    }
  }
}

For Development

cd planer-mcp

uv venv

uv pip install -e ".[dev]"

Usage

Run with uvx (Recommended for Users)

uvx planer-mcp

Run with Python Module (Development)

uv run python -m src.planer_mcp.server

Run with main.py (Development)

python main.py
# or
uv run python main.py

Configure in Cursor

For users:

{
  "mcpServers": {
    "planer": {
      "command": "uvx",
      "args": ["planer-mcp"]
    }
  }
}

For development:

{
  "mcpServers": {
    "planer": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Projects/mcp/planer-mcp",
        "run",
        "python",
        "-m",
        "src.planer_mcp.server"
      ]
    }
  }
}

Change the --directory path to match your project location.

Development

Running Tests

make test         # Run tests
make format       # Format code
make lint         # Lint code
make type-check   # Type checking
make dev-check    # Run all checks (format, type-check, test)

Publishing to PyPI

1. Update version in pyproject.toml
2. Update authors and urls in pyproject.toml
3. Commit all changes and create a git tag
4. Build and publish:

make build          # Build package
make publish-test   # Publish to TestPyPI (for testing)
make publish        # Publish to PyPI

Or manually with uv:

uv build
uv publish

Architecture

• src/planer_mcp/server.py - FastMCP server implementation
• src/planer_mcp/models/schemas.py - Pydantic data models
• src/planer_mcp/database/models.py - SQLAlchemy ORM models
• src/planer_mcp/database/manager.py - Database operations with query builder
• src/planer_mcp/planning/engine.py - Planning logic
• src/planer_mcp/planning/formatter.py - Output formatting
• src/planer_mcp/prompts/templates.py - Category-specific prompts

Categories

Project (Software Engineering)

• Requirements analysis and specification
• System architecture and design
• Database schema and data modeling
• API design and implementation
• Frontend/backend development
• Testing strategy and implementation
• CI/CD setup and deployment
• Code review and quality gates
• Performance optimization
• Documentation and security

Learning (Skill Development)

• Progressive skill building
• Hands-on coding exercises
• Real project development
• Code review practice
• Testing and debugging
• Performance optimization
• Architecture patterns

Business (Product Development)

• Market research and validation
• MVP feature definition
• Technical architecture
• Monitoring and analytics
• User feedback integration
• Iterative development

Creative (Design)

• User research and personas
• Design system and components
• Wireframing and prototyping
• Accessibility considerations
• Design-dev handoff

Research (Investigation)

• Problem statement definition
• Technology evaluation
• Proof of concept development
• Performance benchmarking
• Documentation of findings

Maintenance (Refactoring)

• Code audit and technical debt
• Dependency updates and patches
• Test coverage improvement
• Documentation updates
• Performance profiling

Example Usage

Creating a Plan (LLM-Driven, Smart Elicitation)

Example 1: Sufficient Information (No Elicitation)

User: Create plan for "Build REST API with FastAPI"

Server: [Progress 10%] Analyzing requirements...
Server: [Info] Sufficient information provided, generating task list...
Server: [Progress 30%] Generating tasks with LLM...
Server: [Progress 60%] Parsing generated tasks...
Server: [Info] Generated 12 tasks from LLM
Server: [Progress 80%] Validating plan...

[Plan Preview shows 12 detailed tasks]

Server: Does this plan look correct?
- Type 'yes' to save
- Type modifications to regenerate
- Type 'cancel' to abort

User: yes

Server: [Progress 100%] Plan created successfully!

Example 2: LLM Needs Clarification (Smart Elicitation)

User: Create plan for "Migrate legacy system to cloud"

Server: [Progress 10%] Analyzing requirements...
Server: [Info] LLM needs clarification: Critical tech stack info missing

To create an effective plan for 'Migrate legacy system to cloud', please provide:
1. What is the current technology stack?
2. Which cloud provider (AWS/Azure/GCP)?
3. What's the current deployment architecture?
4. What's the timeline/phased approach preference?

User: Currently on-premise Java monolith with MySQL. Moving to AWS. 
      3-month timeline, want microservices architecture.

Server: [Info] Additional context received, generating optimized task list...
Server: [Progress 30%] Generating tasks with LLM...
Server: [Info] Generated 18 tasks from LLM
...

Example 3: Request Modifications

[After plan preview]

User: Add more testing tasks and include performance benchmarks

Server: [Info] Regenerating plan with user feedback...
Server: [Info] Regenerated plan with 16 tasks
Server: [Progress 95%] Saving plan to database...

Listing Active Plans

# Only active (incomplete) plans
list_plans()

# Include completed plans
list_plans(include_completed=True)

# Pagination
list_plans(page=2)

Managing Tasks

# Mark tasks complete
update_task_status(plan_id=1, task_ids=[1, 2, 3], status="completed")

# Set tasks in progress
update_task_status(plan_id=1, task_ids=[4, 5], status="in_progress", notes="Started backend work")

Best Practices

• All __init__.py files ONLY contain imports/exports
• Code is in properly named files (schemas.py, manager.py, etc.)
• SQLAlchemy query builder for all database operations
• Type hints throughout
• FastMCP for clean, modern MCP server implementation

Testing

uv run pytest tests/ -v

All 12 tests passing with 100% coverage of core functionality.