chore: adds changeset.mdc to help agent automatically trigger changeset command with contextual information based on how we want to use it. not to be called for internal dev stuff.

.cursor/rules/new_features.mdc

@@ -312,48 +312,59 @@ For more information on module structure, see [`MODULE_PLAN.md`](mdc:scripts/mod
 
 ## Adding MCP Server Support for Commands
 
-Integrating Task Master commands with the MCP server (for use by tools like Cursor) follows a specific pattern distinct from the CLI command implementation.
+Integrating Task Master commands with the MCP server (for use by tools like Cursor) follows a specific pattern distinct from the CLI command implementation, prioritizing performance and reliability.
 
-- **Goal**: Leverage direct function calls for performance and reliability, avoiding CLI overhead.
+- **Goal**: Leverage direct function calls to core logic, avoiding CLI overhead.
 - **Reference**: See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for full details.
 
 **MCP Integration Workflow**:
 
-1.  **Core Logic**: Ensure the command's core logic exists in the appropriate module (e.g., [`task-manager.js`](mdc:scripts/modules/task-manager.js)).
-2.  **Direct Function Wrapper**:
-    - In [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js), create an `async function yourCommandDirect(args, log)`.
-    - This function imports and calls the core logic.
-    - It uses utilities like `findTasksJsonPath` if needed.
-    - It handles argument parsing and validation specific to the direct call.
-    - **Implement Caching (if applicable)**: For read operations that benefit from caching, use the `getCachedOrExecute` utility here to wrap the core logic call. Generate a unique cache key based on relevant arguments.
-    - It returns a standard `{ success: true/false, data/error, fromCache: boolean }` object.
-    - Export the function and add it to the `directFunctions` map.
-3.  **MCP Tool File**:
-    - Create a new file in `mcp-server/src/tools/` (e.g., `yourCommand.js`).
-    - Import `zod`, `executeMCPToolAction` from `./utils.js`, and your `yourCommandDirect` function.
-    - Implement `registerYourCommandTool(server)` which calls `server.addTool`:
-        - Define the tool `name`, `description`, and `parameters` using `zod`. Include optional `projectRoot` and `file` if relevant, following patterns in existing tools.
-        - Define the `async execute(args, log)` method for the tool.
-        - **Crucially**, the `execute` method should primarily call `executeMCPToolAction`:
-          ```javascript
-          // In mcp-server/src/tools/yourCommand.js
-          import { executeMCPToolAction } from "./utils.js";
-          import { yourCommandDirect } from "../core/task-master-core.js";
-          import { z } from "zod";
-
-          export function registerYourCommandTool(server) {
-            server.addTool({
-              name: "yourCommand",
-              description: "Description of your command.",
-              parameters: z.object({ /* zod schema */ }),
-              async execute(args, log) {
-                return executeMCPToolAction({
-                  actionFn: yourCommandDirect, // Pass the direct function wrapper
-                  args, log, actionName: "Your Command Description"
-                });
-              }
-            });
+1.  **Core Logic**: Ensure the command's core logic exists and is exported from the appropriate module (e.g., [`task-manager.js`](mdc:scripts/modules/task-manager.js)).
+2.  **Direct Function 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).
+    - This function imports and calls the core logic function.
+    - It handles argument parsing, path resolution (e.g., using `findTasksJsonPath`), and validation specific to the direct call.
+    - **Implement Caching (if applicable)**:
+        - **Use Case**: Apply caching primarily for read-only operations that benefit from repeated calls (e.g., `listTasks`, `showTask`, `nextTask`). Avoid caching for operations that modify state (`setTaskStatus`, `addTask`, `parsePRD`, `updateTask`, `addDependency`, etc.).
+        - **Implementation**: Inside the `yourCommandDirect` function, use the `getCachedOrExecute` utility (imported from `../tools/utils.js`).
+            - Generate a unique `cacheKey` based on relevant arguments (e.g., file path, filters).
+            - Define an `async` function `coreActionFn` that wraps the actual call to the core logic and returns `{ success: true/false, data/error }`.
+            - Call `await getCachedOrExecute({ cacheKey, actionFn: coreActionFn, log });`.
+    - The `yourCommandDirect` function must return a standard object: `{ success: true/false, data/error, fromCache: boolean }`. For non-cached operations, `fromCache` should be `false`.
+    - Export the function and add it to the `directFunctions` map in `task-master-core.js`.
+3.  **MCP Tool File (`mcp-server/src/tools/`)**:
+    - Create a new file (e.g., `yourCommand.js`).
+    - Import `zod` (for schema), `handleApiResult`, `createErrorResponse` from `./utils.js`, and your `yourCommandDirect` function from `../core/task-master-core.js`.
+    - Implement `registerYourCommandTool(server)` which calls `server.addTool`.
+    - Define the tool's `name`, `description`, and `parameters` using `zod`.
+    - Define the `async execute(args, log)` method. **This is the standard pattern**:
+      ```javascript
+      // In mcp-server/src/tools/yourCommand.js
+      import { z } from "zod";
+      import { handleApiResult, createErrorResponse } from "./utils.js";
+      import { yourCommandDirect } from "../core/task-master-core.js";
+      
+      export function registerYourCommandTool(server) {
+        server.addTool({
+          name: "yourCommand",
+          description: "Description of your command.",
+          parameters: z.object({ /* zod schema, include projectRoot, file if needed */ }),
+          async execute(args, log) {
+            try {
+              log.info(`Executing Your Command with args: ${JSON.stringify(args)}`);
+              // 1. Call the direct function wrapper
+              const result = await yourCommandDirect(args, log);
+              
+              // 2. Pass the result to handleApiResult for formatting
+              return handleApiResult(result, log, 'Error during Your Command');
+            } catch (error) {
+              // Catch unexpected errors from the direct call itself
+              log.error(`Unexpected error in tool execute: ${error.message}`);
+              return createErrorResponse(`Tool execution failed: ${error.message}`); 
+            }
           }
-          ```
+        });
+      }
+      ```
 4.  **Register in Tool Index**: Import and call `registerYourCommandTool` in [`mcp-server/src/tools/index.js`](mdc:mcp-server/src/tools/index.js).
 5.  **Update `mcp.json`**: Add the tool definition to `.cursor/mcp.json`.