MCP SysOperator

Instructions

Implementation Reference

• src/sysoperator/operations/aws.ts:434-514 (handler)

  The main handler function for the 'aws_cloudformation' tool. It generates an Ansible playbook based on the action (list, create, update, delete) and parameters, handles template files, and executes the playbook using executeAwsPlaybook.

  export async function cloudFormationOperations(args: CloudFormationOptions): Promise<string> {
    await verifyAwsCredentials();
  
    const { action, region, stackName, templateBody, templateUrl, parameters, capabilities, tags } = args;
  
    const tempFiles: { filename: string, content: string }[] = [];
    let templateParam = '';
  
    if (templateBody) {
      // Prepare template body to be written to a temp file
      tempFiles.push({ filename: 'template.cfn', content: templateBody });
      templateParam = 'template: "template.cfn"'; // Reference the temp file name
    } else if (templateUrl) {
      templateParam = `template_url: "${templateUrl}"`;
    } else if (action === 'create' || action === 'update') {
      // Template is required for create/update
      throw new AnsibleError('Either templateBody or templateUrl must be provided for CloudFormation create/update actions.');
    }
  
    let playbookContent = `---
  - name: AWS CloudFormation ${action} operation
    hosts: localhost
    connection: local
    gather_facts: no
    tasks:`;
    
    switch (action) {
      case 'list':
        playbookContent += `
      - name: List CloudFormation stacks
        amazon.aws.cloudformation_info:
          region: "${region}"
        register: cfn_info
      
      - name: Display stacks
        debug:
          var: cfn_info.stacks`;
        break;
        
      case 'create':
      case 'update':
        playbookContent += `
      - name: ${action === 'create' ? 'Create' : 'Update'} CloudFormation stack
        amazon.aws.cloudformation:
          region: "${region}"
          stack_name: "${stackName}"
          state: present
          ${templateParam} # Use the determined template parameter
  ${formatYamlParams({
    template_parameters: parameters,
    capabilities,
    tags
  })}
        register: cfn_result
      
      - name: Display stack outputs/result
        debug:
          var: cfn_result`;
        break;
        
      case 'delete':
        playbookContent += `
      - name: Delete CloudFormation stack
        amazon.aws.cloudformation:
          region: "${region}"
          stack_name: "${stackName}"
          state: absent
        register: cfn_delete
        
      - name: Display deletion result
        debug:
          var: cfn_delete`;
        break;
        
      default:
        throw new AnsibleError(`Unsupported CloudFormation action: ${action}`);
    }
    
    // Execute the generated playbook, passing template body if needed
    return executeAwsPlaybook(`cloudformation-${action}`, playbookContent, '', tempFiles);
  }

• src/sysoperator/index.ts:106-110 (registration)

  Registration of the 'aws_cloudformation' tool in the toolDefinitions map, linking its description, input schema, and handler function.

  aws_cloudformation: {
    description: 'Manage AWS CloudFormation stacks',
    schema: aws.CloudFormationSchema,
    handler: aws.cloudFormationOperations,
  },

• src/sysoperator/common/types.ts:89-100 (schema)

  Zod schema defining the input validation for the 'aws_cloudformation' tool, including action enum, required region, and optional parameters like stackName, templateBody, etc.

  export const CloudFormationSchema = z.object({
    action: CloudFormationActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    stackName: z.string().optional(),
    templateBody: z.string().optional(),
    templateUrl: z.string().optional(),
    parameters: z.record(z.any()).optional(),
    capabilities: z.array(z.string()).optional(),
    tags: z.record(z.string()).optional()
  });
  
  export type CloudFormationOptions = z.infer<typeof CloudFormationSchema>;

• src/sysoperator/common/types.ts:17-18 (schema)

  Zod enum defining the supported actions for the 'aws_cloudformation' tool: list, create, update, delete.

  export const CloudFormationActionEnum = z.enum(['list', 'create', 'update', 'delete']);
  export type CloudFormationAction = z.infer<typeof CloudFormationActionEnum>;

• src/sysoperator/operations/aws.ts:77-116 (helper)

  Helper function used by the handler to execute dynamically generated Ansible playbooks for AWS operations, handling temporary files and directories.

  async function executeAwsPlaybook(
    operationName: string, 
    playbookContent: string, 
    extraParams: string = '',
    tempFiles: { filename: string, content: string }[] = [] // For additional files like templates, policies
  ): Promise<string> {
    let tempDir: string | undefined;
    try {
      // Create a unique temporary directory
      tempDir = await createTempDirectory(`ansible-aws-${operationName}`);
      
      // Write the main playbook file
      const playbookPath = await writeTempFile(tempDir, 'playbook.yml', playbookContent);
      
      // Write any additional temporary files
      for (const file of tempFiles) {
        await writeTempFile(tempDir, file.filename, file.content);
      }
  
      // Build the command
      const command = `ansible-playbook ${playbookPath} ${extraParams}`;
      console.error(`Executing: ${command}`);
  
      // Execute the playbook asynchronously
      const { stdout, stderr } = await execAsync(command);
      
      // Return stdout, or a success message if stdout is empty
      return stdout || `${operationName} completed successfully (no output).`;
  
    } catch (error: any) {
      // Handle execution errors
      const errorMessage = error.stderr || error.message || 'Unknown error';
      throw new AnsibleExecutionError(`Ansible execution failed for ${operationName}: ${errorMessage}`, error.stderr);
    } finally {
      // Ensure cleanup happens even if errors occur
      if (tempDir) {
        await cleanupTempDirectory(tempDir);
      }
    }
  }