{"id":34029816,"url":"https://github.com/niradler/mcp-planer","last_synced_at":"2026-04-08T15:33:25.886Z","repository":{"id":322161471,"uuid":"1087930629","full_name":"niradler/mcp-planer","owner":"niradler","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-02T22:15:48.000Z","size":116,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-15T08:09:19.524Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niradler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T23:51:44.000Z","updated_at":"2025-11-02T22:15:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niradler/mcp-planer","commit_stats":null,"previous_names":["niradler/mcp-planer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/niradler/mcp-planer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fmcp-planer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fmcp-planer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fmcp-planer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fmcp-planer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niradler","download_url":"https://codeload.github.com/niradler/mcp-planer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fmcp-planer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-13T17:54:01.149Z","updated_at":"2026-04-08T15:33:25.878Z","avatar_url":"https://github.com/niradler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Planer MCP Server\n\nAn intelligent planning and task management MCP server built with FastMCP that provides sophisticated planning tools optimized for software engineering projects.\n\n## Features\n\n- **🤖 LLM-Powered Task Generation**: Uses LLM sampling to generate context-aware, high-quality task breakdowns\n- **💬 Interactive Elicitation**: Asks clarifying questions to ensure requirements are well-understood\n- **✅ Plan Validation**: Preview and confirm plans before saving, with regeneration option\n- **📊 Progress Reporting**: Real-time progress updates during plan creation\n- **🎯 Engineering-Focused**: Optimized prompts for coding, debugging, system design, and feature development\n- **⏱️ Automatic Time Tracking**: Track actual time via plan/task creation and completion timestamps\n- **📄 Pagination**: Efficient handling of large plan lists (30 plans per page)\n- **🔍 Smart Filtering**: Hide completed plans by default, focus on active work\n- **💾 Persistent Storage**: SQLite database for reliable data persistence\n- **🏷️ Category-based Planning**: Different planning strategies based on task categories\n\n## How It Works\n\nWhen you create a new plan, the server uses an intelligent, LLM-driven workflow:\n\n1. **🧠 LLM Analyzes Requirements** (10% progress)\n   - The LLM evaluates if there's enough information\n   - Determines what's missing (if anything)\n   - Only asks for clarification when truly needed\n   - Users are NOT bothered unnecessarily!\n\n2. **💬 Smart Elicitation** (Conditional)\n   - **IF** LLM needs more info → Asks specific, targeted questions\n   - **ELSE** → Proceeds directly to task generation\n   - Example: \"Build REST API\" might not need questions\n   - Example: \"Migrate system\" likely needs clarification on tech stack\n\n3. **🤖 Generates Tasks with LLM** (30-60% progress)\n   - Uses LLM sampling to create context-aware tasks\n   - Applies category-specific planning strategies\n   - Considers dependencies and priorities\n   - Generates detailed task descriptions\n\n4. **👀 Shows Preview \u0026 Confirms** (80% progress)\n   - Displays the proposed plan\n   - You can: accept, request modifications, or cancel\n\n5. **🔁 Regenerates if Needed**\n   - If you request changes, LLM regenerates with your feedback\n   - Iterative refinement until you're satisfied\n\n6. **💾 Saves to Database** (95-100% progress)\n   - Stores the validated, high-quality plan\n\n## Tools Available\n\n### `new_plan` ⭐ Enhanced with Intelligent LLM-Driven Workflow\n\nCreates a new plan with intelligent task breakdown. The LLM decides when to ask for clarification - users are only bothered when necessary!\n\n**Smart Workflow:**\n1. **LLM analyzes** your request (10% progress)\n2. **Conditionally elicits** only if LLM needs more info\n3. **Generates tasks** using LLM sampling (30-60% progress)\n4. **Shows preview** and asks for confirmation (80% progress)\n5. **Regenerates** if you request modifications\n6. **Saves** validated plan (95-100% progress)\n\n**Parameters:**\n- `title`: Plan title (max 200 chars)\n- `goal`: Main goal or objective (max 500 chars)\n- `category`: One of: project, personal, learning, business, creative, research, maintenance\n- `description` (optional): Detailed description\n- `additional_context` (optional): Additional context for better planning\n\n**Key Features:**\n- 🧠 **Smart Elicitation**: LLM decides when questions are needed\n- 🎯 **No Unnecessary Interruptions**: Only asks when truly required\n- 📊 **Progress Reporting**: Real-time updates (10%, 30%, 60%, 80%, 95%, 100%)\n- 📝 **Comprehensive Logging**: Info, warning, error, debug messages\n- 🤖 **LLM-Powered**: High-quality, context-aware task generation\n- 🔁 **Feedback Loop**: Request modifications and regenerate\n- 🛡️ **Reliable**: Falls back to templates if LLM fails\n\n### `list_plans`\n\nList plans with pagination and filtering.\n\n**Parameters:**\n- `include_completed` (optional, default: False): Include completed plans\n- `page` (optional, default: 1): Page number (30 plans per page)\n\n### `get_plan`\n\nRetrieve detailed information about a specific plan.\n\n**Parameters:**\n- `plan_id`: ID of the plan to retrieve\n\n### `update_task_status`\n\nUpdate the status of specific tasks within a plan.\n\n**Parameters:**\n- `plan_id`: ID of the plan containing the tasks\n- `task_ids`: List of task IDs to update\n- `status`: One of: pending, in_progress, completed, deleted\n- `notes` (optional): Notes about the status change\n\n### `update_plan`\n\nUpdate existing plan by adding new tasks or changing plan info.\n\n**Parameters:**\n- `plan_id`: ID of the plan to update\n- `title` (optional): New title\n- `description` (optional): New description\n- `new_tasks` (optional): List of new task titles to add\n- `additional_context` (optional): Additional context for the update\n\n### `delete_plan`\n\nPermanently delete a plan and all its tasks from the database.\n\n**Parameters:**\n- `plan_id`: ID of the plan to delete\n\n## Installation\n\n### For Users (with uvx)\n\nThe easiest way to use Planer MCP is with `uvx`:\n\n```bash\nuvx planer-mcp\n```\n\nOr add it to your MCP configuration (e.g., in Cursor):\n\n```json\n{\n  \"mcpServers\": {\n    \"planer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"planer-mcp\"]\n    }\n  }\n}\n```\n\n### For Development\n\n```bash\ncd planer-mcp\n\nuv venv\n\nuv pip install -e \".[dev]\"\n```\n\n## Usage\n\n### Run with uvx (Recommended for Users)\n\n```bash\nuvx planer-mcp\n```\n\n### Run with Python Module (Development)\n\n```bash\nuv run python -m src.planer_mcp.server\n```\n\n### Run with main.py (Development)\n\n```bash\npython main.py\n# or\nuv run python main.py\n```\n\n### Configure in Cursor\n\nFor users:\n```json\n{\n  \"mcpServers\": {\n    \"planer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"planer-mcp\"]\n    }\n  }\n}\n```\n\nFor development:\n```json\n{\n  \"mcpServers\": {\n    \"planer\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"C:/Projects/mcp/planer-mcp\",\n        \"run\",\n        \"python\",\n        \"-m\",\n        \"src.planer_mcp.server\"\n      ]\n    }\n  }\n}\n```\n\nChange the `--directory` path to match your project location.\n\n## Development\n\n### Running Tests\n\n```bash\nmake test         # Run tests\nmake format       # Format code\nmake lint         # Lint code\nmake type-check   # Type checking\nmake dev-check    # Run all checks (format, type-check, test)\n```\n\n### Publishing to PyPI\n\n1. Update version in `pyproject.toml`\n2. Update `authors` and `urls` in `pyproject.toml`\n3. Commit all changes and create a git tag\n4. Build and publish:\n\n```bash\nmake build          # Build package\nmake publish-test   # Publish to TestPyPI (for testing)\nmake publish        # Publish to PyPI\n```\n\nOr manually with uv:\n\n```bash\nuv build\nuv publish\n```\n\n## Architecture\n\n- `src/planer_mcp/server.py` - FastMCP server implementation\n- `src/planer_mcp/models/schemas.py` - Pydantic data models\n- `src/planer_mcp/database/models.py` - SQLAlchemy ORM models\n- `src/planer_mcp/database/manager.py` - Database operations with query builder\n- `src/planer_mcp/planning/engine.py` - Planning logic\n- `src/planer_mcp/planning/formatter.py` - Output formatting\n- `src/planer_mcp/prompts/templates.py` - Category-specific prompts\n\n## Categories\n\n### Project (Software Engineering)\n- Requirements analysis and specification\n- System architecture and design\n- Database schema and data modeling\n- API design and implementation\n- Frontend/backend development\n- Testing strategy and implementation\n- CI/CD setup and deployment\n- Code review and quality gates\n- Performance optimization\n- Documentation and security\n\n### Learning (Skill Development)\n- Progressive skill building\n- Hands-on coding exercises\n- Real project development\n- Code review practice\n- Testing and debugging\n- Performance optimization\n- Architecture patterns\n\n### Business (Product Development)\n- Market research and validation\n- MVP feature definition\n- Technical architecture\n- Monitoring and analytics\n- User feedback integration\n- Iterative development\n\n### Creative (Design)\n- User research and personas\n- Design system and components\n- Wireframing and prototyping\n- Accessibility considerations\n- Design-dev handoff\n\n### Research (Investigation)\n- Problem statement definition\n- Technology evaluation\n- Proof of concept development\n- Performance benchmarking\n- Documentation of findings\n\n### Maintenance (Refactoring)\n- Code audit and technical debt\n- Dependency updates and patches\n- Test coverage improvement\n- Documentation updates\n- Performance profiling\n\n## Example Usage\n\n### Creating a Plan (LLM-Driven, Smart Elicitation)\n\n**Example 1: Sufficient Information (No Elicitation)**\n```\nUser: Create plan for \"Build REST API with FastAPI\"\n\nServer: [Progress 10%] Analyzing requirements...\nServer: [Info] Sufficient information provided, generating task list...\nServer: [Progress 30%] Generating tasks with LLM...\nServer: [Progress 60%] Parsing generated tasks...\nServer: [Info] Generated 12 tasks from LLM\nServer: [Progress 80%] Validating plan...\n\n[Plan Preview shows 12 detailed tasks]\n\nServer: Does this plan look correct?\n- Type 'yes' to save\n- Type modifications to regenerate\n- Type 'cancel' to abort\n\nUser: yes\n\nServer: [Progress 100%] Plan created successfully!\n```\n\n**Example 2: LLM Needs Clarification (Smart Elicitation)**\n```\nUser: Create plan for \"Migrate legacy system to cloud\"\n\nServer: [Progress 10%] Analyzing requirements...\nServer: [Info] LLM needs clarification: Critical tech stack info missing\n\nTo create an effective plan for 'Migrate legacy system to cloud', please provide:\n1. What is the current technology stack?\n2. Which cloud provider (AWS/Azure/GCP)?\n3. What's the current deployment architecture?\n4. What's the timeline/phased approach preference?\n\nUser: Currently on-premise Java monolith with MySQL. Moving to AWS. \n      3-month timeline, want microservices architecture.\n\nServer: [Info] Additional context received, generating optimized task list...\nServer: [Progress 30%] Generating tasks with LLM...\nServer: [Info] Generated 18 tasks from LLM\n...\n```\n\n**Example 3: Request Modifications**\n```\n[After plan preview]\n\nUser: Add more testing tasks and include performance benchmarks\n\nServer: [Info] Regenerating plan with user feedback...\nServer: [Info] Regenerated plan with 16 tasks\nServer: [Progress 95%] Saving plan to database...\n```\n\n### Listing Active Plans\n\n```bash\n# Only active (incomplete) plans\nlist_plans()\n\n# Include completed plans\nlist_plans(include_completed=True)\n\n# Pagination\nlist_plans(page=2)\n```\n\n### Managing Tasks\n\n```bash\n# Mark tasks complete\nupdate_task_status(plan_id=1, task_ids=[1, 2, 3], status=\"completed\")\n\n# Set tasks in progress\nupdate_task_status(plan_id=1, task_ids=[4, 5], status=\"in_progress\", notes=\"Started backend work\")\n```\n\n## Best Practices\n\n- All `__init__.py` files ONLY contain imports/exports\n- Code is in properly named files (schemas.py, manager.py, etc.)\n- SQLAlchemy query builder for all database operations\n- Type hints throughout\n- FastMCP for clean, modern MCP server implementation\n\n## Testing\n\n```bash\nuv run pytest tests/ -v\n```\n\nAll 12 tests passing with 100% coverage of core functionality.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Fmcp-planer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniradler%2Fmcp-planer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Fmcp-planer/lists"}