Taskmaster

# Task Master MCP Integration This document outlines how Task Master CLI functionality is integrated with MCP (Master Control Program) architecture to provide both CLI and programmatic API access to features. ## Architecture Overview The MCP integration uses a layered approach: 1. **Core Functions** - In `scripts/modules/` contain the main business logic 2. **Source Parameter** - Core functions check the `source` parameter to determine behavior 3. **Task Master Core** - In `mcp-server/src/core/task-master-core.js` provides direct function imports 4. **MCP Tools** - In `mcp-server/src/tools/` register the functions with the MCP server ``` ┌─────────────────┐ ┌─────────────────┐ │ CLI User │ │ MCP User │ └────────┬────────┘ └────────┬────────┘ │ │ ▼ ▼ ┌────────────────┐ ┌────────────────────┐ │ commands.js │ │ MCP Tool API │ └────────┬───────┘ └──────────┬─────────┘ │ │ │ │ ▼ ▼ ┌───────────────────────────────────────────────┐ │ │ │ Core Modules (task-manager.js, etc.) │ │ │ └───────────────────────────────────────────────┘ ``` ## Core Function Pattern Core functions should follow this pattern to support both CLI and MCP use: ```javascript /** * 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); } } ``` ## Source-Adapter Utilities For convenience, you can use the source adapter helpers in `scripts/modules/source-adapter.js`: ```javascript import { adaptForMcp, sourceSplitFunction } from './source-adapter.js'; // Simple adaptation - just adds source parameter support export const simpleFunction = adaptForMcp(originalFunction); // Split implementation - completely different code paths for CLI vs MCP export const complexFunction = sourceSplitFunction( // CLI version with UI function (param1, param2) { displayBanner(); console.log(`Processing ${param1}...`); // ... CLI implementation }, // MCP version with structured return function (param1, param2, options = {}) { // ... MCP implementation return { success: true, data }; } ); ``` ## Adding New Features When adding new features, follow these steps to ensure CLI and MCP compatibility: 1. **Implement Core Logic** in the appropriate module file 2. **Add Source Parameter Support** using the pattern above 3. **Add to task-master-core.js** to make it available for direct import 4. **Update Command Map** in `mcp-server/src/tools/utils.js` 5. **Create Tool Implementation** in `mcp-server/src/tools/` 6. **Register the Tool** in `mcp-server/src/tools/index.js` ### Core Function Implementation ```javascript // 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); } } ``` ### Task Master Core Update ```javascript // 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); } }; ``` ### Command Map Update ```javascript // In mcp-server/src/tools/utils.js const commandMap = { // ... existing mappings 'new-feature': 'newFeature' }; ``` ### Tool Implementation ```javascript // 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}`); } } }); } ``` ### Tool Registration ```javascript // In mcp-server/src/tools/index.js import { registerNewFeatureTool } from './newFeature.js'; export function registerTaskMasterTools(server) { // ... existing registrations registerNewFeatureTool(server); } ``` ## Testing Always test your MCP-compatible features with both CLI and MCP interfaces: ```javascript // Test CLI usage node scripts/dev.js new-feature --param1=test --param2=123 // Test MCP usage node mcp-server/tests/test-command.js newFeature ``` ## Best Practices 1. **Keep Core Logic DRY** - Share as much logic as possible between CLI and MCP 2. **Structured Data for MCP** - Return clean JSON objects from MCP source functions 3. **Consistent Error Handling** - Standardize error formats for both interfaces 4. **Documentation** - Update MCP tool documentation when adding new features 5. **Testing** - Test both CLI and MCP interfaces for any new or modified feature