MCP SysOperator

Instructions

Implementation Reference

• src/sysoperator/operations/aws.ts:646-748 (handler)

  The rdsOperations handler function that destructures input args, dynamically generates an Ansible playbook YAML for RDS actions (list, create, delete, start, stop) using amazon.aws.rds_instance module, and executes it via executeAwsPlaybook helper.

  export async function rdsOperations(args: RDSOptions): Promise<string> {
    await verifyAwsCredentials();
  
    const { action, region, dbInstanceIdentifier, dbEngine, dbInstanceClass, allocatedStorage, masterUsername, 
      masterPassword, vpcSecurityGroupIds, dbSubnetGroupName, tags, multiAZ, backupRetentionPeriod, skipFinalSnapshot } = args;
  
    let playbookContent = `---
  - name: AWS RDS ${action} operation
    hosts: localhost
    connection: local
    gather_facts: no
    tasks:`;
    
    switch (action) {
      case 'list':
        playbookContent += `
      - name: List RDS instances
        amazon.aws.rds_instance_info:
          region: "${region}"
        register: rds_info
      
      - name: Display RDS instances
        debug:
          var: rds_info.instances`;
        break;
        
      case 'create':
        playbookContent += `
      - name: Create RDS instance
        amazon.aws.rds_instance:
          region: "${region}"
          db_instance_identifier: "${dbInstanceIdentifier}"
          engine: "${dbEngine}"
          db_instance_class: "${dbInstanceClass}"
          allocated_storage: ${allocatedStorage}
          master_username: "${masterUsername}"
          master_user_password: "${masterPassword}"
          state: present
  ${formatYamlParams({
    vpc_security_group_ids: vpcSecurityGroupIds,
    db_subnet_group_name: dbSubnetGroupName,
    tags,
    multi_az: multiAZ,
    backup_retention_period: backupRetentionPeriod,
    // Add other relevant RDS params here if needed
  })}
        register: rds_result
      
      - name: Display RDS instance details
        debug:
          var: rds_result`;
        break;
        
      case 'delete':
        playbookContent += `
      - name: Delete RDS instance
        amazon.aws.rds_instance:
          region: "${region}"
          db_instance_identifier: "${dbInstanceIdentifier}"
          state: absent
          skip_final_snapshot: ${skipFinalSnapshot ? 'yes' : 'no'}
        register: rds_delete
      
      - name: Display deletion result
        debug:
          var: rds_delete`;
        break;
        
      case 'start':
        playbookContent += `
      - name: Start RDS instance
        amazon.aws.rds_instance:
          region: "${region}"
          db_instance_identifier: "${dbInstanceIdentifier}"
          state: started
        register: rds_start
      
      - name: Display start result
        debug:
          var: rds_start`;
        break;
        
      case 'stop':
        playbookContent += `
      - name: Stop RDS instance
        amazon.aws.rds_instance:
          region: "${region}"
          db_instance_identifier: "${dbInstanceIdentifier}"
          state: stopped
        register: rds_stop
      
      - name: Display stop result
        debug:
          var: rds_stop`;
        break;
        
      default:
        throw new AnsibleError(`Unsupported RDS action: ${action}`);
    }
    
    // Execute the generated playbook
    return executeAwsPlaybook(`rds-${action}`, playbookContent);
  }

