yoda-mcp/docs/guides/getting-started.md

Intelligent Planning MCP with Optional Dependencies and Graceful Fallbacks - wise planning through the Force of lean excellence

# Getting Started with Planner MCP

## Welcome to Planner MCP

Planner MCP is an enterprise-grade planning platform that orchestrates multiple Model Context Protocol (MCP) servers to deliver world-class implementation plans. This guide will help you get up and running quickly.

## What is Planner MCP?

Planner MCP combines the power of multiple specialized AI services to create comprehensive, high-quality implementation plans:

- **🧠 Intelligent Orchestration**: Coordinates multiple MCP servers for optimal results
- **✅ Quality Assurance**: 5-tier quality certification ensures exceptional output
- **🔒 Enterprise Security**: OAuth2/JWT with MFA, RBAC, and comprehensive audit logging
- **📈 Auto-scaling**: Handles enterprise workloads with graceful degradation
- **🔍 Real-time Monitoring**: Comprehensive dashboards and intelligent alerting

## Quick Start

### Prerequisites

- **Node.js**: Version 18.0 or higher
- **npm**: Version 8.0 or higher
- **Docker**: For containerized deployment (optional)
- **Access Credentials**: Valid user account with appropriate permissions

### Installation

#### Option 1: npm Installation (Recommended)
```bash
# Install Planner MCP client
npm install -g planner-mcp-client

# Verify installation
planner-mcp --version
```

#### Option 2: Docker Installation
```bash
# Pull the official image
docker pull planner-mcp:latest

# Run with environment variables
docker run -d \
  --name planner-mcp \
  -p 3000:3000 \
  -e PLANNER_API_URL=https://api.planner-mcp.example.com \
  -e PLANNER_API_KEY=your_api_key \
  planner-mcp:latest
```

#### Option 3: Source Installation
```bash
# Clone the repository
git clone https://github.com/company/planner-mcp.git
cd planner-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the development server
npm run dev
```

### Authentication Setup

