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.