Instructions

Implementation Reference

• src/tools/approvals.ts:122-187 (handler)

  Primary handler function for the 'approvals' MCP tool. Dispatches to sub-handlers based on the 'action' parameter (request, status, delete). Includes input validation and type guards.
  export async function approvalsHandler( args: { action: 'request' | 'status' | 'delete'; projectPath?: string; approvalId?: string; title?: string; filePath?: string; type?: 'document' | 'action'; category?: 'spec' | 'steering'; categoryName?: string; }, context: ToolContext ): Promise<ToolResponse> { // Cast to discriminated union type const typedArgs = args as ApprovalArgs; switch (typedArgs.action) { case 'request': if (isRequestApproval(typedArgs)) { // Validate required fields for request if (!args.title || !args.filePath || !args.type || !args.category || !args.categoryName) { return { success: false, message: 'Missing required fields for request action. Required: title, filePath, type, category, categoryName' }; } return handleRequestApproval(typedArgs, context); } break; case 'status': if (isStatusApproval(typedArgs)) { // Validate required fields for status if (!args.approvalId) { return { success: false, message: 'Missing required field for status action. Required: approvalId' }; } return handleGetApprovalStatus(typedArgs, context); } break; case 'delete': if (isDeleteApproval(typedArgs)) { // Validate required fields for delete if (!args.approvalId) { return { success: false, message: 'Missing required field for delete action. Required: approvalId' }; } return handleDeleteApproval(typedArgs, context); } break; default: return { success: false, message: `Unknown action: ${(args as any).action}. Use 'request', 'status', or 'delete'.` }; } // This should never be reached due to exhaustive type checking return { success: false, message: 'Invalid action configuration' }; }
• src/tools/approvals.ts:30-82 (schema)

  Tool definition including name, description, and detailed inputSchema for validation.
  export const approvalsTool: Tool = { name: 'approvals', description: `Manage approval requests through the dashboard interface. # Instructions Use this tool to request, check status, or delete approval requests. The action parameter determines the operation: - 'request': Create a new approval request after creating each document - 'status': Check the current status of an approval request - 'delete': Clean up completed, rejected, or needs-revision approval requests (cannot delete pending requests) CRITICAL: Only provide filePath parameter for requests - the dashboard reads files directly. Never include document content. Wait for user to review and approve before continuing.`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['request', 'status', 'delete'], description: 'The action to perform: request, status, or delete' }, projectPath: { type: 'string', description: 'Absolute path to the project root (optional - uses server context path if not provided)' }, approvalId: { type: 'string', description: 'The ID of the approval request (required for status and delete actions)' }, title: { type: 'string', description: 'Brief title describing what needs approval (required for request action)' }, filePath: { type: 'string', description: 'Path to the file that needs approval, relative to project root (required for request action)' }, type: { type: 'string', enum: ['document', 'action'], description: 'Type of approval request - "document" for content approval, "action" for action approval (required for request)' }, category: { type: 'string', enum: ['spec', 'steering'], description: 'Category of the approval request - "spec" for specifications, "steering" for steering documents (required for request)' }, categoryName: { type: 'string', description: 'Name of the spec or "steering" for steering documents (required for request)' } }, required: ['action'] } };
• src/tools/index.ts:9-17 (registration)

  Central tool registration function that includes the 'approvalsTool' in the MCP tools list.
  export function registerTools(): Tool[] { return [ specWorkflowGuideTool, steeringGuideTool, specStatusTool, approvalsTool, logImplementationTool ]; }
• src/tools/index.ts:34-36 (registration)

  Dispatcher switch case that routes 'approvals' tool calls to the specific approvalsHandler.
  case 'approvals': response = await approvalsHandler(args, context); break;
• src/tools/approvals.ts:17-28 (helper)

  Utility function for safely translating paths, with defensive checks for module loading issues.
  function safeTranslatePath(path: string): string { // Defensive check: ensure translatePath method exists and is callable // This handles edge cases where the class might be partially initialized if (typeof PathUtils?.translatePath !== 'function') { throw new Error( `PathUtils.translatePath is not available (got ${typeof PathUtils?.translatePath}). ` + 'This may indicate a module loading issue. Please reinstall the package with: ' + 'npm uninstall @pimzino/spec-workflow-mcp && npm install @pimzino/spec-workflow-mcp' ); } return PathUtils.translatePath(path); }