MCP Project Planning Tool - Usage Examples

This document demonstrates how to use the new MCP Project Planning Tool that addresses the gaps identified in issue #93.

Tool Overview

The mcp_planning tool provides comprehensive project planning and workflow management capabilities that integrate seamlessly with existing ADR Analysis tools.

Available Operations

1. create_project - Initialize project with phases, milestones, and team structure
2. manage_phases - Phase lifecycle management (planning → active → completed)
3. track_progress - Real-time progress monitoring with visual dashboards
4. manage_resources - Team member allocation and workload balancing
5. risk_analysis - Automated risk assessment based on ADR complexity
6. generate_reports - Executive summaries and status reports

Usage Examples

1. Create a New Project

{
  "tool": "mcp_planning",
  "arguments": {
    "operation": "create_project",
    "projectPath": "/path/to/your/project",
    "projectName": "ServiceNow OpenShift Integration",
    "description": "Integrate ServiceNow with OpenShift using Keycloak OIDC",
    "phases": [
      {
        "name": "Phase 1: Keycloak & OIDC Setup",
        "duration": "2 weeks",
        "dependencies": [],
        "milestones": ["Keycloak deployed", "OIDC configured"]
      },
      {
        "name": "Phase 2: ServiceNow Integration",
        "duration": "3 weeks", 
        "dependencies": ["Phase 1"],
        "milestones": ["ServiceNow connected", "Authentication flow tested"]
      },
      {
        "name": "Phase 3: Testing & Deployment",
        "duration": "1 week",
        "dependencies": ["Phase 2"],
        "milestones": ["End-to-end testing complete", "Production deployment"]
      }
    ],
    "team": [
      {
        "name": "Alice Johnson",
        "role": "Architect",
        "skills": ["OpenShift", "Keycloak", "ADR"],
        "capacity": "40h/week"
      },
      {
        "name": "Bob Smith", 
        "role": "Developer",
        "skills": ["ServiceNow", "JavaScript", "Integration"],
        "capacity": "35h/week"
      }
    ],
    "importFromAdrs": true,
    "importFromTodos": true
  }
}

Result: Creates a structured project plan with phases automatically linked to existing ADRs and TODO tasks.

2. Track Project Progress

{
  "tool": "mcp_planning",
  "arguments": {
    "operation": "track_progress",
    "projectPath": "/path/to/your/project",
    "reportType": "summary",
    "updateTaskProgress": true,
    "includeVisuals": true
  }
}

Result: Generates a visual progress report with completion percentages and status indicators.

Example output:

# Project Progress Summary

## ServiceNow OpenShift Integration

### Overall Status
- **Progress**: 67% [█████████████▒░░░░░░]
- **Status**: active
- **Total Phases**: 3
- **Completed**: 1
- **Active**: 1
- **Blocked**: 0

### Current Focus
Currently working on 1 phase(s):
- Phase 2: ServiceNow Integration

3. Perform Risk Analysis

{
  "tool": "mcp_planning",
  "arguments": {
    "operation": "risk_analysis",
    "projectPath": "/path/to/your/project",
    "analysisType": "comprehensive",
    "includeAdrRisks": true,
    "includeDependencyRisks": true,
    "includeResourceRisks": true,
    "generateMitigation": true
  }
}

Result: Identifies potential risks and provides mitigation strategies.

Example output:

# Risk Analysis Report

### Overall Risk Assessment
- **Risk Level**: MEDIUM
- **Risk Score**: 8
- **Total Risks**: 3

### Identified Risks

#### Risk 1: Dependencies
- **Description**: Phase "ServiceNow Integration" has multiple dependencies (2) - high coordination risk
- **Impact**: high
- **Probability**: medium
- **Mitigation**: Review and simplify dependencies, create detailed coordination plan

4. Manage Project Phases

{
  "tool": "mcp_planning",
  "arguments": {
    "operation": "manage_phases",
    "projectPath": "/path/to/your/project",
    "action": "transition",
    "phaseId": "phase-id-from-list",
    "targetStatus": "active"
  }
}

Result: Transitions a phase status and updates completion tracking.

5. Generate Executive Report

{
  "tool": "mcp_planning", 
  "arguments": {
    "operation": "generate_reports",
    "projectPath": "/path/to/your/project",
    "reportType": "executive",
    "format": "markdown",
    "includeCharts": true,
    "timeframe": "month"
  }
}

Result: Creates comprehensive executive summary with key metrics and status.

Integration with Existing Tools

ADR Integration

• Automatically imports and links ADRs to relevant project phases
• Analyzes ADR complexity for risk assessment
• Updates project phases when new ADRs are created

TODO System Integration

• Syncs task completion with phase progress
• Imports existing tasks into appropriate phases
• Updates project metrics based on task status

Development Guidance Integration

• Converts development roadmaps into tracked project phases
• Links implementation tasks to architectural decisions
• Provides phase-specific development guidance

Key Benefits Delivered

1. Addresses Original Gaps:

   • ✅ Development guidance integration with TODO management
   • ✅ Phase-based planning with native management
   • ✅ Enhanced dependency tracking and visualization
   • ✅ Visual progress tracking with Gantt-style views
   • ✅ Team coordination with capacity planning

2. Seamless Integration:

   • Works with existing ADR analysis tools
   • Integrates with TODO management system
   • Connects to development guidance workflows
   • Updates project health scoring

3. Comprehensive Features:

   • Phase lifecycle management
   • Risk analysis with mitigation strategies
   • Team resource allocation
   • Executive reporting and dashboards
   • Visual progress indicators

Example Workflow

1. Start: Use create_project to initialize project structure
2. Plan: Use manage_phases to refine phase details and dependencies
3. Allocate: Use manage_resources to assign team members to phases
4. Execute: Work progresses, syncing with TODO system automatically
5. Monitor: Use track_progress for regular status updates
6. Assess: Use risk_analysis to identify and mitigate issues
7. Report: Use generate_reports for stakeholder communication

This tool successfully bridges the gap between architectural decisions and implementation workflows, providing the comprehensive project planning capabilities identified as missing in the original issue.