# 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`:

```bash
uvx planer-mcp
```

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

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

### For Development

```bash
cd planer-mcp

uv venv

uv pip install -e ".[dev]"
```

## Usage

### Run with uvx (Recommended for Users)

```bash
uvx planer-mcp
```

### Run with Python Module (Development)

```bash
uv run python -m src.planer_mcp.server
```

### Run with main.py (Development)

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

### Configure in Cursor

For users:
```json
{
  "mcpServers": {
    "planer": {
      "command": "uvx",
      "args": ["planer-mcp"]
    }
  }
}
```

For development:
```json
{
  "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

```bash
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:

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

Or manually with uv:

```bash
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

```bash
# Only active (incomplete) plans
list_plans()

# Include completed plans
list_plans(include_completed=True)

# Pagination
list_plans(page=2)
```

### Managing Tasks

```bash
# 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

```bash
uv run pytest tests/ -v
```

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