1. **Get API Credentials**
   - Visit the [Planner MCP Dashboard](https://dashboard.planner-mcp.example.com)
   - Create an account or sign in
   - Navigate to API Settings
   - Generate your API key

2. **Configure Authentication**
   ```bash
   # Set your API key
   export PLANNER_MCP_API_KEY=your_api_key_here
   
   # Or use configuration file
   planner-mcp config set api-key your_api_key_here
   planner-mcp config set endpoint https://api.planner-mcp.example.com
   ```

3. **Test Authentication**
   ```bash
   # Verify your credentials
   planner-mcp auth test
   
   # Expected output:
   # ✅ Authentication successful
   # User: your@email.com
   # Role: planner
   # Tier: professional
   ```

## Your First Planning Request

### Basic Planning Request

Create a simple planning request to get familiar with the system:

```bash
# Create a basic plan
planner-mcp create plan \
  --title "Build a Todo App" \
  --requirements "Create a simple todo application with user authentication" \
  --complexity moderate \
  --deadline "2024-02-15"
```

### Interactive Planning

Use the interactive mode for guided plan creation:

```bash
# Start interactive planning session
planner-mcp create --interactive

# Follow the prompts:
# ? What's your project title? Build a Todo App
# ? Describe your requirements: Create a simple todo application...
# ? What's the complexity level? (moderate)
# ? When do you need this completed? 2024-02-15
# ? Any specific technology preferences? React, Node.js
# ? Additional constraints or preferences? Mobile-friendly design
```

### Programmatic Usage (Node.js)

```javascript
const { PlannerMCPClient } = require('planner-mcp-client');

// Initialize client
const planner = new PlannerMCPClient({
  apiKey: process.env.PLANNER_MCP_API_KEY,
  endpoint: 'https://api.planner-mcp.example.com'
});

// Create a planning request
async function createPlan() {
  try {
    const request = {
      title: 'Build a Todo App',
      requirements: [
        'Create a simple todo application',
        'Implement user authentication',
        'Support mobile and desktop',
        'Include task categories and priorities'
      ],
      complexity: 'moderate',
      targetQuality: 'professional',
      deadline: new Date('2024-02-15'),
      context: {
        technologies: ['React', 'Node.js', 'PostgreSQL'],
        constraints: ['Budget: $10k', 'Team size: 3 developers'],
        preferences: ['Modern UI', 'Cloud deployment']
      }
    };

    const plan = await planner.createPlan(request);
    
    console.log('Plan created successfully!');
    console.log('Plan ID:', plan.id);
    console.log('Quality Score:', plan.qualityScore);
    console.log('Estimated Duration:', plan.estimatedDuration);
    
    return plan;
  } catch (error) {
    console.error('Failed to create plan:', error.message);
  }
}

createPlan();
```

## Understanding Your Plan

### Plan Structure

A typical Planner MCP plan includes:

```json
{
  "id": "plan_abc123",
  "title": "Build a Todo App",
  "qualityScore": 92,
  "qualityTier": "ENTERPRISE",
  "status": "completed",
  "architecture": {
    "overview": "Modern full-stack application architecture...",
    "components": ["Frontend (React)", "Backend API (Node.js)", "Database (PostgreSQL)"],
    "patterns": ["RESTful API", "JWT Authentication", "Responsive Design"]
  },
  "implementation": {
    "phases": [
      {
        "name": "Setup & Architecture",
        "duration": "1 week",
        "tasks": ["Project scaffolding", "Database design", "API specification"]
      },
      {
        "name": "Core Development",
        "duration": "3 weeks",
        "tasks": ["Authentication system", "CRUD operations", "UI components"]
      },
      {
        "name": "Testing & Deployment",
        "duration": "1 week",
        "tasks": ["Unit tests", "Integration tests", "Production deployment"]
      }
    ],
    "timeline": "5 weeks total",
    "resources": ["3 developers", "1 designer", "DevOps support"]
  },
  "qualityAssurance": {
    "testingStrategy": "Comprehensive testing with 90% coverage",
    "securityMeasures": "OWASP compliance, input validation",
    "performanceTargets": "< 2s page load, 99.9% uptime"
  },
  "recommendations": [
    "Consider implementing progressive web app features",
    "Use TypeScript for better code maintainability",
    "Implement proper error handling and user feedback"
  ]
}
```

### Quality Tiers Explained

- **🏆 WORLD_CLASS (81-100)**: Exceptional quality with innovative solutions, comprehensive coverage, and industry-leading practices
- **🏢 ENTERPRISE (61-80)**: Excellent quality suitable for large organizations with scalability and security focus
- **💼 PROFESSIONAL (41-60)**: High-quality plans with complete implementation details and testing strategies
- **📋 STANDARD (21-40)**: Good quality plans meeting basic requirements with solid implementation approach
- **📝 BASIC (0-20)**: Minimal quality plans requiring significant enhancement

### Reading Your Plan

1. **Executive Summary**: High-level overview and key recommendations
2. **Architecture Section**: Technical approach and system design
3. **Implementation Plan**: Detailed steps, timeline, and resources
4. **Quality Assurance**: Testing, security, and performance considerations
5. **Risk Assessment**: Potential challenges and mitigation strategies
6. **Enhancement Suggestions**: Recommendations for improvement

## Working with Plans

### Viewing Your Plans

```bash
# List all your plans
planner-mcp plans list

# View a specific plan
planner-mcp plans show plan_abc123

# Export plan to different formats
planner-mcp plans export plan_abc123 --format pdf
planner-mcp plans export plan_abc123 --format markdown
planner-mcp plans export plan_abc123 --format json
```

### Plan Management

```bash
# Update plan requirements
planner-mcp plans update plan_abc123 \
  --add-requirement "Add email notifications"

# Request plan enhancement
planner-mcp plans enhance plan_abc123 \
  --focus security \
  --target-quality enterprise

# Share plan with team members
planner-mcp plans share plan_abc123 \
  --email teammate@company.com \
  --permission read
```

### Tracking Progress

```bash
# Mark tasks as completed
planner-mcp plans progress plan_abc123 \
  --complete-task "Project scaffolding"

# Update overall progress
planner-mcp plans progress plan_abc123 \
  --percentage 45

# View progress dashboard
planner-mcp dashboard open
```

## Advanced Features

### Custom Quality Requirements

Specify custom quality criteria for specialized needs:

```javascript
const customPlan = await planner.createPlan({
  title: 'Enterprise Security Audit System',
  requirements: ['...'],
  qualityRequirements: {
    security: {
      minimum: 95,
      standards: ['SOC2', 'ISO27001'],
      requirements: ['Zero trust architecture', 'End-to-end encryption']
    },
    performance: {
      responseTime: '< 500ms',
      throughput: '> 10000 req/min',
      availability: '99.99%'
    },
    compliance: {
      frameworks: ['PCI DSS', 'HIPAA'],
      auditReadiness: true
    }
  }
});
```

### Batch Planning

Process multiple planning requests efficiently:

```javascript
const batchRequest = {
  requests: [
    { title: 'Mobile App', requirements: ['...'], complexity: 'high' },
    { title: 'API Gateway', requirements: ['...'], complexity: 'moderate' },
    { title: 'Analytics Dashboard', requirements: ['...'], complexity: 'low' }
  ],
  parallel: true,
  qualityTier: 'enterprise'
};

const batchResults = await planner.createBatchPlans(batchRequest);
```

### Webhooks and Notifications

Set up webhooks to receive plan updates:

```javascript
// Configure webhook for plan completion
await planner.webhooks.create({
  url: 'https://your-app.com/webhooks/planner',
  events: ['plan.completed', 'plan.quality_updated'],
  secret: 'your_webhook_secret'
});

// Handle webhook in your application
app.post('/webhooks/planner', (req, res) => {
  const { event, data } = req.body;
  
  switch (event) {
    case 'plan.completed':
      console.log(`Plan ${data.planId} completed with quality ${data.qualityScore}`);
      break;
    case 'plan.quality_updated':
      console.log(`Plan ${data.planId} quality improved to ${data.newQualityScore}`);
      break;
  }
  
  res.status(200).send('OK');
});
```

## Best Practices

### 1. Writing Effective Requirements

**Good Requirements:**
```
Requirements:
- Create a todo application with user authentication
- Support adding, editing, deleting, and categorizing tasks
- Implement priority levels (high, medium, low)
- Provide mobile-responsive design
- Include search and filtering capabilities
- Support team collaboration with shared lists
- Implement email notifications for due tasks
```

**Avoid Vague Requirements:**
```
❌ "Build a good app"
❌ "Make it user-friendly"
❌ "Add some features"
```

### 2. Choosing the Right Complexity Level

- **Simple**: Basic CRUD applications, simple websites
- **Moderate**: Multi-user applications, API integrations
- **Complex**: Enterprise systems, real-time features
- **Enterprise**: Large-scale systems, advanced security
- **World-Class**: Industry-leading solutions, innovation required

### 3. Setting Realistic Deadlines

Consider these factors:
- Project complexity and scope
- Team size and experience
- Available resources and budget
- Quality requirements
- External dependencies

### 4. Leveraging Context Information

Provide relevant context to improve plan quality:
```javascript
context: {
  existingSystem: "Legacy PHP application with MySQL database",
  teamExperience: ["React", "Node.js", "AWS"],
  constraints: ["Must maintain existing user data", "Budget: $50k"],
  preferences: ["Microservices architecture", "Cloud-native deployment"],
  complianceRequirements: ["GDPR", "SOC2"],
  performanceTargets: ["< 2s page load", "Support 10k users"]
}
```

## Troubleshooting

### Common Issues

#### Authentication Problems
```bash
# Check your credentials
planner-mcp auth status

# Refresh your token
planner-mcp auth refresh

# Reset authentication
planner-mcp auth reset
```

#### Plan Creation Fails
```bash
# Check service status
planner-mcp status

# Validate your request
planner-mcp validate --file plan-request.json

# View detailed error logs
planner-mcp logs --level error --last 24h
```

#### Quality Score Lower Than Expected

1. **Review Requirements**: Ensure all requirements are clearly specified
2. **Add Context**: Provide more detailed context and constraints
3. **Increase Complexity**: Consider if the complexity level is appropriate
4. **Request Enhancement**: Use the enhancement feature to improve quality

#### Performance Issues

```bash
# Check system performance
planner-mcp performance check

# View performance metrics
planner-mcp metrics --component orchestrator

# Report performance issues
planner-mcp support create-ticket --type performance
```

### Getting Help

#### Documentation
- [API Reference](../api/README.md)
- [Architecture Overview](../architecture/system-overview.md)
- [Troubleshooting Guide](./troubleshooting.md)
- [FAQ](./faq.md)

#### Support Channels
- **Email**: support@planner-mcp.example.com
- **Slack**: #planner-support
- **GitHub Issues**: [github.com/company/planner-mcp/issues](https://github.com/company/planner-mcp/issues)
- **Community Forum**: [community.planner-mcp.example.com](https://community.planner-mcp.example.com)

#### Emergency Support
For critical production issues:
- **Phone**: +1-800-PLANNER (24/7)
- **Emergency Email**: emergency@planner-mcp.example.com
- **Status Page**: [status.planner-mcp.example.com](https://status.planner-mcp.example.com)

## Next Steps

Now that you're up and running with Planner MCP:

1. **Explore Advanced Features**: Try batch planning, webhooks, and custom quality requirements
2. **Integrate with Your Workflow**: Set up CI/CD integration and team collaboration
3. **Monitor and Optimize**: Use dashboards to track plan quality and system performance
4. **Join the Community**: Connect with other users and share best practices
5. **Stay Updated**: Subscribe to our newsletter for feature updates and tips

## Examples and Tutorials

- [Building a Web Application](./examples/web-application.md)
- [Microservices Architecture Planning](./examples/microservices.md)
- [Mobile App Development](./examples/mobile-app.md)
- [DevOps and Infrastructure](./examples/devops.md)
- [Team Collaboration Workflows](./examples/team-collaboration.md)

---

**Need Help?** Don't hesitate to reach out to our support team. We're here to help you succeed with Planner MCP!

**Last Updated**: {current_date}  
**Version**: 2.0  
**Feedback**: [feedback@planner-mcp.example.com](mailto:feedback@planner-mcp.example.com)