taskflow-mcp-tools

Original source / Raw SKILL.md

---
name: taskflow-mcp-tools
description: |
  MCP (Model Context Protocol) tools for TaskFlow task management operations.
  Use when you need to perform task operations through standardized MCP tools.
allowed-tools: Read, Write, Edit, Grep
---

# TaskFlow MCP Tools Skill

Provides standardized Model Context Protocol (MCP) tools for TaskFlow task management operations. This skill enables AI agents to perform task operations through a standardized interface following MCP specifications.

## What This Skill Does

- **Standardized Task Operations**: Exposes task CRUD operations as MCP tools
- **Authentication Integration**: Ensures proper user authentication and isolation
- **Parameter Validation**: Validates tool parameters before execution
- **Error Handling**: Provides comprehensive error handling for tool operations
- **Response Formatting**: Returns structured responses for AI consumption
- **MCP Protocol Compliance**: Follows MCP specifications for tool definitions

## What This Skill Does NOT Do

- Replace the core TaskFlow application
- Handle direct database operations (uses existing API)
- Bypass security measures or validations
- Access tasks belonging to other users
- Manage frontend UI components

---

## Before Implementation

Gather context to ensure successful implementation:

| Source | Gather |
|--------|--------|
| **Codebase** | Existing task models, MCP server structure, authentication patterns |
| **Conversation** | User's specific task management needs, required MCP tools |
| **Skill References** | MCP protocol specifications, tool schemas, security requirements |
| **User Guidelines** | Project-specific MCP tool standards, team conventions |

Ensure all required context is gathered before implementing.

---

## Available MCP Tools

### Tool: add_task
**Purpose**: Create a new task for the authenticated user

**Parameters**:
- `user_id`: string (required) - The ID of the user
- `title`: string (required) - The title of the task (1-200 characters)
- `description`: string (optional) - The description of the task (max 1000 characters)

**Response**:
```json
{
  "success": true,
  "task_id": 123,
  "message": "Task 'Buy groceries' created successfully",
  "task": {
    "id": 123,
    "title": "Buy groceries",
    "description": "Milk, eggs, bread",
    "completed": false,
    "created_at": "2026-01-28T10:00:00Z",
    "updated_at": "2026-01-28T10:00:00Z"
  }
}
```

### Tool: list_tasks
**Purpose**: Retrieve tasks for the authenticated user with optional filtering

**Parameters**:
- `user_id`: string (required) - The ID of the user
- `status`: string (optional) - Filter by status ("all", "pending", "completed"), defaults to "all"

**Response**:
```json
{
  "success": true,
  "message": "Retrieved 3 tasks",
  "tasks": [
    {
      "id": 1,
      "title": "Buy groceries",
      "description": "Milk, eggs, bread",
      "completed": false,
      "created_at": "2026-01-28T10:00:00Z",
      "updated_at": "2026-01-28T10:00:00Z"
    }
  ]
}
```

### Tool: complete_task
**Purpose**: Mark a specific task as complete

**Parameters**:
- `user_id`: string (required) - The ID of the user
- `task_id`: integer (required) - The ID of the task to mark complete

**Response**:
```json
{
  "success": true,
  "message": "Task 'Buy groceries' marked as complete",
  "task": {
    "id": 123,
    "title": "Buy groceries",
    "completed": true
  }
}
```

### Tool: delete_task
**Purpose**: Remove a specific task from the user's list

**Parameters**:
- `user_id`: string (required) - The ID of the user
- `task_id`: integer (required) - The ID of the task to delete

**Response**:
```json
{
  "success": true,
  "message": "Task 'Buy groceries' deleted successfully"
}
```

### Tool: update_task
**Purpose**: Modify the title, description, or completion status of a task

**Parameters**:
- `user_id`: string (required) - The ID of the user
- `task_id`: integer (required) - The ID of the task to update
- `title`: string (optional) - New title for the task
- `description`: string (optional) - New description for the task
- `completed`: boolean (optional) - New completion status

**Response**:
```json
{
  "success": true,
  "message": "Task 'Buy groceries' updated successfully",
  "task": {
    "id": 123,
    "title": "Buy groceries and fruits",
    "description": "Milk, eggs, bread, apples",
    "completed": false
  }
}
```

---

## MCP Tool Schemas

