npm package: @pranavchavda/todo-mcp-server
Description: A Model Context Protocol server for to-do list management in agentic workflows
Author: Pranav Chavda + Manus AI
Latest version: 0.1.1

# Todo MCP Server

A comprehensive Model Context Protocol (MCP) server for to-do list management in agentic workflows. This server enables LLM agents to track tasks, manage workflows, and maintain conversation context throughout complex multi-step processes.

## Features

- **Task Management**: Create, update, delete, and track tasks with rich metadata
- **Conversation Threading**: Associate tasks with specific conversation threads
- **Priority & Categorization**: Organize tasks by priority levels and categories
- **Status Tracking**: Monitor task progress through different states
- **Agentic Workflow Support**: Designed specifically for AI agent task management
- **MCP Compliance**: Full Model Context Protocol implementation
- **SQLite Persistence**: Reliable local data storage
- **Rich Prompts**: Built-in templates for planning and progress review

## Installation

### Using npx (Recommended)

```bash
npx todo-mcp-server
```

### Global Installation

```bash
npm install -g todo-mcp-server
todo-mcp-server
```

### Local Development

```bash
git clone https://github.com/manus-ai/todo-mcp-server.git
cd todo-mcp-server
npm install
npm run build
npm start
```

## Quick Start

1. **Start the server**:
   ```bash
   npx todo-mcp-server
   ```

2. **Configure your MCP client** to connect to the server via stdio

3. **Create your first task**:
   ```json
   {
     "method": "tools/call",
     "params": {
       "name": "create_task",
       "arguments": {
         "title": "Set up project structure",
         "description": "Initialize the basic project structure and dependencies",
         "priority": 4,
         "category": "development"
       }
     }
   }
   ```

## Configuration

The server accepts the following command-line options:

- `-d, --database <path>`: Specify database file path (default: `./todo.db`)

Example:
```bash
todo-mcp-server --database /path/to/my/tasks.db
```

## MCP Tools

### Task Management

#### `create_task`
Create a new task with optional metadata.

**Parameters:**
- `title` (required): Task title
- `description`: Detailed task description
- `priority`: Priority level (1-5, default: 3)
- `category`: Task category
- `tags`: Array of tags
- `due_date`: Due date in ISO format
- `conversation_id`: Associated conversation ID
- `parent_task_id`: Parent task for subtasks

#### `update_task`
Update an existing task.

**Parameters:**
- `task_id` (required): Task ID to update
- `title`: New task title
- `description`: New task description
- `status`: Task status (`pending`, `in_progress`, `completed`, `blocked`)
- `priority`: Priority level (1-5)
- `category`: Task category
- `tags`: Array of tags
- `due_date`: Due date in ISO format

#### `delete_task`
Delete a task by ID.

**Parameters:**
- `task_id` (required): Task ID to delete

#### `complete_task`
Mark a task as completed.

**Parameters:**
- `task_id` (required): Task ID to complete

#### `list_tasks`
List tasks with optional filtering.

**Parameters:**
- `conversation_id`: Filter by conversation ID
- `status`: Filter by status
- `category`: Filter by category
- `priority_min`: Minimum priority level
- `priority_max`: Maximum priority level
- `limit`: Maximum number of tasks to return
- `offset`: Number of tasks to skip

### Conversation Management

#### `create_conversation`
Create a new conversation thread.

**Parameters:**
- `title`: Conversation title
- `description`: Conversation description
- `agent_id`: Agent identifier

### Analytics

#### `get_task_statistics`
Get task completion statistics.

**Parameters:**
- `conversation_id`: Filter by conversation ID
- `date_range`: Date range (e.g., "7d", "30d", "1y")

## MCP Resources

### `todo://tasks`
Access to all tasks in JSON format.

### `todo://conversations`
Access to all conversation threads in JSON format.

## MCP Prompts

### `daily_planning`
Template for daily task planning and organization.

### `project_breakdown`
Template for breaking down complex projects into manageable tasks.

### `progress_review`
Template for reviewing progress and planning next steps.

## Database Schema

The server uses SQLite with the following schema:

### Tasks Table
- `id`: Primary key
- `title`: Task title
- `description`: Task description
- `status`: Task status (pending, in_progress, completed, blocked)
- `priority`: Priority level (1-5)
- `category`: Task category
- `tags`: JSON array of tags
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp
- `due_date`: Due date
- `completed_at`: Completion timestamp
- `conversation_id`: Associated conversation ID
- `agent_id`: Agent identifier
- `parent_task_id`: Parent task ID for subtasks
- `metadata`: JSON metadata

### Conversations Table
- `id`: Primary key (UUID)
- `title`: Conversation title
- `description`: Conversation description
- `agent_id`: Agent identifier
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp
- `status`: Conversation status (active, archived, completed)
- `metadata`: JSON metadata

### Task Dependencies Table
- `id`: Primary key
- `task_id`: Task ID
- `depends_on_task_id`: Dependency task ID
- `dependency_type`: Dependency type (blocks, requires, related)
- `created_at`: Creation timestamp

## API Examples

### Creating a Task

```json
{
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "Research MCP specification",
      "description": "Study the Model Context Protocol documentation and examples",
      "priority": 5,
      "category": "research",
      "tags": ["mcp", "documentation"],
      "due_date": "2024-12-31T23:59:59Z",
      "conversation_id": "conv-123"
    }
  }
}
```

### Listing Tasks

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {
      "conversation_id": "conv-123",
      "status": "pending",
      "priority_min": 3,
      "limit": 10
    }
  }
}
```

### Getting Statistics

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_task_statistics",
    "arguments": {
      "conversation_id": "conv-123",
      "date_range": "7d"
    }
  }
}
```

## Integration with MCP Clients

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["todo-mcp-server"],
      "env": {}
    }
  }
}
```

### Custom MCP Client

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['todo-mcp-server']
});

const client = new Client({
  name: "my-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);
```

## Development

### Project Structure

```
todo-mcp-server/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── database.ts       # Database layer
│   └── todo-manager.ts   # Business logic
├── dist/                 # Compiled JavaScript
├── tests/               # Test files
├── docs/                # Documentation
├── examples/            # Usage examples
├── package.json
├── tsconfig.json
└── README.md
```

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
```

### Formatting

```bash
npm run format
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run linting and tests
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: https://github.com/manus-ai/todo-mcp-server/issues
- Documentation: https://github.com/manus-ai/todo-mcp-server/docs
- Examples: https://github.com/manus-ai/todo-mcp-server/examples

## Changelog

### v0.1.0
- Initial release
- Basic task management functionality
- MCP protocol compliance
- SQLite persistence
- Conversation threading
- Built-in prompts for planning and review