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)

npx task-guardian-mcp

From source

pnpm install

Usage

Running the Server

Start the MCP server:

pnpm start

For development with auto-reload:

pnpm dev

CLI Tool

View tasks in your project using an interactive terminal UI:

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:

# 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)

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

From source

{
  "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:

{
  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

{
  "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

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

Querying Tasks

{
  "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:

pnpm typecheck

Build:

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
• Model Context Protocol
• Cursor Documentation