docs: document MCP server naming conventions and implement set-status
- Update architecture.mdc with file/function naming standards for MCP server components - Update mcp.mdc with detailed naming conventions section - Update task 23 to include naming convention details - Update changeset to capture documentation changes - Rename MCP tool files to follow kebab-case convention - Implement set-task-status MCP command
This commit is contained in:
Eyal Toledano
@@ -46,50 +46,38 @@ The MCP server acts as a bridge between external tools (like Cursor) and the cor
|
||||
Follow these steps to add MCP support for an existing Task Master command (see [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for more detail):
|
||||
|
||||
1. **Ensure Core Logic Exists**: Verify the core functionality is implemented and exported from the relevant module in `scripts/modules/`.
|
||||
2. **Create Direct Wrapper (`task-master-core.js`)**:
|
||||
- Create an `async function yourCommandDirect(args, log)` in [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js).
|
||||
- Inside the wrapper:
|
||||
- Import necessary core functions and utilities (`findTasksJsonPath`, `getCachedOrExecute` if caching).
|
||||
|
||||
2. **Create Direct Function File in `mcp-server/src/core/direct-functions/`**:
|
||||
- Create a new file (e.g., `your-command.js`) in the `direct-functions` directory using **kebab-case** for file naming.
|
||||
- Import necessary core functions from Task Master modules (e.g., `../../../../scripts/modules/task-manager.js`).
|
||||
- Import utilities: `findTasksJsonPath` from `../utils/path-utils.js` and `getCachedOrExecute` from `../../tools/utils.js` if needed.
|
||||
- Implement `async function yourCommandDirect(args, log)` using **camelCase** with `Direct` suffix:
|
||||
- Parse `args` and determine necessary inputs (e.g., `tasksPath` via `findTasksJsonPath`).
|
||||
- **If Caching**:
|
||||
- Generate a unique `cacheKey` based on arguments defining the operation.
|
||||
- Define an `async` function `coreActionFn` containing the actual call to the core logic, formatting its return as `{ success: true/false, data/error }`.
|
||||
- Define an `async` function `coreActionFn` containing the call to the core logic.
|
||||
- Call `const result = await getCachedOrExecute({ cacheKey, actionFn: coreActionFn, log });`.
|
||||
- `return result;` (which includes the `fromCache` flag).
|
||||
- **If Not Caching**:
|
||||
- Directly call the core logic function within a try/catch block.
|
||||
- Format the return as `{ success: true/false, data/error, fromCache: false }`.
|
||||
- Export the wrapper function and add it to the `directFunctions` map.
|
||||
3. **Create MCP Tool (`mcp-server/src/tools/`)**:
|
||||
- Create a new file (e.g., `yourCommand.js`).
|
||||
- Format the return as `{ success: true/false, data/error, fromCache: boolean }`.
|
||||
- Export the wrapper function.
|
||||
|
||||
3. **Update `task-master-core.js` with Import/Export**:
|
||||
- Import your direct function: `import { yourCommandDirect } from './direct-functions/your-command.js';`
|
||||
- Re-export it in the exports section.
|
||||
- Add it to the `directFunctions` map: `yourCommand: yourCommandDirect`.
|
||||
|
||||
4. **Create MCP Tool (`mcp-server/src/tools/`)**:
|
||||
- Create a new file (e.g., `your-command.js`) using **kebab-case**.
|
||||
- Import `z` for schema definition.
|
||||
- Import `handleApiResult` from [`./utils.js`](mdc:mcp-server/src/tools/utils.js).
|
||||
- Import `handleApiResult` from `./utils.js`.
|
||||
- Import the `yourCommandDirect` wrapper function from `../core/task-master-core.js`.
|
||||
- Implement `registerYourCommandTool(server)`:
|
||||
- Call `server.addTool`.
|
||||
- Define `name`, `description`, and `parameters` using `zod` (include optional `projectRoot`, `file` if needed).
|
||||
- Define the `async execute(args, log)` function:
|
||||
```javascript
|
||||
async execute(args, log) {
|
||||
try {
|
||||
log.info(`Executing Your Command with args: ${JSON.stringify(args)}`);
|
||||
// Call the direct function wrapper
|
||||
const result = await yourCommandDirect(args, log);
|
||||
|
||||
// Let handleApiResult format the final MCP response
|
||||
return handleApiResult(result, log, 'Error during Your Command');
|
||||
// Optionally pass a custom processor to handleApiResult if default filtering isn't sufficient:
|
||||
// return handleApiResult(result, log, 'Error...', customDataProcessor);
|
||||
} catch (error) {
|
||||
// Catch unexpected errors during the direct call itself
|
||||
log.error(`Unexpected error in tool execute: ${error.message}`);
|
||||
// Use createErrorResponse for unexpected errors
|
||||
return createErrorResponse(`Tool execution failed: ${error.message}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
4. **Register Tool**: Import and call `registerYourCommandTool` in [`mcp-server/src/tools/index.js`](mdc:mcp-server/src/tools/index.js).
|
||||
5. **Update `mcp.json`**: Add the new tool definition to the `tools` array in `.cursor/mcp.json`.
|
||||
- Implement `registerYourCommandTool(server)` using **camelCase** with `Tool` suffix.
|
||||
- Define the tool `name` using **snake_case** (e.g., `your_command`).
|
||||
|
||||
5. **Register Tool**: Import and call `registerYourCommandTool` in `mcp-server/src/tools/index.js`.
|
||||
|
||||
6. **Update `mcp.json`**: Add the new tool definition to the `tools` array in `.cursor/mcp.json`.
|
||||
|
||||
## Handling Responses
|
||||
|
||||
@@ -185,3 +173,34 @@ Follow these steps to add MCP support for an existing Task Master command (see [
|
||||
- Centralized error handling
|
||||
- Performance optimization through caching (for read operations)
|
||||
- Standardized response formatting
|
||||
|
||||
## MCP Naming Conventions
|
||||
|
||||
- **Files and Directories**:
|
||||
- ✅ DO: Use **kebab-case** for all file names: `list-tasks.js`, `set-task-status.js`
|
||||
- ✅ DO: Use consistent directory structure: `mcp-server/src/tools/` for tool definitions, `mcp-server/src/core/direct-functions/` for direct function implementations
|
||||
|
||||
- **JavaScript Functions**:
|
||||
- ✅ DO: Use **camelCase** with `Direct` suffix for direct function implementations: `listTasksDirect`, `setTaskStatusDirect`
|
||||
- ✅ DO: Use **camelCase** with `Tool` suffix for tool registration functions: `registerListTasksTool`, `registerSetTaskStatusTool`
|
||||
- ✅ DO: Use consistent action function naming inside direct functions: `coreActionFn` or similar descriptive name
|
||||
|
||||
- **MCP Tool Names**:
|
||||
- ✅ DO: Use **snake_case** for tool names exposed to MCP clients: `list_tasks`, `set_task_status`, `parse_prd_document`
|
||||
- ✅ DO: Include the core action in the tool name without redundant words: Use `list_tasks` instead of `list_all_tasks`
|
||||
|
||||
- **Examples**:
|
||||
- File: `list-tasks.js`
|
||||
- Direct Function: `listTasksDirect`
|
||||
- Tool Registration: `registerListTasksTool`
|
||||
- MCP Tool Name: `list_tasks`
|
||||
|
||||
- **Mapping**:
|
||||
- The `directFunctions` map in `task-master-core.js` maps the core function name (in camelCase) to its direct implementation:
|
||||
```javascript
|
||||
export const directFunctions = {
|
||||
list: listTasksDirect,
|
||||
setStatus: setTaskStatusDirect,
|
||||
// Add more functions as implemented
|
||||
};
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user