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);
  }