Task Master 的 MCP 集成架构从 CLI 到程序化 API 的分层设计与实践指南【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master本指南以仓库内 context/MCP_INTEGRATION.md 为骨架系统讲解 Task Master 如何通过分层架构 双接口复用模式将 CLI 命令能力平滑接入 MCPModel Context Protocol服务器从而同时服务交互式终端用户与 AI Agent / 程序化调用。读完本文你将掌握 source 参数驱动的核心函数编写范式、新增一个 MCP 工具的完整六步流程、工具注册与按需加载机制以及 CLI / MCP 双接口的测试与最佳实践。一、为什么需要 MCP 集成Task Master 本身是一个 AI 驱动的任务管理系统其核心业务逻辑集中在scripts/modules/下。传统上这些能力通过 CLI 命令暴露给终端用户但要让 Cursor、Claude Code、Lovable、Windsurf 等 AI 编码工具直接调用任务管理能力就需要一套符合 MCP 协议的程序化 API。MCP 集成正是在此背景下引入的它让同一份业务逻辑既可以被node scripts/dev.js这样的命令行驱动也可以被 MCP 服务器以结构化 JSON 的形式暴露给外部工具与 LLM。从仓库结构可以清楚看到这条集成路径的两端CLI 侧入口scripts/dev.js 与 scripts/modules/commands.jsMCP 侧入口mcp-server/src/index.js基于 FastMCP 的TaskMasterMCPServer。两者最终都汇聚到同一批核心业务模块上。二、分层架构总览文档给出的集成采用四层结构自下而上分别是Core Functions位于scripts/modules/承载主要业务逻辑Source Parameter核心函数通过source参数实际仓库中体现为context.outputType等决定行为差异Task Master Core位于 mcp-server/src/core/task-master-core.js集中提供 direct function 的直接导入MCP Tools位于 mcp-server/src/tools/将函数注册到 MCP 服务器。┌─────────────────┐ ┌─────────────────┐ │ CLI User │ │ MCP User │ └────────┬────────┘ └────────┬────────┘ │ │ ▼ ▼ ┌────────────────┐ ┌────────────────────┐ │ commands.js │ │ MCP Tool API │ └────────┬───────┘ └──────────┬─────────┘ │ │ │ │ ▼ ▼ ┌───────────────────────────────────────────────┐ │ │ │ Core Modules (task-manager.js, etc.) │ │ │ └───────────────────────────────────────────────┘这种设计的核心价值在于DRYDont Repeat Yourself业务逻辑只实现一次两个接口只做表现层差异。值得补充的是当前仓库的实际结构比文档描述的还要细致一层——scripts/modules/下的核心逻辑被进一步拆分为task-manager/子目录例如 scripts/modules/task-manager/add-task.js、scripts/modules/task-manager/update-task-by-id.js 等而mcp-server/src/core/下也相应地建立了direct-functions/目录一一对应这些核心函数。三、核心函数模式一份逻辑两种出口3.1 source 参数模式为了让一个核心函数同时服务 CLI 与 MCP文档提出了统一的编写范式函数接受options对象内部通过options.source分流 UI 展示与返回格式。/** * Example function with source parameter support * param {Object} options - Additional options including source * returns {Object|undefined} - Returns data when source is mcp */ function exampleFunction(param1, param2, options {}) { try { // Skip UI for MCP if (options.source ! mcp) { displayBanner(); console.log(chalk.blue(Processing operation...)); } // Do the core business logic const result doSomething(param1, param2); // For MCP, return structured data if (options.source mcp) { return { success: true, data: result }; } // For CLI, display output console.log(chalk.green(Operation completed successfully!)); } catch (error) { // Handle errors based on source if (options.source mcp) { return { success: false, error: error.message }; } // CLI error handling console.error(chalk.red(Error: ${error.message})); process.exit(1); } }这个模式有三个关键约定UI 跳过MCP 调用不渲染 banner 与加载动画避免污染 JSON 输出结构化返回MCP 分支返回{ success, data }或{ success, error }的统一对象错误隔离CLI 分支可以process.exit(1)MCP 分支则必须把错误作为返回值交给上层处理。3.2 仓库中的实际落地context outputType需要指出一个文档与代码的细微差异文档中提到的scripts/modules/source-adapter.js含adaptForMcp、sourceSplitFunction辅助函数在当前仓库中并未找到该文件。从源码结构看实际实现采用了更直接的context 对象传递 outputType 标记方案。以 scripts/modules/task-manager/add-task.js 为例addTask函数的 JSDoc 明确了这一约定async function addTask( tasksPath, prompt, dependencies [], // ... { session, mcpLog, projectRoot, commandName, outputType, tag }, // context // ... )其中context.outputType取值cli或mcp用于遥测与行为分支context.session、context.mcpLog则让核心函数可以直接与 MCP 会话交互并输出结构化日志。这与文档的source参数模式在精神上完全一致——用一份业务逻辑通过上下文参数分流两种调用场景。3.3 Silent Mode保护 MCP 响应的关键细节在 mcp-server/src/core/direct-functions/add-task.js 中可以看到direct function 入口会先调用enableSilentMode()结束时再调用disableSilentMode()。这两个函数定义于 scripts/modules/utils.js本质是切换一个全局silentMode开关使核心模块内部的console.log输出被抑制。这一设计非常关键MCP 工具返回给调用方的必须是干净的文本/JSON任何意外的终端输出都可能破坏响应解析。因此凡是走 MCP 路径的执行都必须在入口压制 UI 输出、出口恢复。addTaskDirect中甚至用try/catch/finally式的写法在 try 与 catch 两个分支都调用disableSilentMode()确保异常时开关也能复原。四、Task Master Coredirect function 集中层mcp-server/src/core/task-master-core.js是整个集成的中枢它批量导入direct-functions/下的所有实现并同时以Map 与命名导出两种方式暴露出去。从源码可见mcp-server/src/core/task-master-core.jsdirectFunctions是一个Map注册了约 30 个函数覆盖任务全生命周期类别代表函数任务创建与更新addTaskDirect、updateTaskByIdDirect、updateSubtaskByIdDirect、updateTasksDirect任务状态与调度setTaskStatusDirect、nextTaskDirect、getCacheStatsDirect任务展开与结构expandTaskDirect、expandAllTasksDirect、clearSubtasksDirect、removeSubtaskDirect依赖管理addDependencyDirect、removeDependencyDirect、validateDependenciesDirect、fixDependenciesDirect复杂度分析analyzeTaskComplexityDirect、complexityReportDirect标签体系addTagDirect、deleteTagDirect、listTagsDirect、useTagDirect、renameTagDirect、copyTagDirect项目初始化initializeProjectDirect、modelsDirect、researchDirect任务迁移moveTaskDirect、moveTaskCrossTagDirect范围调整scopeUpDirect、scopeDownDirectPRD 解析parsePRDDirect、removeTaskDirect以addTaskDirect为例mcp-server/src/core/direct-functions/add-task.js它的职责是参数适配把 MCP 工具传入的args解构出来处理依赖数组的字符串/数组兼容、默认优先级medium、手动创建与 AI 创建两条路径最终调用核心addTask并包装成{ success, data }结构返回。Map 结构的意义在于为未来扩展留有余地——代码注释明确写着用于潜在的 introspection 或动态派发task-master-core.js。五、MCP 工具层注册、映射与按需加载5.1 工具注册表工具层的核心是 mcp-server/src/tools/tool-registry.js它把工具名如add_task映射到对应的注册函数如registerAddTaskTool。当前注册表覆盖近 40 个工具除了传统任务管理工具外还通过tm/mcp包导入了 TypeScript 侧的 Autopilot 系列工具autopilot_start、autopilot_resume、autopilot_next、autopilot_status、autopilot_complete、autopilot_commit、autopilot_finalize、autopilot_abort以及generate、get_task、get_tasks、set_task_status。注册表同时定义了三种预置集合coreTools7 个get_tasks、next_task、get_task、set_task_status、update_subtask、parse_prd、expand_task覆盖日常开发的最小任务管理闭环standardTools14 个在 core 基础上追加initialize_project、analyze_project_complexity、expand_all、add_subtask、remove_task、add_task、complexity_report全部工具注册表内所有条目。5.2 按需加载TASK_MASTER_TOOLS 环境变量mcp-server/src/tools/index.js 中的getToolsConfiguration()读取TASK_MASTER_TOOLS环境变量未设置时默认core。registerTaskMasterTools(server, toolMode)支持以下取值取值行为all加载注册表中全部工具core/lean仅加载 7 个 core 工具standard加载 14 个 standard 工具自定义逗号分隔列表按名称精确匹配支持大小写不敏感、_/-互换归一化如response_language自动映射到response-language未知工具会被忽略并告警若全部无效则回退加载全部工具注册过程对每个工具做独立 try/catch已注册的工具报already registered会跳过并计入成功其余失败才记入failedTools。这种设计让服务器可以在all模式下安全地多次初始化也便于按需裁剪工具面控制 AI Agent 的工具选择空间。5.3 服务器启动流程mcp-server/src/index.js 中的TaskMasterMCPServer展示了完整启动链路构造 FastMCP 实例并用 Sentry 包装底层 MCP 服务器Sentry.wrapMcpServerWithSentry实现错误监控init()读取工具模式配置并调用registerTaskMasterTools统计成功/失败的工具数start()以stdio 传输启动超时设为 120 秒并监听connect事件——当客户端会话具备sampling能力时注册 MCP ProviderMCPProvider到 Provider Registry从而打通LLM 通过 MCP sampling 调用模型的能力。六、新增一个 MCP 兼容特性的完整流程文档给出六步流程下面结合真实源码逐一步骤展开。假设我们要新增一个new-feature命令。步骤 1在核心模块实现业务逻辑在scripts/modules/task-manager/下如new-feature.js实现核心函数遵循 source 分流模式// In scripts/modules/task-manager.js export async function newFeature(param1, param2, options {}) { try { // Source-specific UI if (options.source ! mcp) { displayBanner(); console.log(chalk.blue(Running new feature...)); } // Shared core logic const result processFeature(param1, param2); // Source-specific return handling if (options.source mcp) { return { success: true, data: result }; } // CLI output console.log(chalk.green(Feature completed successfully!)); displayOutput(result); } catch (error) { // Error handling based on source if (options.source mcp) { return { success: false, error: error.message }; } console.error(chalk.red(Error: ${error.message})); process.exit(1); } }步骤 2在 task-master-core.js 注册 direct 导入在 mcp-server/src/core/task-master-core.js 中导入新函数并同时加入directFunctionsMap 与命名导出块参照文件中既有 30 个函数的做法// In mcp-server/src/core/task-master-core.js import { newFeature } from ../../../scripts/modules/task-manager.js; // Add to exports export default { // ... existing functions async newFeature(args {}, options {}) { const { param1, param2 } args; return executeFunction(newFeature, [param1, param2], options); } };注意文档中的executeFunction封装在实际仓库中体现为*Direct包装函数它们负责参数解构、silent mode 开关与结构化返回这一层是 direct function 的核心职责。步骤 3更新命令映射文档建议在mcp-server/src/tools/utils.js维护commandMap。从当前仓库源码看实际机制已演进为工具注册函数直接调用executeTaskMasterCommand(command, log, cmdArgs, projectRoot)命令名作为第一个参数显式传入mcp-server/src/tools/utils.js。该函数会优先尝试全局task-masterCLI若不存在ENOENT则回退到node scripts/dev.js执行实现了对两种安装方式的无缝兼容// In mcp-server/src/tools/utils.js const commandMap { // ... existing mappings new-feature: newFeature };因此新增功能时确保scripts/dev.js能通过node scripts/dev.js new-feature --param1...调用即可被 MCP 工具复用。步骤 4创建工具实现在mcp-server/src/tools/下新建工具文件使用 Zod 声明参数 Schema并组合executeTaskMasterCommand、createContentResponse、createErrorResponse// In mcp-server/src/tools/newFeature.js import { z } from zod; import { executeTaskMasterCommand, createContentResponse, createErrorResponse } from ./utils.js; export function registerNewFeatureTool(server) { server.addTool({ name: newFeature, description: Run the new feature, parameters: z.object({ param1: z.string().describe(First parameter), param2: z.number().optional().describe(Second parameter), file: z.string().optional().describe(Path to the tasks file), projectRoot: z.string().describe(Root directory of the project) }), execute: async (args, { log }) { try { log.info(Running new feature with args: ${JSON.stringify(args)}); const cmdArgs []; if (args.param1) cmdArgs.push(--param1${args.param1}); if (args.param2) cmdArgs.push(--param2${args.param2}); if (args.file) cmdArgs.push(--file${args.file}); const projectRoot args.projectRoot; // Execute the command const result await executeTaskMasterCommand( new-feature, log, cmdArgs, projectRoot ); if (!result.success) { throw new Error(result.error); } return createContentResponse(result.stdout); } catch (error) { log.error(Error in new feature: ${error.message}); return createErrorResponse(Error in new feature: ${error.message}); } } }); }步骤 5注册到工具索引在 mcp-server/src/tools/index.js 的registerTaskMasterTools中接入当前实现通过 tool-registry 驱动需在 tool-registry.js 的toolRegistry中登记// In mcp-server/src/tools/index.js import { registerNewFeatureTool } from ./newFeature.js; export function registerTaskMasterTools(server) { // ... existing registrations registerNewFeatureTool(server); }步骤 6工具注册表登记最后在 tool-registry.js 的toolRegistry对象中添加new_feature: registerNewFeatureTool并视需要决定是否加入coreTools/standardTools数组。这样工具才能被TASK_MASTER_TOOLS环境变量按名加载。七、响应与项目根目录的工程化处理7.1 统一响应格式mcp-server/src/tools/utils.js 提供了两组响应构造函数createContentResponse(content)将对象 JSON 序列化为 FastMCP 要求的content: [{ type: text, text }]格式createErrorResponse(errorMessage, versionInfo, tagInfo)返回isError: true的文本响应并附带版本号与当前 tag 信息方便调用方快速定位环境。handleApiResult(result, log, errorPrefix, processFunction, projectRoot)则统一处理 direct function 的结果失败时构造错误响应成功时先经processMCPResponseData剔除details、testStrategy等大字段递归处理 subtasks再附带版本与 tag 元数据返回。processMCPResponseData能智能识别单任务、任务数组与{ tasks: [...] }包裹三种结构保证响应体积精简。7.2 projectRoot 解析优先级MCP 工具不持有终端工作目录因此withNormalizedProjectRoot高阶函数mcp-server/src/tools/utils.js会在执行前注入规范化的args.projectRoot其解析优先级为TASK_MASTER_PROJECT_ROOT环境变量进程级或会话级args.projectRoot显式参数处理file://前缀、URI 解码、Windows 盘符前缀MCP 会话的roots信息session.roots[0].uri及其变体兜底当前工作目录带告警。此外getProjectRootutils.js还支持基于PROJECT_MARKERS探测当前目录是否为 Task Master 项目并在找不到时给出--project-root或环境变量的使用建议。7.3 长任务的进度上报针对parse-prd、expand-task、expand-all、analyze等 AI 长任务checkProgressCapability(reportProgress, log)utils.js提供标准的进度能力探测若客户端上下文提供了reportProgress函数则原样返回否则返回undefined并记录 debug 日志操作照常执行但无进度更新——实现优雅降级。核心函数在reportProgress可用时会通过 session 实时推送Starting PRD analysis (Input: 5432 tokens)...、Task 2/10 - Create database schema 等进度消息。八、测试CLI 与 MCP 双接口验证任何 MCP 兼容特性都必须同时验证两个入口。文档给出的最小验证方式# Test CLI usage node scripts/dev.js new-feature --param1test --param2123 # Test MCP usage node mcp-server/tests/test-command.js newFeature在当前仓库中自动化测试集中在根目录tests/下tests/integration/mcp-server/direct-functions.test.js集成测试验证 direct function 的导入与执行通过 mock 文件系统mockReadFileSync、mockWriteFileSync等与 mock AI 流式输出mockHandleAnthropicStream在 fixture 项目上跑通完整任务流程tests/unit/mcp-server/tools/tool-registry.test.js单元测试验证工具注册表的完整性、名称归一化逻辑与TASK_MASTER_TOOLS各模式的加载行为mcp-server/src/core/tests/context-manager.test.js覆盖 context 缓存层的正确性。测试时特别要注意CLI 路径会真实渲染 UI 并可能process.exit而 MCP 路径必须返回结构化对象——这两者的断言方式完全不同务必分开覆盖。九、最佳实践文档总结的五条最佳实践与仓库实现一一对应保持核心逻辑 DRY业务逻辑只写一次CLI 与 MCP 仅做 UI/返回差异。仓库中核心函数与 direct function 的分层正是为此设计scripts/modules/task-manager/与mcp-server/src/core/direct-functions/一一对应职责边界清晰MCP 返回结构化数据direct function 统一返回{ success: true, data }或{ success: false, error: { code, message } }addTaskDirect甚至为缺失参数定义了MISSING_ARGUMENT、MISSING_PARAMETER等错误码便于调用方程序化处理一致的错误处理handleApiResult统一了成功/失败响应格式createErrorResponse附带版本与 tag 元数据确保 CLI 的process.exit(1)语义不会泄漏到 MCP 响应中文档同步更新每新增工具需同步维护 mcp-server/src/tools/ 下的工具描述Zod Schema 的describe文本会被 AI Agent 直接读取直接影响其调用意图识别并更新README-ZOD-V3.md等工具文档双接口测试任何新增或修改的特性都应在 CLInode scripts/dev.js command与 MCP工具注册与 direct function 集成测试两条路径上验证。十、总结Task Master 的 MCP 集成遵循核心逻辑单一实现、接口层按需适配的分层原则scripts/modules/负责业务、mcp-server/src/core/负责 direct 包装、mcp-server/src/tools/负责协议暴露、tool-registry.js与TASK_MASTER_TOOLS负责按需装载。理解这一链路后无论是为项目新增一个 MCP 工具还是排查某个工具在 CLI 正常但 MCP 调用异常的问题优先检查 silent mode、projectRoot 解析与响应格式你都有了清晰的排查路径与可复用的实现模板。【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考