# API Reference - Task Manager MCP Servers

## Overview

This document provides detailed API reference for both Task Management and Task Assignment MCP servers.

## Task Management MCP Server

### Tools

#### `analyze_task_input`

Analyzes natural language task input and extracts structured information.

**Parameters:**
- `task_description` (string, required): Natural language description of the task
- `project_id` (string, optional): ID of the associated project
- `due_date` (string, optional): ISO format due date
- `priority_hint` (string, optional): Priority hint for the task

**Returns:** `TaskAnalysisResult`
```json
{
  "tasks": [
    {
      "id": "task_1",
      "name": "Task Name",
      "description": "Detailed description",
      "priority": 2,
      "time_cost": 4.0,
      "importance": 4,
      "benefit": 8,
      "marginal_cost": 2
    }
  ],
  "total_estimated_time": 4.0,
  "priority_distribution": {"high": 1},
  "risk_summary": "Analysis summary"
}
```

#### `get_schedule_recommendation`

Generates intelligent scheduling recommendations for tasks.

**Parameters:**
- `project_id` (string, optional): Filter tasks by project
- `available_hours_per_day` (float, default: 8.0): Available working hours per day
- `start_date` (string, optional): ISO format start date

**Returns:** `ScheduleRecommendation`
```json
{
  "recommended_order": ["task_1", "task_2"],
  "estimated_completion_date": "2024-02-15T17:00:00",
  "critical_path": ["task_1"],
  "parallel_opportunities": [["task_3", "task_4"]]
}
```

#### `predict_task_risks`

Predicts potential risks for a specific task and suggests mitigation strategies.

**Parameters:**
- `task_id` (string, required): ID of the task to analyze
- `include_mitigation` (bool, default: true): Whether to include mitigation strategies

**Returns:** `RiskAssessment`
```json
{
  "task_id": "task_1",
  "risk_level": 3,
  "risk_factors": ["Large time estimate", "Dependencies"],
  "mitigation_strategies": ["Break into subtasks", "Reduce dependencies"],
  "probability": 0.6,
  "impact": 4
}
```

#### `create_reminder`

Creates a reminder for a task.

**Parameters:**
- `task_id` (string, required): ID of the task
- `reminder_type` (string, required): Type of reminder ("start", "deadline", "progress")
- `scheduled_time` (string, optional): ISO format scheduled time
- `message` (string, optional): Custom reminder message

**Returns:** `Reminder`
```json
{
  "id": "reminder_1",
  "task_id": "task_1",
  "reminder_type": "deadline",
  "message": "Deadline approaching for: Task Name",
  "scheduled_time": "2024-02-14T09:00:00",
  "sent": false
}
```

#### `update_task_progress`

Updates task progress and dynamically adjusts estimates.

**Parameters:**
- `task_id` (string, required): ID of the task
- `progress` (float, required): Progress percentage (0.0-1.0)
- `time_spent` (float, default: 0.0): Time spent since last update
- `notes` (string, default: ""): Progress notes
- `updated_by` (string, default: "user"): Who updated the progress

**Returns:** `ProgressUpdate`
```json
{
  "task_id": "task_1",
  "progress": 0.5,
  "time_spent": 2.0,
  "notes": "Halfway complete",
  "updated_by": "user",
  "timestamp": "2024-02-10T14:30:00"
}
```

#### `get_next_task_recommendation`

Gets intelligent recommendation for the next task to work on.

**Parameters:**
- `available_time` (float, default: 2.0): Available time in hours
- `current_context` (string, default: ""): Current work context
- `exclude_task_ids` (list, optional): Task IDs to exclude

**Returns:** `TaskRecommendation`
```json
{
  "task_id": "task_1",
  "score": 85.5,
  "reasoning": "High priority task that fits available time",
  "context": {
    "available_time": 2.0,
    "task_time_cost": 1.5
  }
}
```

### Resources

#### `task://{task_id}`

Get detailed information about a specific task.

**Example:** `task://task_1`

Returns formatted task details including status, progress, dependencies, and metadata.

#### `project://{project_id}/summary`

Get comprehensive summary of a project and its tasks.

**Example:** `project://proj_1/summary`

Returns project overview with task statistics, progress tracking, and upcoming deadlines.

### Prompts

#### `task_review_prompt`

Generates a prompt for reviewing and analyzing a completed task.

**Parameters:**
- `task_id` (string, required): ID of the completed task

#### `risk_mitigation_prompt`

Generates a prompt for developing risk mitigation strategies.

**Parameters:**
- `task_id` (string, required): ID of the task to analyze

