# Task Guardian MCP

A Model Context Protocol (MCP) server for intelligent task management in AI-powered development environments like Cursor.

## Features

- 📁 **File-based storage** - Tasks stored as JSON files in `.task/` directory
- 🔢 **Sequential IDs** - Simple, incremental task numbering
- 🔗 **Typed dependencies** - Model relationships between tasks (blocks, requires, related-to)
- 🔄 **Cycle detection** - Prevents circular dependencies at creation time
- 📝 **Rich descriptions** - Full markdown support with code blocks and checklists
- 🎯 **Task types** - Support for user stories, tasks, and bugs
- 🔍 **Advanced querying** - Filter, sort, and search tasks
- ⚡ **Batch operations** - Create or update multiple tasks at once
- 📦 **Custom metadata** - Store project-specific attributes on tasks
- 🖥️ **Interactive CLI** - Beautiful terminal UI for viewing tasks with Ink and React

## Installation

### From npm (recommended)

```bash
npx task-guardian-mcp
```

### From source

```bash
pnpm install
```

## Usage

### Running the Server

Start the MCP server:

```bash
pnpm start
```

For development with auto-reload:

```bash
pnpm dev
```

### CLI Tool

View tasks in your project using an interactive terminal UI:

```bash
pnpm cli
```

The CLI reads from the `.task` directory in your current working directory and displays tasks in a beautiful, color-coded table with interactive navigation.

**Features:**

- 🎯 Navigate through tasks with arrow keys
- 👁️ View detailed information for any task
- 🎨 Color-coded status, priority, and type indicators
- 🔍 Filter tasks by status, priority, or type
- ⌨️ Full keyboard navigation

**Options:**

- `--status <status>` - Filter by status (pending|in_progress|completed|blocked|cancelled)
- `--priority <priority>` - Filter by priority (low|medium|high|critical)
- `--type <type>` - Filter by type (user_story|task|bug)
- `--help` - Show help message

**Examples:**

```bash
# List all tasks
pnpm cli

# List in-progress tasks only
pnpm cli --status in_progress

# List high priority tasks
pnpm cli --priority high

# Combine filters
pnpm cli --status pending --priority critical
```

**Keyboard shortcuts:**

_In List View:_

- `↑`/`↓` or `j`/`k` - Navigate through tasks (vim-style supported)
- `Enter` - View selected task details
- `q` - Quit the application
- `Ctrl+C` - Exit

_In Detail View:_

- Use your terminal's native scrolling (mouse wheel, trackpad, or terminal scroll commands)
- `Esc` or `b` - Back to list
- `q` - Quit the application

### Cursor Integration

Add Task Guardian to your Cursor MCP configuration:

**Location**: `~/.cursor/config/mcp_settings.json`

#### Using npx (recommended)

```json
{
  "mcpServers": {
    "task-guardian": {
      "command": "npx",
      "args": ["-y", "task-guardian-mcp"]
    }
  }
}
```

#### From source

```json
{
  "mcpServers": {
    "task-guardian": {
      "command": "node",
      "args": ["/absolute/path/to/task-guardian-mcp/dist/index.mjs"]
    }
  }
}
```

Replace `/absolute/path/to/task-guardian-mcp` with the actual path to this repository on your machine.

## Task Schema

Tasks are stored in `.task/task-{id}.json` with the following structure:

```typescript
{
  id: number;              // Sequential ID (1, 2, 3, ...)
  title: string;           // Task title (1-200 chars)
  description: string;     // Markdown-formatted description
  status: 'pending' | 'in_progress' | 'completed' | 'blocked' | 'cancelled';
  priority: 'low' | 'medium' | 'high' | 'critical';
  type: 'user_story' | 'task' | 'bug';
  dependencies: Array<{
    taskId: number;
    type: 'blocks' | 'requires' | 'related-to';
    description?: string;
  }>;
  createdAt: string;       // ISO8601 timestamp
  updatedAt: string;       // ISO8601 timestamp
  [key: string]: any;      // Custom metadata fields
}
```

## Available Tools

### Core Operations

- **`create_task`** - Create a new task
- **`get_task`** - Retrieve a task by ID
- **`update_task`** - Update task fields
- **`delete_task`** - Delete a task (with dependency check)
- **`list_tasks`** - List tasks with optional filtering
- **`query_tasks`** - Advanced search with sorting and pagination

### Dependency Management

- **`add_dependency`** - Add a typed dependency (with cycle detection)
- **`remove_dependency`** - Remove a dependency link

### Batch Operations

- **`create_tasks`** - Create multiple tasks at once
- **`update_tasks`** - Update multiple tasks at once

## Examples

### Creating a Task

```json
{
  "title": "Implement OAuth2 authentication",
  "description": "## Overview\n\nAdd OAuth2 support using Google identity provider.\n\n## Acceptance Criteria\n\n- [ ] User can login with Google\n- [ ] JWT tokens generated\n- [ ] Token refresh works",
  "priority": "high",
  "type": "task"
}
```

### Adding Dependencies

```json
{
  "fromTaskId": 5,
  "toTaskId": 3,
  "type": "blocks",
  "description": "OAuth requires database setup first"
}
```

### Querying Tasks

```json
{
  "filters": {
    "status": ["in_progress", "blocked"],
    "priority": ["high", "critical"],
    "titleContains": "auth"
  },
  "sort": {
    "field": "priority",
    "order": "desc"
  },
  "limit": 10
}
```

## Architecture

- **Types** (`src/types/`) - Type definitions and constants using `as const` pattern
- **Schemas** (`src/schemas/`) - Zod validation schemas with type inference
- **Services** (`src/services/`) - Business logic for tasks and dependencies
- **Tools** (`src/tools/`) - MCP tool implementations
- **Index** (`src/index.ts`) - MCP server entry point

## Development

Type checking:

```bash
pnpm typecheck
```

Build:

```bash
pnpm build
```

## File Structure

```
.task/
├── .meta.json           # Stores last task ID
├── task-1.json          # Individual task files
├── task-2.json
└── archive/             # Archived completed tasks
    └── task-old.json
```

## TypeScript Best Practices

This project follows modern TypeScript patterns:

- ✅ `as const` objects instead of enums
- ✅ Zod schema inference for single source of truth
- ✅ Result types for error handling
- ✅ `readonly` modifiers for immutability
- ✅ `type` over `interface` for data shapes
- ✅ Permissive validation with `.passthrough()`

## License

MIT

## Related

- [ADR-001: Initial Architecture](docs/adr/001-initial-architecture.md)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Cursor Documentation](https://cursor.sh/docs)