# MCP Task Management Server

An advanced Model Context Protocol (MCP) server for comprehensive task management with groups, custom statuses, task relationships, and AI integration. Now powered by SQLite for enhanced performance and reliability.

## Features

- **Task Management**: Create, update, delete, and search tasks with rich metadata
- **Bulk Operations**: Create, update, and change status of multiple tasks simultaneously
- **Task Groups**: Organize tasks into projects, areas, or any custom groupings
- **Custom Statuses**: Define your own workflow statuses with colors and descriptions
- **Task References**: Create relationships between tasks (blocks, relates-to, child-of, etc.)
- **Status History**: Automatic tracking of status changes with timestamps
- **Markdown Support**: Task descriptions support full markdown formatting
- **AI-Friendly**: Designed for AI assistants to automatically manage tasks during conversations
- **Persistent Storage**: SQLite database with automatic migration from JSON format

## Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```

## Usage

### As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "mcp-task": {
      "command": "node",
      "args": ["/path/to/mcp-task/build/index.js"]
    }
  }
}
```

### Direct Usage

You can also run the server directly:

```bash
npm start
```

## Data Storage

### SQLite Database (Default)

The server now uses **SQLite** as the default database for improved performance, reliability, and data integrity. Tasks are stored in `~/.mcp-tasks.sqlite`.

**Benefits of SQLite:**
- Better performance for large datasets
- ACID transactions ensure data consistency
- Structured queries and indexing
- Automatic migration from JSON format

### Legacy JSON Support

For compatibility, the server can still use JSON storage by setting the environment variable:
```bash
export MCP_TASK_USE_SQLITE=false
```

**Automatic Migration:** When upgrading from JSON to SQLite, the server automatically migrates your existing `~/.mcp-tasks.json` data to the new SQLite format.

## Available Tools

### Task Operations

- **create_task**: Create a new task with title, description, status, group, priority, tags, assignee, due date, and time estimates
- **update_task**: Update any task properties. Status changes are automatically tracked with timestamps
- **get_task**: Get detailed task information including history and references
- **list_tasks**: List and filter tasks by status, group, assignee, tags, priority, due dates, or search terms
- **delete_task**: Delete a task and remove all references to it

### Bulk Operations

- **bulk_create_tasks**: Create multiple tasks at once with shared properties (group, status, assignee, tags)
- **bulk_update_tasks**: Update multiple tasks simultaneously with the same changes
- **bulk_change_status**: Change the status of multiple tasks at once with optional notes

### Group Management

- **create_group**: Create task groups for organizing related tasks (projects, areas, etc.)
- **list_groups**: List all groups with metadata
- **delete_group**: Delete a group (tasks remain but become ungrouped)

### Status Management

- **create_status**: Create custom workflow statuses with colors and descriptions
- **list_statuses**: List all available statuses
- **delete_status**: Delete custom statuses (cannot delete default or in-use statuses)

### Task Relationships

- **add_task_reference**: Create relationships between tasks:
  - `blocks` / `blocked-by`: Dependency relationships
  - `relates-to`: General relationship
  - `duplicates`: Duplicate tasks
  - `child-of` / `parent-of`: Hierarchical relationships
- **remove_task_reference**: Remove task relationships
- **get_task_references**: View all incoming and outgoing task references

## AI Integration

This MCP server is specifically designed for AI assistants to:

1. **Automatically create tasks** when users mention work they need to do
2. **Update task status** as work progresses during conversations
3. **Break down complex requests** into manageable subtasks with references
4. **Track project progress** by organizing tasks into groups
5. **Manage dependencies** by creating task references
6. **Provide context** by searching and filtering existing tasks
7. **Handle bulk operations** for efficient project setup and team management

### Example AI Usage Patterns

**Creating tasks from conversation:**
```
User: "I need to implement user authentication and then build the dashboard"
AI: Creates two tasks:
- "Implement user authentication"
- "Build dashboard" (with "blocked-by" reference to auth task)
```

**Status tracking:**
```
User: "I finished the login form"
AI: Updates relevant task status to "Done" and adds completion timestamp
```

**Project organization:**
```
User: "Let's start working on the mobile app redesign"
AI: Creates a "Mobile App Redesign" group and organizes related tasks
```

**Bulk project setup:**
```
User: "I need to set up tasks for the Q1 marketing campaign"
AI: Uses bulk_create_tasks to create multiple related tasks at once:
- "Design campaign assets", "Write copy", "Set up analytics", etc.
```

**Team workflow management:**
```
User: "Move all the design tasks to review status"
AI: Uses bulk_change_status to transition multiple tasks simultaneously
```

## Data Model

### Task Properties

- **Basic Info**: ID, title, description, summary
- **Organization**: status, group, priority, tags, assignee
- **Timing**: due date, estimated hours, actual hours
- **Tracking**: created/updated timestamps, completion date
- **Relationships**: references to other tasks
- **History**: Complete status change history

### Task Statuses

Default statuses include "To Do", "In Progress", and "Done", but you can create custom statuses like "Review", "Testing", "Blocked", etc.

### Task Groups

Organize tasks into logical groups like:
- Projects ("Website Redesign", "Mobile App")
- Areas ("Marketing", "Development", "Operations")
- Contexts ("Home", "Office", "Travel")

### Task References

Model complex relationships:
- **Dependencies**: Task A blocks Task B
- **Hierarchy**: Parent/child task relationships
- **Related work**: Tasks that relate to each other
- **Duplicates**: Mark duplicate tasks

## Complete Tool Reference

The server provides **17 comprehensive tools** designed for AI assistants:

**Task Operations**: create_task, update_task, get_task, list_tasks, delete_task
**Bulk Operations**: bulk_create_tasks, bulk_update_tasks, bulk_change_status
**Groups**: create_group, list_groups, delete_group
**Statuses**: create_status, list_statuses, delete_status
**References**: add_task_reference, remove_task_reference, get_task_references

### Bulk Operations in Detail

**bulk_create_tasks**: Perfect for project initialization, breaking down large initiatives into subtasks, or importing task lists. Supports shared properties (group, status, assignee, tags) that apply to all tasks while allowing individual task customization.

**bulk_update_tasks**: Ideal for team management scenarios like reassigning multiple tasks, updating priorities across a project, or applying deadline changes to related tasks.

**bulk_change_status**: Essential for workflow management such as moving multiple tasks through pipeline stages, marking sprint tasks as complete, or transitioning project phases.

Each tool includes comprehensive error handling, detailed result reporting, and maintains data integrity even during partial failures.

## Development

### Build
```bash
npm run build
```

### Development mode with auto-rebuild
```bash
npm run dev
```

### Project Structure

```
src/
├── types.ts      # TypeScript type definitions
├── database.ts   # Data persistence and management
└── index.ts      # MCP server implementation
```

## License

ISC License