### add_task Schema
```json
{
  "name": "add_task",
  "description": "Create a new task for the authenticated user",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string", "description": "The ID of the user"},
      "title": {"type": "string", "description": "The title of the task"},
      "description": {"type": "string", "description": "The description of the task"}
    },
    "required": ["user_id", "title"]
  }
}
```

### list_tasks Schema
```json
{
  "name": "list_tasks",
  "description": "Retrieve tasks for the authenticated user with optional filtering",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string", "description": "The ID of the user"},
      "status": {"type": "string", "enum": ["all", "pending", "completed"], "description": "Filter by status"}
    },
    "required": ["user_id"]
  }
}
```

### complete_task Schema
```json
{
  "name": "complete_task",
  "description": "Mark a specific task as complete",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string", "description": "The ID of the user"},
      "task_id": {"type": "integer", "description": "The ID of the task to mark complete"}
    },
    "required": ["user_id", "task_id"]
  }
}
```

### delete_task Schema
```json
{
  "name": "delete_task",
  "description": "Remove a specific task from the user's list",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string", "description": "The ID of the user"},
      "task_id": {"type": "integer", "description": "The ID of the task to delete"}
    },
    "required": ["user_id", "task_id"]
  }
}
```

### update_task Schema
```json
{
  "name": "update_task",
  "description": "Modify the title, description, or completion status of a task",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string", "description": "The ID of the user"},
      "task_id": {"type": "integer", "description": "The ID of the task to update"},
      "title": {"type": "string", "description": "New title for the task"},
      "description": {"type": "string", "description": "New description for the task"},
      "completed": {"type": "boolean", "description": "New completion status"}
    },
    "required": ["user_id", "task_id"]
  }
}
```

---

## MCP Server Implementation

### Required Endpoints
- `GET /mcp/tools` - Return available MCP tools and their schemas
- `POST /mcp/call/tool` - Execute MCP tool with parameters

### Authentication Requirements
- All MCP tool calls must include valid JWT token
- User ID in tool parameters must match authenticated user
- MCP server validates user permissions before executing tools

### Error Handling
- **Invalid Parameters**: Return 400 with validation details
- **Unauthorized Access**: Return 403 for cross-user access attempts
- **Resource Not Found**: Return 404 for non-existent tasks
- **Internal Errors**: Return 500 with generic error message

---

## Security Considerations

### User Isolation
- MCP tools enforce user ID matching between token and parameters
- Tasks can only be accessed/modified by their owner
- MCP server validates user permissions for each operation

### Input Validation
- All parameters validated against JSON schemas
- Task titles/descriptions sanitized before storage
- SQL injection prevention through parameterized queries
- Rate limiting for MCP tool calls

### Authentication
- JWT tokens validated before tool execution
- Token expiration checked automatically
- User session state maintained across tool calls

---

## Implementation Examples

### Using add_task tool
```
Use when: User wants to create a new task
Input: {"user_id": "user123", "title": "Buy groceries", "description": "Milk, eggs, bread"}
Output: Success response with created task details
```

### Using list_tasks tool
```
Use when: User wants to see their tasks
Input: {"user_id": "user123", "status": "pending"}
Output: Array of pending tasks for the user
```

### Using complete_task tool
```
Use when: User wants to mark a task as complete
Input: {"user_id": "user123", "task_id": 456}
Output: Success response confirming task completion
```

---

## Quality Assurance

### Validation Criteria
- MCP tools must follow JSON Schema specifications
- All tools must implement proper error handling
- User isolation must be enforced at all levels
- Authentication must be validated before execution
- Responses must be structured and consistent

### Testing Requirements
- Test each MCP tool individually
- Verify user isolation works correctly
- Test error conditions and validation
- Validate JSON Schema compliance
- Check authentication requirements

### Performance Standards
- MCP tool execution under 1 second
- Efficient database queries with proper indexing
- Caching for frequently accessed data
- Proper connection management
- Memory-efficient processing

---

## MCP Protocol Compliance

### Standards Adherence
- Follows MCP specification for tool definitions
- Proper JSON Schema validation
- Standardized error response formats
- Consistent parameter naming conventions
- Proper HTTP status codes

### Best Practices
- Minimal, focused tools for single operations
- Clear, descriptive tool names
- Comprehensive parameter documentation
- Structured, consistent responses
- Proper error categorization

This skill enables AI agents to interact with TaskFlow through standardized MCP tools, providing reusable intelligence for task management operations.