Task Guardian MCP

任务守护者MCP

用于Cursor等AI驱动开发环境中智能任务管理的模型上下文协议（MCP）服务器。

特性

• 📁 基于文件的存储 -任务以JSON文件存储在 .task/ 目录
• 🔢 顺序ID -简单、递增的任务编号
• 🔗 类型化依赖关系 -任务之间的模型关系（块、需求、相关）
• 🔄 循环检测 -在创建时防止循环依赖
• 📝 丰富的描述 -通过代码块和检查表提供全面的降价支持
• 🎯 任务类型 -支持用户故事、任务和错误
• 🔍 高级查询 -筛选、排序和搜索任务
• ⚡ 批量操作 -一次创建或更新多个任务
• 📦 自定义元数据 -在任务上存储项目特定的属性
• 🖥️ 交互式CLI -使用Ink和React查看任务的漂亮终端UI

安装

bun install

用法

运行服务器

启动MCP服务器：

bun start

对于自动重新加载的开发：

bun run dev

CLI工具

使用交互式终端UI查看项目中的任务：

bun run cli

CLI从 .task 您当前工作目录中的目录，并在带有交互式导航的漂亮彩色编码表中显示任务。

特征：

• 🎯 使用箭头键浏览任务
• 👁️ 查看任何任务的详细信息
• 🎨 颜色编码的状态、优先级和类型指示器
• 🔍 按状态、优先级或类型筛选任务
• ⌨️ 全键盘导航

选项：

• --status -按状态筛选（待定|in_process|已完成|已阻止|已取消）
• `--priority

` -按优先级筛选（低|中|高|关键）

• --type -按类型筛选（user_story|task|bug）
• --help -显示帮助消息

示例：

# List all tasks
bun run cli

# List in-progress tasks only
bun run cli --status in_progress

# List high priority tasks
bun run cli --priority high

# Combine filters
bun run cli --status pending --priority critical

键盘快捷键：

*在列表视图中：*

• ↑/↓ 或 j/k -浏览任务（支持vim风格）
• Enter -查看所选任务详细信息
• q -退出应用程序
• Ctrl+C -退出

*在详细视图中：*

• 使用终端的原生滚动（鼠标滚轮、触控板或终端滚动命令）
• Esc 或 b -返回列表
• q -退出应用程序

光标集成

将任务守护者添加到游标MCP配置中：

位置: ~/.cursor/config/mcp_settings.json

{
  "mcpServers": {
    "task-guardian": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/task-guardian-mcp/src/index.ts"]
    }
  }
}

替换 /absolute/path/to/task-guardian-mcp 使用您计算机上此存储库的实际路径。

任务架构

任务存储在 .task/task-{id}.json 具有以下结构：

{
  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;
  createdAt: string;       // ISO8601 timestamp
  updatedAt: string;       // ISO8601 timestamp
  [key: string]: any;      // Custom metadata fields
}

可用工具

核心业务

• create_task -创建新任务
• get_task -按ID检索任务
• update_task -更新任务字段
• delete_task -删除任务（带依赖性检查）
• list_tasks -列出具有可选筛选功能的任务
• query_tasks -具有排序和分页功能的高级搜索

依赖管理

• add_dependency -添加类型化依赖关系（带循环检测）
• remove_dependency -删除依赖关系链接

批量操作

• create_tasks -一次创建多个任务
• update_tasks -一次更新多个任务

例子

创建任务

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

添加依赖关系

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

查询任务

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

建筑

• 类型 (src/types/)-类型定义和常量使用 as const 模式
• 模式 (src/schemas/)-带类型推理的Zod验证模式
• 服务 (src/services/)-任务和依赖关系的业务逻辑
• 工具 (src/tools/)-MCP工具实施
• 索引 (src/index.ts)-MCP服务器入口点

发展

类型检查：

bun run typecheck

文件结构

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

TypeScript最佳实践

这个项目遵循现代TypeScript模式：

• ✅ as const 对象而不是枚举
• ✅ 单真值源的Zod模式推理
• ✅ 错误处理的结果类型
• ✅ readonly 不变性修饰词
• ✅ type 超过 interface 用于数据形状
• ✅ 许可验证 .passthrough()

许可证

麻省理工学院

相关

• ADR-001：初始架构
• 模型上下文协议
• 游标文档