MCP 任务管理服务器

本地模型上下文协议 (MCP) 服务器使用 SQLite 数据库为客户端驱动的项目和任务管理提供后端工具。

概述

该服务器充当本地 MCP 客户端（例如 AI 代理或脚本）的持久后端，这些客户端需要管理不同项目中的结构化任务数据。它负责数据存储并提供一套标准化的交互工具，而战略性工作流逻辑则驻留在客户端中。

主要特点：

• **基于项目：**任务在不同的项目内组织。
• **SQLite 持久性：**使用本地 SQLite 文件（默认为./data/taskmanager.db ）进行简单、独立的数据存储。
• **客户驱动：**为客户提供工具；不规定工作流程。
• **符合 MCP：**遵守模型上下文协议进行工具定义和通信。
• **任务管理：**支持创建项目、添加任务、列出/显示任务、更新状态、将任务扩展为子任务以及确定下一个可操作的任务。
• **导入/导出：**允许将项目数据导出为 JSON 并从 JSON 导入以创建新项目。

实施 MCP 工具

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

• createProject ：
  • **描述：**创建一个新的空项目。
  • 参数： projectName （字符串，可选，最大 255）
  • 返回： { project_id: string }
• addTask ：
  • **描述：**向项目添加新任务。
  • 参数： project_id （字符串，必需，UUID）、 description （字符串，必需，1-1024）、 dependencies （字符串[]，可选，最大 50）、 priority （枚举“高”|“中”|“低”，可选，默认“中”）、 status （枚举“待办事项”|“进行中”|“审核”|“完成”，可选，默认“待办事项”）
  • **返回：**创建任务的完整TaskData对象。
• listTasks ：
  • **描述：**列出项目的任务，并带有可选的过滤和子任务包含。
  • 参数： project_id （字符串，必需，UUID）、 status （枚举“todo”|“in-progress”|“review”|“done”，可选）、 include_subtasks （布尔值，可选，默认 false）
  • 返回： TaskData或StructuredTaskData对象的数组。
• showTask ：
  • **描述：**检索特定任务的完整详细信息，包括依赖关系和直接子任务。
  • 参数： project_id （字符串，必需，UUID）， task_id （字符串，必需）
  • 返回： FullTaskData对象。
• setTaskStatus ：
  • **描述：**更新一个或多个任务的状态。
  • 参数： project_id （字符串，必需，UUID）， task_ids （字符串[]，必需，1-100）， status （枚举'todo'|'in-progress'|'review'|'done'，必需）
  • 返回： { success: true, updated_count: number }
• expandTask ：
  • **描述：**将父任务分解为子任务，可选择替换现有任务。
  • 参数： project_id （字符串，必需，UUID）、 task_id （字符串，必需）、 subtask_descriptions （字符串[]，必需，1-20，每个 1-512）、 force （布尔值，可选，默认 false）
  • **返回：**更新的父FullTaskData对象，包括新的子任务。
• getNextTask ：
  • **描述：**根据状态（“待办事项”）、依赖关系（“完成”）、优先级和创建日期确定下一个可操作的任务。
  • 参数： project_id （字符串，必需，UUID）
  • **返回：**下一个任务的FullTaskData对象，如果没有准备好则返回null 。
• exportProject ：
  • **描述：**将完整的项目数据导出为 JSON 字符串。
  • 参数： project_id （字符串，必需，UUID）， format （枚举“json”，可选，默认“json”）
  • **返回：**代表项目的 JSON 字符串。
• importProject ：
  • **描述：**从导出的 JSON 字符串创建一个新项目。
  • 参数： project_data （字符串，必需，JSON）， new_project_name （字符串，可选，最大 255）
  • **返回：**新创建的项目的{ project_id: string } 。
• updateTask ：
  • **描述：**更新现有任务的具体详细信息（描述、优先级、依赖关系）。
  • 参数： project_id （字符串，必需，UUID）、 task_id （字符串，必需，UUID）、 description （字符串，可选，1-1024）、 priority （枚举“高”|“中”|“低”，可选）、 dependencies （字符串[]，可选，最大 50，替换现有的）
  • **返回：**更新的FullTaskData对象。
• deleteTask ：
  • **描述：**删除一个或多个任务（及其通过级联的子任务/依赖链接）。
  • 参数： project_id （字符串，必需，UUID）， task_ids （字符串[]，必需，1-100）
  • 返回： { success: true, deleted_count: number }
• deleteProject ：
  • **描述：**永久删除项目及其所有相关数据。请谨慎使用！
  • 参数： project_id （字符串，必需，UUID）
  • 返回： { success: true }

（注意：有关详细的 Zod 模式和参数描述，请参阅相应的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.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等）

代码检查和格式化

• Lint： npm run lint
• 格式： npm run format

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