Task Master AI Algae

任务大师AI藻类

用于任务管理的最小MCP（模型上下文协议）服务器，作为扩展任务主功能的起点而构建。该服务器提供与Claude Desktop无缝协作的AI驱动任务管理工具。

特性

• 初始化：使用目录结构、配置文件和Roo代码集成初始化完整的Task Master项目
• 正确记录：所有操作都记录到 logs/task-master-mcp.log 不干扰MCP stdio通信
• Roo代码集成：为专门的开发模式设置.roomode和规则文件
• 项目结构：创建.taskmaster目录，其中包含任务、文档、报告和模板的有序子目录

安装

方法1：从GitHub克隆（推荐）

# Clone the repository
git clone https://github.com/algae514/task-master-ai-algae.git
cd task-master-ai-algae

# Install dependencies
npm install

方法二：地方发展

cd /path/to/your/local/copy
npm install

Claude桌面集成

步骤1：查找您的Claude桌面配置文件

位置取决于您的操作系统：

步骤2：更新配置

将以下内容添加到您的 claude_desktop_config.json:

选项A：使用克隆存储库

{
  "mcpServers": {
    "task-master-ai-algae": {
      "command": "node",
      "args": ["/full/path/to/task-master-ai-algae/server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

选项B：使用NPX（如果发布到npm）

{
  "mcpServers": {
    "task-master-ai-algae": {
      "command": "npx",
      "args": ["task-master-ai-algae"]
    }
  }
}

重要：替换 /full/path/to/task-master-ai-algae/server.js 安装的实际绝对路径。

步骤3：示例完整配置

如果您有其他MCP服务器，您的完整配置可能如下：

{
  "mcpServers": {
    "task-master-ai-algae": {
      "command": "node",
      "args": ["/Users/username/projects/task-master-ai-algae/server.js"]
    },
    "other-mcp-server": {
      "command": "node",
      "args": ["/path/to/other/server.js"]
    }
  }
}

步骤4:重新启动克劳德桌面

更新配置后：

1. 完全退出克劳德桌面 （不要只是关上窗户）
2. 重新启动克劳德桌面
3. 等待初始化 （可能需要几秒钟）

步骤5：验证安装

在Claude Desktop中，尝试说：

Initialize a Task Master project in /path/to/my/project

如果成功，您应该看到正在创建Task Master目录结构。

用法

独立运行MCP服务器（用于测试）

node server.js

与Claude Desktop一起使用

配置后，您可以直接在Claude Desktop中使用任务主控工具，方法是要求Claude：

• 初始化项目：“在我的项目/path/to/project中初始化任务主控”
• 得到帮助：“有哪些任务主控工具可用？”
• 使用工具：“使用init工具在我当前的项目中设置Task Master”

使用工具

初始化

初始化一个完整的任务主控项目：

• 创建 .taskmaster/ 目录结构（任务、文档、报告、模板）
• 设置Roo Code集成 .roomodes 6种特殊模式的规则文件
• 创建基本配置文件和模板
• 将任务主条目添加到 .gitignore

用法：提供 projectRoot 参数中包含项目目录的绝对路径。

示例：“使用带有projectRoot'/Users/username/myproject'的init工具设置Task Master”

添加新工具

分步指南

1. 创建工具文件 在……里面 src/tools/:

   // src/tools/my-new-tool.js
   import { z } from 'zod';
   import logger from '../logger.js';

   function createContentResponse(content) {
     return {
       content: [{ type: 'text', text: typeof content === 'object' ? JSON.stringify(content, null, 2) : String(content) }]
     };
   }

   function createErrorResponse(errorMessage) {
     return {
       content: [{ type: 'text', text: `Error: ${errorMessage}` }],
       isError: true
     };
   }

   export function registerMyNewTool(server) {
     server.addTool({
       name: 'my_new_tool',
       description: 'Description of what this tool does',
       parameters: z.object({
         param1: z.string().describe('Description of parameter'),
         param2: z.number().optional().describe('Optional parameter')
       }),
       execute: async (args) => {
         try {
           logger.info(`Executing my_new_tool with args: ${JSON.stringify(args)}`);
           
           // Your tool logic here
           const result = { success: true, data: 'some result' };
           
           logger.info('Tool executed successfully');
           return createContentResponse(result);
         } catch (error) {
           logger.error(`Tool failed: ${error.message}`, { error: error.stack, args });
           return createErrorResponse(`Tool failed: ${error.message}`);
         }
       }
     });
   }

1. 注册该工具 在……里面 src/tools/index.js:

   import { registerMyNewTool } from './my-new-tool.js';

   export function registerTaskMasterTools(server) {
     try {
       registerInitTool(server);
       registerMyNewTool(server); // Add this line
       
       logger.info('Task Master tools registered successfully');
     } catch (error) {
       logger.error(`Error registering Task Master tools: ${error.message}`, { error: error.stack });
       throw error;
     }
   }

1. 重新启动克劳德桌面 拿起新工具

关键要求

✅ 必须做

• 使用正确的MCP响应格式：始终返回 createContentResponse() 或 createErrorResponse()
• 记录所有内容：永远不要使用文件记录器 console.log 或 console.error
• 验证参数：使用Zod模式进行参数验证
• 优雅地处理错误：将execute函数包装在try-catch中
• 使用绝对路径：处理文件时，始终使用绝对路径

❌ 关键陷阱

1. 切勿使用console.log/console.error：这会中断MCP stdio通信，并导致Claude Desktop中的JSON解析错误

1. 响应格式错误：不要返回普通对象。这会导致架构验证错误：

   // ❌ Wrong - causes "Unexpected token" errors
   return { success: true, message: "Done" };

   // ✅ Correct - proper MCP format
   return createContentResponse({ success: true, message: "Done" });

1. 缺少错误处理：未处理的异常导致MCP服务器崩溃：

   // ❌ Wrong - no error handling
   execute: async (args) => {
     const result = fs.readFileSync(args.file); // Could throw
     return createContentResponse(result);
   }

   // ✅ Correct - wrapped in try-catch
   execute: async (args) => {
     try {
       const result = fs.readFileSync(args.file);
       return createContentResponse(result);
     } catch (error) {
       logger.error(`Failed: ${error.message}`);
       return createErrorResponse(`Failed: ${error.message}`);
     }
   }

1. 工具名称冲突：使用现有工具名称会导致冲突。使用唯一的描述性名称。

1. 缺少参数验证：始终为参数定义Zod模式，以防止运行时错误。

1. 忘记重新启动Claude Desktop：代码更改需要重新启动Claude Desktop才能生效。

故障排除

常见问题

MCP服务器未加载

• 检查日志：Claude桌面日志通常位于 ~/Library/Logs/Claude/ 在 macOS 上
• 检查MCP服务器日志：服务器日志将写入 logs/task-master-mcp.log 在项目目录中
• 验证路径：确保server.js文件存在并且可执行
• 手动测试：您可以通过运行以下命令手动测试服务器 node server.js 在项目目录中

架构验证错误

• 通常是由错误的响应格式引起的，请确保您正在使用 createContentResponse()
• 检查是否使用Zod模式正确验证了所有参数

JSON解析错误

• 通常由console.log输出引起-确保您仅使用文件记录器
• 确保没有工具输出到stdout/stderr

工具不可用

• 确保配置更改后完全重新启动Claude Desktop
• 检查配置文件语法是否为有效的JSON
• 验证server.js的绝对路径是否正确

调试步骤

1. 独立测试服务器:

   cd /path/to/task-master-ai-algae
   node server.js

1. 检查Claude桌面配置:

   # On macOS
   cat "~/Library/Application Support/Claude/claude_desktop_config.json"

1. 查看日志:

   tail -f logs/task-master-mcp.log

项目结构

task-master-ai-algae/
├── package.json
├── server.js                 # Entry point
├── src/
│   ├── index.js             # Main server class
│   ├── logger.js            # File-based logger
│   └── tools/
│       ├── index.js         # Tool registration
│       └── init.js          # Enhanced init tool
├── logs/                    # Generated log files
│   └── task-master-mcp.log
├── TASK_MASTER_TOOLS_DOCUMENTATION.md  # Complete tools reference
├── PRD_DISCIPLINE_FRAMEWORK.md         # PRD best practices
├── IMPLEMENTATION_REPORT.md            # Implementation details
└── README.md

Init工具创建什么

当你运行init工具时，它会在你的项目中创建以下结构：

your-project/
├── .taskmaster/
│   ├── config.json          # Basic project configuration
│   ├── tasks/
│   │   └── tasks.json       # Empty tasks file
│   ├── docs/                # For PRD and documentation
│   ├── reports/             # For complexity and other reports
│   └── templates/
│       └── example_prd.txt  # PRD template
├── .roomodes                # Roo Code mode definitions
├── .roo/
│   ├── rules-architect/
│   │   └── architect-rules
│   ├── rules-ask/
│   │   └── ask-rules
│   ├── rules-boomerang/
│   │   └── boomerang-rules
│   ├── rules-code/
│   │   └── code-rules
│   ├── rules-debug/
│   │   └── debug-rules
│   └── rules-test/
│       └── test-rules
└── .gitignore (updated)     # Adds Task Master entries

相关文件

• 完整的工具文档 -所有31个任务主控工具的综合参考
• PRD最佳实践 -撰写有效PRD的指南
• 实施报告 -技术实施细节

仓库

• GitHub: https://github.com/algae514/task-master-ai-algae
• 问题：在GitHub上报告问题或请求功能

许可证

麻省理工学院