task-manager-mcp-wrapper/docs/USER_GUIDE.md

Complete task management and assignment MCP servers with 16 AI-powered tools for intelligent task planning, scheduling, risk prediction, team collaboration, and automated workflow management

# User Guide - Task Manager MCP Servers

## Getting Started

### Prerequisites

- Python 3.9 or higher
- OpenAI API key (for AI features)
- Claude Desktop (for MCP integration)

### Installation

1. **Install the package:**
   ```bash
   pip install task-manager-mcp
   ```

2. **Set up environment variables:**
   ```bash
   export OPENAI_API_KEY="your-openai-api-key"
   export OPENAI_BASE_URL="https://api.openai.com/v1"  # Optional
   ```

3. **Configure Claude Desktop:**
   
   Edit your Claude Desktop configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "task-management": {
         "command": "python",
         "args": ["-m", "task_management_mcp.server"],
         "env": {
           "OPENAI_API_KEY": "your-openai-api-key"
         }
       },
       "task-assignment": {
         "command": "python",
         "args": ["-m", "task_assignment_mcp.server"],
         "env": {
           "OPENAI_API_KEY": "your-openai-api-key"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop** to load the MCP servers.

## Basic Usage

### Task Management Workflows

#### 1. Creating and Analyzing Tasks

Start by describing your task in natural language:

```
"I need to build a user authentication system for my web app. It should include login, registration, password reset, and email verification features. The deadline is in 2 weeks."
```

The system will:
- Extract structured task information
- Estimate time and complexity
- Assign priority levels
- Identify potential risks

#### 2. Getting Schedule Recommendations

Ask for scheduling help:

```
"Can you recommend the best order to work on these tasks? I have 6 hours available per day."
```

You'll get:
- Optimal task ordering
- Estimated completion dates
- Critical path analysis
- Parallel execution opportunities

#### 3. Risk Assessment and Mitigation

For any task, you can ask:

```
"What are the potential risks for the authentication system task, and how can I mitigate them?"
```

The system provides:
- Risk level assessment (1-5 scale)
- Specific risk factors
- Actionable mitigation strategies
- Early warning indicators

#### 4. Progress Tracking

Update progress as you work:

```
"I've completed 30% of the authentication task and spent 3 hours on it. The login functionality is working."
```

The system will:
- Update task progress
- Adjust time estimates
- Recalculate schedules
- Suggest next steps

#### 5. Smart Task Recommendations

When you're ready for the next task:

```
"I have 2 hours available. What should I work on next?"
```

Get personalized recommendations based on:
- Available time
- Task priorities
- Dependencies
- Your current context

### Task Assignment Workflows

#### 1. Task Decomposition

For complex tasks, ask for breakdown:

```
"This e-commerce platform task seems too big. Can you break it down into smaller, manageable pieces?"
```

The system will:
- Analyze task complexity
- Create logical subtasks
- Estimate time for each piece
- Maintain dependencies

#### 2. Resource Matching and Assignment

When you have team members:

```
"I have a React component task. Who should I assign it to based on skills and availability?"
```

Get recommendations considering:
- Skill matching
- Current workload
- Cost efficiency
- Past performance

#### 3. Team Collaboration Planning

For multi-person tasks:

```
"This full-stack feature needs both frontend and backend work. How should the team collaborate?"
```

Receive detailed plans including:
- Team composition
- Coordination strategy
- Communication plan
- Milestone schedule

#### 4. Daily Report Review

Team members can submit daily reports:

```
"Today I completed the user profile API, wrote comprehensive tests, and helped review the frontend integration. I also optimized the database queries for better performance."
```

Get automated feedback with:
- Performance scoring (productivity, quality, collaboration)
- Specific achievements recognition
- Areas for improvement
- Constructive suggestions

## Advanced Features

### Custom Resource Management

Define your team members and AI agents:

```json
{
  "human_resources": [
    {
      "id": "dev_001",
      "name": "Sarah Chen",
      "skills": ["react", "typescript", "ui_design"],
      "cost_per_hour": 85.0,
      "availability": "full_time"
    }
  ],
  "ai_agents": [
    {
      "id": "code_agent",
      "name": "Code Generation Agent",
      "skills": ["code_generation", "testing", "documentation"],
      "cost_per_task": 0.5
    }
  ]
}
```

### Project-Level Management

Organize tasks by projects:

```
"Create a new project called 'Mobile App' and analyze these requirements: [requirements document]"
```

Track progress across entire projects:

```
"Show me the overall status of the Mobile App project"
```

### Integration with Development Tools

The MCP servers can integrate with:
- **Git repositories**: Track commits and relate to tasks
- **Issue trackers**: Sync with GitHub Issues, Jira
- **Time tracking**: Export time logs
- **Calendar apps**: Schedule task work

## Best Practices

### Task Description Guidelines

**Good task descriptions:**
- Be specific about deliverables
- Include acceptance criteria
- Mention technical constraints
- Specify deadlines if known

**Example:**
```
"Implement user authentication API with JWT tokens. Must include login, logout, token refresh, and password reset endpoints. Use FastAPI and PostgreSQL. Should handle rate limiting and include comprehensive tests. Deadline: March 15th."
```

### Effective Progress Updates

**Include in progress updates:**
- Specific accomplishments
- Time spent
- Challenges encountered
- Next steps planned

**Example:**
```
"Completed login and logout endpoints (40% progress, 3 hours spent). Encountered issue with JWT token expiration handling - researching best practices. Next: implement token refresh endpoint."
```

### Team Collaboration Tips

1. **Regular Check-ins**: Use daily report reviews
2. **Clear Dependencies**: Identify task dependencies early
3. **Skill Development**: Track team member growth
4. **Workload Balance**: Monitor resource utilization

## Troubleshooting

### Common Issues

#### MCP Server Not Starting
- Check Python version (3.9+ required)
- Verify environment variables are set
- Check Claude Desktop configuration syntax

#### AI Features Not Working
- Verify OpenAI API key is valid
- Check API quota and billing
- Ensure network connectivity

#### Poor Task Recommendations
- Provide more detailed task descriptions
- Update resource skills and availability
- Review and adjust task priorities

### Getting Help

1. **Check logs**: Look for error messages in Claude Desktop
2. **Validate configuration**: Use the provided examples
3. **Test with demo script**: Run `python examples/demo.py`
4. **Community support**: GitHub Discussions and Issues

## Tips for Maximum Productivity

### Daily Workflow

1. **Morning Planning**: Get task recommendations for the day
2. **Regular Updates**: Update progress every few hours
3. **End-of-Day Review**: Reflect on completed tasks
4. **Weekly Planning**: Review project status and adjust priorities

### Team Management

1. **Skill Tracking**: Keep resource skills updated
2. **Performance Monitoring**: Review daily reports regularly
3. **Workload Balancing**: Monitor team capacity
4. **Continuous Improvement**: Use retrospective insights

### Project Success

1. **Clear Requirements**: Start with detailed task analysis
2. **Risk Management**: Address risks proactively
3. **Regular Reviews**: Track progress against schedules
4. **Adaptive Planning**: Adjust plans based on actual progress

## Next Steps

Once you're comfortable with basic usage:

1. **Explore Advanced Features**: Custom resources, project management
2. **Integrate with Tools**: Connect to your development workflow
3. **Customize Workflows**: Adapt to your team's processes
4. **Share Feedback**: Help improve the system with your insights

For detailed API reference, see [API_REFERENCE.md](API_REFERENCE.md).