MCP 任务管理服务器

这是一个本地的模型上下文协议（MCP）服务器，它使用 SQLite 数据库为客户端驱动的项目和任务管理提供后端工具。

概述

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

主要特性：

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

实现的 MCP 工具

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

[此处保留代码块或链接内容]

• createProject:
  • Description: Creates a new, empty project.
  • Params: projectName (string, optional, max 255)
  • Returns: { project_id: string }
• addTask:
  • Description: Adds a new task to a project.
  • Params: project_id (string, required, UUID), description (string, required, 1-1024), dependencies (string[], optional, max 50), priority (enum 'high'|'medium'|'low', optional, default 'medium'), status (enum 'todo'|'in-progress'|'review'|'done', optional, default 'todo')
  • Returns: Full TaskData object of the created task.
• listTasks:
  • Description: Lists tasks for a project, with optional filtering and subtask inclusion.
  • Params: project_id (string, required, UUID), status (enum 'todo'|'in-progress'|'review'|'done', optional), include_subtasks (boolean, optional, default false)
  • Returns: Array of TaskData or StructuredTaskData objects.
• showTask:
  • Description: Retrieves full details for a specific task, including dependencies and direct subtasks.
  • Params: project_id (string, required, UUID), task_id (string, required)
  • Returns: FullTaskData object.
• setTaskStatus:
  • Description: Updates the status of one or more tasks.
  • Params: project_id (string, required, UUID), task_ids (string[], required, 1-100), status (enum 'todo'|'in-progress'|'review'|'done', required)
  • Returns: { success: true, updated_count: number }
• expandTask:
  • Description: Breaks a parent task into subtasks, optionally replacing existing ones.
  • Params: project_id (string, required, UUID), task_id (string, required), subtask_descriptions (string[], required, 1-20, each 1-512), force (boolean, optional, default false)
  • Returns: Updated parent FullTaskData object including new subtasks.
• getNextTask:
  • Description: Identifies the next actionable task based on status ('todo'), dependencies ('done'), priority, and creation date.
  • Params: project_id (string, required, UUID)
  • Returns: FullTaskData object of the next task, or null if none are ready.
• exportProject:
  • Description: Exports complete project data as a JSON string.
  • Params: project_id (string, required, UUID), format (enum 'json', optional, default 'json')
  • Returns: JSON string representing the project.
• importProject:
  • Description: Creates a new project from an exported JSON string.
  • Params: project_data (string, required, JSON), new_project_name (string, optional, max 255)
  • Returns: { project_id: string } of the newly created project.
• updateTask:
  • Description: Updates specific details (description, priority, dependencies) of an existing task.
  • Params: project_id (string, required, UUID), task_id (string, required, UUID), description (string, optional, 1-1024), priority (enum 'high'|'medium'|'low', optional), dependencies (string[], optional, max 50, replaces existing)
  • Returns: Updated FullTaskData object.
• deleteTask:
  • Description: Deletes one or more tasks (and their subtasks/dependency links via cascade).
  • Params: project_id (string, required, UUID), task_ids (string[], required, 1-100)
  • Returns: { success: true, deleted_count: number }
• deleteProject:
  • Description: Permanently deletes a project and ALL associated data. Use with caution!
  • Params: project_id (string, required, UUID)
  • Returns: { 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 等)

代码检查和格式化

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

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