## Task Assignment MCP Server

### Tools

#### `decompose_complex_task`

Decomposes a complex task into manageable subtasks.

**Parameters:**
- `task_id` (string, required): ID of the task to decompose
- `max_subtasks` (int, default: 5): Maximum number of subtasks
- `target_time_per_subtask` (float, default: 4.0): Target time per subtask in hours

**Returns:** `TaskDecompositionResult`
```json
{
  "parent_task_id": "task_1",
  "subtasks": [
    {
      "id": "task_1_sub_1",
      "name": "Subtask 1",
      "description": "First part of the task",
      "time_cost": 4.0
    }
  ],
  "decomposition_reasoning": "AI-powered decomposition based on complexity",
  "estimated_total_time": 12.0
}
```

#### `recommend_task_assignment`

Recommends the best resource to assign a task to.

**Parameters:**
- `task_id` (string, required): ID of the task to assign
- `consider_workload` (bool, default: true): Whether to consider current workload
- `prefer_human` (bool, default: false): Whether to prefer human resources

**Returns:** `AssignmentRecommendation`
```json
{
  "task_id": "task_1",
  "recommended_resource_id": "human_001",
  "resource_type": "human",
  "confidence_score": 0.85,
  "reasoning": "Best skill match with good availability",
  "estimated_completion_time": 3.5,
  "skill_match_score": 0.9,
  "availability_score": 0.8
}
```

#### `assign_task_to_resource`

Assigns a task to a specific resource.

**Parameters:**
- `task_id` (string, required): ID of the task
- `resource_id` (string, required): ID of the resource
- `start_date` (string, optional): ISO format start date
- `notes` (string, default: ""): Assignment notes

**Returns:** Assignment result object
```json
{
  "task_id": "task_1",
  "resource_id": "human_001",
  "resource_name": "Alice Johnson",
  "assignment_date": "2024-02-10T10:00:00",
  "estimated_completion": "2024-02-12T14:00:00",
  "notes": "Assigned based on skill match",
  "status": "assigned"
}
```

#### `create_collaboration_plan`

Creates a collaboration plan for complex tasks requiring multiple resources.

**Parameters:**
- `task_id` (string, required): ID of the task
- `required_skills` (list, optional): List of required skills
- `max_team_size` (int, default: 4): Maximum team size

**Returns:** `TeamCollaborationPlan`
```json
{
  "task_id": "task_1",
  "collaboration_type": "parallel_development",
  "team_members": ["human_001", "human_002"],
  "coordination_strategy": "Divide into parallel workstreams",
  "communication_plan": "Daily standup meetings",
  "milestone_schedule": [
    {
      "milestone": "Milestone 1",
      "date": "2024-02-12T17:00:00",
      "deliverable": "Progress checkpoint 1",
      "responsible": "human_001"
    }
  ]
}
```

#### `review_daily_report`

Reviews and scores a team member's daily report.

**Parameters:**
- `team_member_id` (string, required): ID of the team member
- `report_content` (string, required): Content of the daily report
- `report_date` (string, optional): ISO format report date

**Returns:** `DailyReportReview`
```json
{
  "report_date": "2024-02-10T00:00:00",
  "team_member_id": "human_001",
  "productivity_score": 8.5,
  "quality_score": 9.0,
  "collaboration_score": 7.5,
  "overall_score": 8.3,
  "feedback": "Excellent work with strong attention to quality",
  "improvement_areas": ["Increase team interaction"],
  "achievements": ["High productivity", "Strong quality focus"]
}
```

### Resources

#### `resource://{resource_id}`

Get detailed information about a specific resource (human or agent).

**Example:** `resource://human_001`

Returns resource details including skills, availability, cost, and current assignments.

#### `team://{project_id}/workload`

Get team workload summary for a project.

**Example:** `team://proj_1/workload`

Returns workload distribution across team members and unassigned tasks.

### Prompts

#### `assignment_optimization_prompt`

Generates a prompt for optimizing task assignments across a project.

**Parameters:**
- `project_id` (string, required): ID of the project to analyze

#### `team_performance_analysis_prompt`

Generates a prompt for analyzing team performance trends.

**Parameters:**
- `team_member_ids` (list, required): List of team member IDs to analyze

## Error Handling

All tools return appropriate error messages for:
- Invalid parameters
- Missing resources
- Non-existent tasks/projects
- API failures (when AI features are used)

## Rate Limits

When using AI features (with OpenAI API):
- Respect OpenAI's rate limits
- Implement exponential backoff for retries
- Fallback to rule-based implementations when API is unavailable