task-engine-ai-core/docs/mcp-tool-usage-patterns.md

Revolutionary AI-driven task management system with complete transformation trilogy: Frontend v0.1.0, Backend v0.2.0, CLI v0.3.0 - Enterprise-grade performance with 95% improvements

# MCP Tool Usage Patterns

This guide covers advanced usage patterns for Task Engine AI MCP tools, including dual-mode task creation and agentic workflows.

## 🎯 Overview

Task Engine AI provides comprehensive MCP (Model Control Protocol) integration with tools designed for both human users and AI agents. The tools support multiple operation modes to accommodate different workflows and requirements.

## 🛠️ Core Tool Categories

### 1. Task Management Tools

#### `add_task` - Dual Mode Task Creation

The `add_task` tool supports two distinct operation modes:

##### 🤖 AI-Powered Mode
Uses external AI services to generate task details from a natural language prompt.

**Parameters:**
```json
{
  "projectRoot": "/path/to/project",
  "prompt": "Create a task for implementing user authentication",
  "research": false,
  "priority": "medium"
}
```

**Use Cases:**
- Quick task creation from natural language
- Leveraging AI for task detail generation
- Research-backed task creation with external knowledge

**Requirements:**
- Valid API keys for AI services (Anthropic, OpenAI, etc.)
- Internet connectivity
- Configured model settings

##### 🧠 Manual/Agentic Mode
Bypasses AI generation and uses provided task details directly.

**Parameters:**
```json
{
  "projectRoot": "/path/to/project",
  "title": "Implement user authentication",
  "description": "Add secure login/logout functionality with session management",
  "details": "Implementation steps:\n1. Set up authentication middleware\n2. Create login/logout endpoints\n3. Implement session management\n4. Add password hashing\n5. Create user registration flow",
  "testStrategy": "Unit tests for auth functions, integration tests for endpoints, security testing for vulnerabilities",
  "priority": "high",
  "dependencies": "1,2,3"
}
```

**Benefits:**
- ✅ **No External Dependencies**: Works without API keys or internet
- ✅ **Immediate Response**: No waiting for AI processing
- ✅ **Full Control**: Precise task specification
- ✅ **Reliable**: No AI service failures or rate limits
- ✅ **Cost-Free**: No API usage costs
- ✅ **Perfect for Agentic Workflows**: Ideal for AI agents creating tasks

**Use Cases:**
- Agentic task creation workflows
- Offline development environments
- Precise task specification requirements
- Cost-conscious development
- High-reliability scenarios

#### Other Task Management Tools

##### `get_tasks` - Task Retrieval
```json
{
  "projectRoot": "/path/to/project",
  "status": "pending",
  "withSubtasks": true
}
```

##### `set_task_status` - Status Updates
```json
{
  "projectRoot": "/path/to/project",
  "id": "15",
  "status": "done"
}
```

##### `next_task` - Workflow Management
```json
{
  "projectRoot": "/path/to/project"
}
```

### 2. IDE Integration Tools

#### `detect_ide` - IDE Discovery
```json
{
  "forceRefresh": true
}
```

#### `connect_ide` - IDE Connection
```json
{
  "ideType": "auto-detect",
  "timeout": 10000
}
```

#### `ide_generate_text` - IDE-Powered Generation
```json
{
  "messages": [
    {"role": "user", "content": "Write a Python function for fibonacci"}
  ],
  "maxTokens": 500,
  "temperature": 0.7
}
```

## 🔄 Workflow Patterns

### Pattern 1: Agentic Task Creation Workflow

```mermaid
graph TD
    A[AI Agent] --> B[Analyze Requirements]
    B --> C[Create Task with Manual Mode]
    C --> D[Set Dependencies]
    D --> E[Update Status]
    E --> F[Generate Subtasks]
```

**Implementation:**
1. Agent analyzes project requirements
2. Creates tasks using manual mode for precision
3. Sets up task dependencies and priorities
4. Updates task status as work progresses
5. Expands complex tasks into subtasks

### Pattern 2: Hybrid Human-AI Workflow

```mermaid
graph TD
    A[Human Input] --> B[AI-Powered Task Creation]
    B --> C[Manual Refinement]
    C --> D[Task Execution]
    D --> E[Status Updates]
```

**Implementation:**
1. Human provides natural language requirements
2. AI generates initial task structure
3. Manual refinement for precision
4. Execute tasks with status tracking

### Pattern 3: IDE-Integrated Development

```mermaid
graph TD
    A[Detect IDE] --> B[Connect to IDE]
    B --> C[Generate Code via IDE]
    C --> D[Update Task Progress]
    D --> E[Create Follow-up Tasks]
```

**Implementation:**
1. Detect available IDEs and capabilities
2. Connect to best available IDE
3. Use IDE's AI for code generation
4. Track progress in task system
5. Create follow-up tasks as needed

## 🎯 Best Practices

### For Agentic Workflows
- **Use Manual Mode**: Provides immediate, reliable task creation
- **Structure Dependencies**: Set up clear task relationships
- **Batch Operations**: Create multiple related tasks efficiently
- **Status Tracking**: Maintain accurate progress information

### For Human Workflows
- **Start with AI Mode**: Leverage AI for initial task generation
- **Refine Manually**: Use manual mode for precision adjustments
- **Use IDE Integration**: Connect to your IDE for seamless development
- **Monitor Progress**: Regular status updates and next task queries

### For Mixed Workflows
- **Combine Modes**: Use AI for creativity, manual for precision
- **Leverage IDE**: Use real IDE connections when available
- **Fallback Gracefully**: Handle API failures with manual alternatives
- **Document Decisions**: Track why specific approaches were chosen

## 🔧 Configuration Tips

### Environment Setup
- Configure multiple API keys for redundancy
- Set up IDE integration for enhanced capabilities
- Use absolute paths in MCP configurations
- Test both online and offline scenarios

### Performance Optimization
- Use manual mode for batch operations
- Cache IDE detection results
- Minimize external API calls when possible
- Leverage local IDE capabilities

## 🚀 Advanced Usage

### Custom Tool Combinations
Combine multiple tools for complex workflows:

```javascript
// 1. Get current project status
const tasks = await get_tasks({projectRoot, status: "pending"});

// 2. Create new task based on analysis
const newTask = await add_task({
  projectRoot,
  title: "Optimize performance",
  description: "Based on current task analysis...",
  // ... manual mode parameters
});

// 3. Update dependencies
await add_dependency({
  projectRoot,
  id: newTask.id,
  dependsOn: "15,16"
});
```

### Error Handling
Implement robust error handling for different scenarios:

```javascript
try {
  // Try AI-powered mode first
  const task = await add_task({projectRoot, prompt});
} catch (error) {
  // Fallback to manual mode
  const task = await add_task({
    projectRoot,
    title: extractedTitle,
    description: extractedDescription,
    // ... manual parameters
  });
}
```

This comprehensive approach ensures reliable task management regardless of external service availability or network conditions.