MCP Task Manager Server

MCP 任务管理器服务

一个本地 Model Context Protocol (MCP) 服务，使用 SQLite 数据库为客户端驱动的项目和任务管理提供后端工具。

概述

该服务作为本地 MCP 客户端（如 AI Agent 或脚本）的持久化后端，用于在不同项目中管理结构化任务数据。它负责数据存储，并提供一套标准化的工具供交互使用，而策略性工作流逻辑则位于客户端中。

主要特性：

• 基于项目： 任务在不同项目中组织管理。
• SQLite 持久化： 使用本地 SQLite 文件（默认为 ./data/taskmanager.db）实现简单、自包含的数据存储。
• 客户端驱动： 为客户端提供工具；不规定工作流。
• 符合 MCP 规范： 遵循 Model Context Protocol 进行工具定义和通信。
• 任务管理： 支持创建项目、添加任务、列出/显示任务、更新状态、将任务展开为子任务，以及识别下一个可执行任务。
• 导入/导出： 允许将项目数据导出为 JSON，并从 JSON 导入以创建新项目。

已实现的 MCP 工具

以下工具可供 MCP 客户端使用：

• createProject：
  • 描述： 创建一个新的空项目。
  • 参数： projectName（string，可选，最大 255）
  • 返回： { project_id: string }
• addTask：
  • 描述： 向项目添加一个新任务。
  • 参数： project_id（string，必填，UUID）、description（string，必填，1-1024）、dependencies（string[]，可选，最大 50）、priority（enum 'high'|'medium'|'low'，可选，默认 'medium'）、status（enum 'todo'|'in-progress'|'review'|'done'，可选，默认 'todo'）
  • 返回： 所创建任务的完整 TaskData 对象。
• listTasks：
  • 描述： 列出项目的任务，支持可选筛选和包含子任务。
  • 参数： project_id（string，必填，UUID）、status（enum 'todo'|'in-progress'|'review'|'done'，可选）、include_subtasks（boolean，可选，默认 false）
  • 返回： TaskData 或 StructuredTaskData 对象数组。
• showTask：
  • 描述： 检索特定任务的完整详情，包括依赖项和直接子任务。
  • 参数： project_id（string，必填，UUID）、task_id（string，必填）
  • 返回： FullTaskData 对象。
• setTaskStatus：
  • 描述： 更新一个或多个任务的状态。
  • 参数： project_id（string，必填，UUID）、task_ids（string[]，必填，1-100）、status（enum 'todo'|'in-progress'|'review'|'done'，必填）
  • 返回： { success: true, updated_count: number }
• expandTask：
  • 描述： 将父任务拆分为子任务，可选择替换现有子任务。
  • 参数： project_id（string，必填，UUID）、task_id（string，必填）、subtask_descriptions（string[]，必填，1-20，每项 1-512）、force（boolean，可选，默认 false）
  • 返回： 更新后的父任务 FullTaskData 对象，包含新的子任务。
• getNextTask：
  • 描述： 根据状态（'todo'）、依赖项（'done'）、优先级和创建日期确定下一个可执行任务。
  • 参数： project_id（string，必填，UUID）
  • 返回： 下一个任务的 FullTaskData 对象，如果没有就绪任务则返回 null。
• exportProject：
  • 描述： 将完整项目数据导出为 JSON 字符串。
  • 参数： project_id（string，必填，UUID）、format（enum 'json'，可选，默认 'json'）
  • 返回： 表示项目的 JSON 字符串。
• importProject：
  • 描述： 从导出的 JSON 字符串创建新项目。
  • 参数： project_data（string，必填，JSON）、new_project_name（string，可选，最大 255）
  • 返回： 新创建项目的 { project_id: string }。
• updateTask：
  • 描述： 更新现有任务的特定详情（描述、优先级、依赖项）。
  • 参数： project_id（string，必填，UUID）、task_id（string，必填，UUID）、description（string，可选，1-1024）、priority（enum 'high'|'medium'|'low'，可选）、dependencies（string[]，可选，最大 50，替换现有项）
  • 返回： 更新后的 FullTaskData 对象。
• deleteTask：
  • 描述： 删除一个或多个任务（及其子任务/通过级联删除依赖链接）。
  • 参数： project_id（string，必填，UUID）、task_ids（string[]，必填，1-100）
  • 返回： { success: true, deleted_count: number }
• deleteProject：
  • 描述： 永久删除项目及所有关联数据。请谨慎使用！
  • 参数： project_id（string，必填，UUID）
  • 返回： { success: true }

（注意：有关详细的 Zod schema 和参数说明，请参阅相应的 src/tools/*Params.ts 文件。）

快速开始

1. 前置条件： Node.js（推荐 LTS 版本）、npm。

2. 安装依赖：

   npm install
   

3. 以开发模式运行：（使用 ts-node 和 nodemon 实现自动重载）

   npm run dev
   

   服务将通过 stdio 连接。日志（JSON 格式）将输出到 stderr。SQLite 数据库将在 ./data/taskmanager.db 中创建/更新。

4. 为生产环境构建：

   npm run build
   

5. 运行生产构建：

   npm start
   

配置

• 数据库路径： 可以通过设置 DATABASE_PATH 环境变量来覆盖 SQLite 数据库文件的位置。默认值为 ./data/taskmanager.db。
• 日志级别： 可以使用 LOG_LEVEL 环境变量设置日志级别（例如 debug、info、warn、error）。默认值为 info。

项目结构

• /src：源代码。
  • /config：配置管理。
  • /db：数据库管理器和 schema（schema.sql）。
  • /repositories：数据访问层（SQLite 交互）。
  • /services：核心业务逻辑。
  • /tools：MCP 工具定义（*Params.ts）和实现（*Tool.ts）。
  • /types：共享的 TypeScript 接口（目前较少，大多在 repos/services 中）。
  • /utils：日志、自定义错误等。
  • createServer.ts：服务实例创建。
  • server.ts：主应用入口点。
• /dist：编译后的 JavaScript 输出。
• /docs：项目文档（PRD、功能规格、RFC）。
• /data：SQLite 数据库文件的默认位置（自动创建）。
• tasks.md：用于开发的手动任务跟踪文件。
• 配置文件（package.json、tsconfig.json、.eslintrc.json 等）

代码检查与格式化

• 代码检查： npm run lint
• 格式化： npm run format

（提交时通过 Husky/lint-staged 自动进行代码检查/格式化）。