MCP SysOperator

Instructions

Implementation Reference

• src/sysoperator/operations/aws.ts:122-225 (handler)

  Main handler function that destructures input args, generates an Ansible playbook YAML based on the 'action' (list, create, terminate, start, stop), and executes it via executeAwsPlaybook helper.

  export async function ec2InstanceOperations(args: EC2InstanceOptions): Promise<string> {
    await verifyAwsCredentials();
  
    const { action, region, instanceIds, filters, instanceType, imageId, keyName, securityGroups, userData, count, tags, waitForCompletion, terminationProtection, ...restParams } = args;
  
    let playbookContent = `---
  - name: AWS EC2 ${action} operation
    hosts: localhost
    connection: local
    gather_facts: no
    tasks:`;
    
    switch (action) {
      case 'list':
        playbookContent += `
      - name: List EC2 instances
        amazon.aws.ec2_instance_info:
          region: "${region}"
  ${filters ? formatYamlParams({ filters }) : ''}
        register: ec2_info
      
      - name: Display instances
        debug:
          var: ec2_info.instances`;
        break;
        
      case 'create':
        playbookContent += `
      - name: Create EC2 instance
        amazon.aws.ec2_instance:
          region: "${region}"
          state: present
          instance_type: "${instanceType}"
          image_id: "${imageId}"
  ${formatYamlParams({
    key_name: keyName,
    security_groups: securityGroups,
    user_data: userData,
    exact_count: count,
    tags: tags,
    wait: waitForCompletion,
    termination_protection: terminationProtection,
    ...restParams
  })}
        register: ec2_create
      
      - name: Display created instance details
        debug:
          var: ec2_create`;
        break;
        
      case 'terminate':
        playbookContent += `
      - name: Terminate EC2 instances
        amazon.aws.ec2_instance:
          region: "${region}"
          instance_ids: ${JSON.stringify(instanceIds)}
          state: absent
          wait: ${waitForCompletion ? 'yes' : 'no'}
        register: ec2_terminate
        
      - name: Display termination result
        debug:
          var: ec2_terminate`;
        break;
        
      case 'start':
        playbookContent += `
      - name: Start EC2 instances
        amazon.aws.ec2_instance:
          region: "${region}"
          instance_ids: ${JSON.stringify(instanceIds)}
          state: running
          wait: ${waitForCompletion ? 'yes' : 'no'}
        register: ec2_start
        
      - name: Display start result
        debug:
          var: ec2_start`;
        break;
        
      case 'stop':
        playbookContent += `
      - name: Stop EC2 instances
        amazon.aws.ec2_instance:
          region: "${region}"
          instance_ids: ${JSON.stringify(instanceIds)}
          state: stopped
          wait: ${waitForCompletion ? 'yes' : 'no'}
        register: ec2_stop
        
      - name: Display stop result
        debug:
          var: ec2_stop`;
        break;
        
      default:
        // Should be caught by Zod validation, but good to have a fallback
        throw new AnsibleError(`Unsupported EC2 action: ${action}`);
    }
    
    // Execute the generated playbook
    return executeAwsPlaybook(`ec2-${action}`, playbookContent);
  }

• src/sysoperator/common/types.ts:36-50 (schema)

  Zod input schema for aws_ec2 tool, defining required 'action' and 'region', and optional parameters for EC2 operations.

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

• src/sysoperator/index.ts:91-95 (registration)

  Registration of the aws_ec2 tool in the toolDefinitions map, linking to its description, Zod schema, and handler function.

  aws_ec2: {
    description: 'Manage AWS EC2 instances (list, create, start, stop, terminate)',
    schema: aws.EC2InstanceSchema,
    handler: aws.ec2InstanceOperations,
  },

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

  Helper function used by AWS tool handlers to execute dynamically generated Ansible playbooks in temporary 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);
      }
    }
  }

• src/sysoperator/common/types.ts:8-9 (schema)

  Zod enum defining valid actions for the aws_ec2 tool.

  export const EC2InstanceActionEnum = z.enum(['list', 'create', 'terminate', 'start', 'stop']);
  export type EC2InstanceAction = z.infer<typeof EC2InstanceActionEnum>;