MCP SysOperator

Instructions

Implementation Reference

• src/sysoperator/operations/aws.ts:519-641 (handler)

  The primary handler function for the 'aws_iam' tool. It destructures input args, prepares temporary policy files if needed, dynamically generates an Ansible playbook YAML based on the specified IAM action (list_roles, list_policies, create_role, etc.), and executes it using the shared executeAwsPlaybook helper.

  export async function iamOperations(args: IAMOptions): Promise<string> {
    await verifyAwsCredentials();
  
    const { action, region, policyName, policyDocument, path, roleName, assumeRolePolicyDocument, managedPolicies } = args;
  
    const tempFiles: { filename: string, content: string }[] = [];
    let policyDocParam = '';
    let assumeRoleDocParam = '';
  
    if (policyDocument) {
      const policyFilename = 'policy.json';
      tempFiles.push({ filename: policyFilename, content: JSON.stringify(policyDocument, null, 2) });
      policyDocParam = `policy_document: "{{ lookup('file', '${policyFilename}') }}"`;
    }
  
    if (assumeRolePolicyDocument) {
      const assumeRoleFilename = 'assume_role_policy.json';
      tempFiles.push({ filename: assumeRoleFilename, content: JSON.stringify(assumeRolePolicyDocument, null, 2) });
      assumeRoleDocParam = `assume_role_policy_document: "{{ lookup('file', '${assumeRoleFilename}') }}"`;
    }
  
    let playbookContent = `---
  - name: AWS IAM ${action} operation
    hosts: localhost
    connection: local
    gather_facts: no
    tasks:`;
    
    switch (action) {
      case 'list_roles':
        playbookContent += `
      - name: List IAM roles
        amazon.aws.iam_role_info:
          region: "${region}"
        register: iam_roles
      
      - name: Display roles
        debug:
          var: iam_roles.iam_roles`;
        break;
        
      case 'list_policies':
        playbookContent += `
      - name: List IAM policies
        amazon.aws.iam_policy_info:
          region: "${region}"
        register: iam_policies
      
      - name: Display policies
        debug:
          var: iam_policies.policies`;
        break;
        
      case 'create_role':
        playbookContent += `
      - name: Create IAM role
        amazon.aws.iam_role:
          region: "${region}"
          name: "${roleName}"
          ${assumeRoleDocParam}
          state: present
  ${formatYamlParams({
    path,
    managed_policies: managedPolicies
  })}
        register: iam_result
      
      - name: Display role details
        debug:
          var: iam_result`;
        break;
        
      case 'create_policy':
        playbookContent += `
      - name: Create IAM policy
        amazon.aws.iam_policy:
          region: "${region}"
          policy_name: "${policyName}"
          ${policyDocParam}
          state: present
  ${formatYamlParams({ path })}
        register: iam_result
      
      - name: Display policy details
        debug:
          var: iam_result`;
        break;
        
      case 'delete_role':
        playbookContent += `
      - name: Delete IAM role
        amazon.aws.iam_role:
          region: "${region}"
          name: "${roleName}"
          state: absent
        register: iam_role_delete
      
      - name: Display deletion result
        debug:
          var: iam_role_delete`;
        break;
        
      case 'delete_policy':
        playbookContent += `
      - name: Delete IAM policy
        amazon.aws.iam_policy:
          region: "${region}"
          policy_name: "${policyName}"
          state: absent
        register: iam_policy_delete
      
      - name: Display deletion result
        debug:
          var: iam_policy_delete`;
        break;
        
      default:
        throw new AnsibleError(`Unsupported IAM action: ${action}`);
    }
    
    // Execute the generated playbook, passing policy docs if needed
    return executeAwsPlaybook(`iam-${action}`, playbookContent, '', tempFiles);
  }

• src/sysoperator/common/types.ts:103-113 (schema)

  Zod schema IAMSchema defining the input validation for the aws_iam tool, including required region and action from IAMActionEnum, and optional fields for IAM operations.

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

• src/sysoperator/index.ts:111-115 (registration)

  Tool registration in the toolDefinitions object, specifying name 'aws_iam', its description, input schema (aws.IAMSchema), and handler function (aws.iamOperations).

  aws_iam: {
    description: 'Manage AWS IAM roles and policies',
    schema: aws.IAMSchema,
    handler: aws.iamOperations,
  },

• src/sysoperator/common/types.ts:20-21 (schema)

  Zod enum defining possible actions for the aws_iam tool, used in IAMSchema.

  export const IAMActionEnum = z.enum(['list_roles', 'list_policies', 'create_role', 'create_policy', 'delete_role', 'delete_policy']);
  export type IAMAction = z.infer<typeof IAMActionEnum>;

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

  Shared helper function used by iamOperations (and other AWS handlers) to create temp dir, write playbook and extra files, execute ansible-playbook, 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);
      }
    }
  }