• src/sysoperator/common/types.ts:23-135 (schema)

  Zod schema definition for aws_rds tool inputs: RDSSchema validates action (enum: list/create/delete/start/stop), region (required), and optional RDS-specific params like dbInstanceIdentifier, engine, etc.

  export const RDSActionEnum = z.enum(['list', 'create', 'delete', 'start', 'stop']);
  export type RDSAction = z.infer<typeof RDSActionEnum>;
  
  export const Route53ActionEnum = z.enum(['list_zones', 'list_records', 'create_zone', 'create_record', 'delete_record', 'delete_zone']);
  export type Route53Action = z.infer<typeof Route53ActionEnum>;
  
  export const ELBActionEnum = z.enum(['list', 'create', 'delete']);
  export type ELBAction = z.infer<typeof ELBActionEnum>;
  
  export const LambdaActionEnum = z.enum(['list', 'create', 'update', 'delete', 'invoke']);
  export type LambdaAction = z.infer<typeof LambdaActionEnum>;
  
  // AWS EC2 Schema
  export const EC2InstanceSchema = z.object({
    action: EC2InstanceActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    instanceIds: z.array(z.string()).optional(),
    filters: z.record(z.any()).optional(),
    instanceType: z.string().optional(),
    imageId: z.string().optional(),
    keyName: z.string().optional(),
    securityGroups: z.array(z.string()).optional(),
    userData: z.string().optional(),
    count: z.number().optional(),
    tags: z.record(z.string()).optional(),
    waitForCompletion: z.boolean().optional().default(true),
    terminationProtection: z.boolean().optional()
  });
  
  export type EC2InstanceOptions = z.infer<typeof EC2InstanceSchema>;
  
  // AWS S3 Schema
  export const S3Schema = z.object({
    action: S3ActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    bucket: z.string().optional(),
    objectKey: z.string().optional(),
    localPath: z.string().optional(),
    acl: z.string().optional(),
    tags: z.record(z.string()).optional(),
    metadata: z.record(z.string()).optional(),
    contentType: z.string().optional()
  });
  
  export type S3Options = z.infer<typeof S3Schema>;
  
  // AWS VPC Schema
  export const VPCSchema = z.object({
    action: VPCActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    vpcId: z.string().optional(),
    cidrBlock: z.string().optional(),
    name: z.string().optional(),
    dnsSupport: z.boolean().optional(),
    dnsHostnames: z.boolean().optional(),
    tags: z.record(z.string()).optional(),
    subnets: z.array(z.object({
      cidr: z.string(),
      az: z.string().optional(),
      tags: z.record(z.string()).optional()
    })).optional()
  });
  
  export type VPCOptions = z.infer<typeof VPCSchema>;
  
  // AWS CloudFormation Schema
  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>;
  
  // AWS IAM Schema
  export const IAMSchema = z.object({
    action: IAMActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    name: z.string().optional(),
    roleName: z.string().optional(),
    policyName: z.string().optional(),
    policyDocument: z.any().optional(),
    assumeRolePolicyDocument: z.any().optional(),
    path: z.string().optional(),
    managedPolicies: z.array(z.string()).optional()
  });
  
  export type IAMOptions = z.infer<typeof IAMSchema>;
  
  // AWS RDS Schema
  export const RDSSchema = z.object({
    action: RDSActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    dbInstanceIdentifier: z.string().optional(),
    dbEngine: z.string().optional(),
    dbInstanceClass: z.string().optional(),
    allocatedStorage: z.number().optional(),
    masterUsername: z.string().optional(),
    masterPassword: z.string().optional(),
    vpcSecurityGroupIds: z.array(z.string()).optional(),
    dbSubnetGroupName: z.string().optional(),
    tags: z.record(z.string()).optional(),
    multiAZ: z.boolean().optional(),
    backupRetentionPeriod: z.number().optional(),
    skipFinalSnapshot: z.boolean().optional() // Added based on usage in aws.ts
  });
  
  export type RDSOptions = z.infer<typeof RDSSchema>;

• src/sysoperator/index.ts:116-120 (registration)

  Tool registration in toolDefinitions map: associates 'aws_rds' name with its description, input schema (aws.RDSSchema), and handler function (aws.rdsOperations).

  aws_rds: {
    description: 'Manage AWS RDS database instances',
    schema: aws.RDSSchema,
    handler: aws.rdsOperations,
  },

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

  Shared helper function executeAwsPlaybook used by all AWS tools (including rdsOperations) to create temp dir, write playbook YAML to file, execute ansible-playbook, capture output, and cleanup.

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