Ansible MCP Server

Instructions

Implementation Reference

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

  Registration of the 'aws_iam' tool in the toolDefinitions map, linking to its schema and handler.

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

• src/sysoperator/common/types.ts:102-115 (schema)

  Zod schema definition for 'aws_iam' tool inputs, including IAMActionEnum and parameters like action, region, roleName, policyName, etc.

  // 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>;

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

  The handler function that implements the aws_iam tool logic by dynamically generating Ansible playbooks for IAM operations (list, create, delete roles/policies) using AWS collection modules and executing them.

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