Ansible MCP Server

Instructions

Implementation Reference

• src/sysoperator/operations/aws.ts:753-865 (handler)

  Primary handler function that destructures arguments, builds dynamic Ansible playbook YAML based on the specified Route53 action (list_zones, list_records, create_zone, create_record, delete_record, delete_zone), and executes it via executeAwsPlaybook.

  export async function route53Operations(args: Route53Options): Promise<string> {
    await verifyAwsCredentials();
  
    const { action, region, zoneId, zoneName, recordName, recordType, recordTtl, recordValue, recordState, comment } = args;
  
    let playbookContent = `---
  - name: AWS Route53 ${action} operation
    hosts: localhost
    connection: local
    gather_facts: no
    tasks:`;
    
    switch (action) {
      case 'list_zones':
        playbookContent += `
      - name: List Route53 hosted zones
        amazon.aws.route53_info:
          region: "${region}"
          query: hosted_zone
        register: route53_zones
      
      - name: Display hosted zones
        debug:
          var: route53_zones.HostedZones`;
        break;
        
      case 'list_records':
        playbookContent += `
      - name: List Route53 records
        amazon.aws.route53_info:
          region: "${region}"
          query: record_sets
          hosted_zone_id: "${zoneId}"
        register: route53_records
      
      - name: Display records
        debug:
          var: route53_records.ResourceRecordSets`;
        break;
        
      case 'create_zone':
        playbookContent += `
      - name: Create Route53 hosted zone
        amazon.aws.route53_zone:
          region: "${region}"
          zone: "${zoneName}"
          state: present
  ${formatYamlParams({ comment })}
        register: route53_result
      
      - name: Display zone details
        debug:
          var: route53_result`;
        break;
        
      case 'create_record':
        playbookContent += `
      - name: Create Route53 record
        amazon.aws.route53:
          region: "${region}"
          zone: "${zoneName}"
          record: "${recordName}"
          type: "${recordType}"
          ttl: ${recordTtl ?? 300}
          value: ${JSON.stringify(Array.isArray(recordValue) ? recordValue : [recordValue])}
          state: ${recordState ?? 'present'}
  ${formatYamlParams({ comment })}
        register: route53_result
      
      - name: Display record details
        debug:
          var: route53_result`;
        break;
        
      case 'delete_record':
        playbookContent += `
      - name: Delete Route53 record
        amazon.aws.route53:
          region: "${region}"
          zone: "${zoneName}"
          record: "${recordName}"
          type: "${recordType}"
          # Value might be needed for deletion depending on the record type/setup
          value: ${JSON.stringify(Array.isArray(recordValue) ? recordValue : [recordValue])} 
          state: absent
        register: route53_delete
      
      - name: Display deletion result
        debug:
          var: route53_delete`;
        break;
        
      case 'delete_zone':
        playbookContent += `
      - name: Delete Route53 hosted zone
        amazon.aws.route53_zone:
          region: "${region}"
          zone: "${zoneName}"
          state: absent
        register: route53_zone_delete
      
      - name: Display deletion result
        debug:
          var: route53_zone_delete`;
        break;
        
      default:
        throw new AnsibleError(`Unsupported Route53 action: ${action}`);
    }
    
    // Execute the generated playbook
    return executeAwsPlaybook(`route53-${action}`, playbookContent);
  }

• src/sysoperator/common/types.ts:138-151 (schema)

  Zod schema defining input validation for aws_route53 tool, including action enum and optional parameters for zones, records, etc.

  export const Route53Schema = z.object({
    action: Route53ActionEnum,
    region: z.string().min(1, 'AWS region is required'),
    zoneId: z.string().optional(),
    zoneName: z.string().optional(),
    recordName: z.string().optional(),
    recordType: z.string().optional(),
    recordTtl: z.number().optional(),
    recordValue: z.union([z.string(), z.array(z.string())]).optional(),
    recordState: z.string().optional(),
    comment: z.string().optional() // Added based on usage in aws.ts
  });
  
  export type Route53Options = z.infer<typeof Route53Schema>;

• src/sysoperator/index.ts:121-125 (registration)

  Tool registration in the toolDefinitions map, linking name 'aws_route53' to its schema and handler.

  aws_route53: {
    description: 'Manage AWS Route53 DNS records and zones',
    schema: aws.Route53Schema,
    handler: aws.route53Operations,
  },

• src/sysoperator/common/types.ts:26-27 (schema)

  Zod enum defining possible actions for the Route53 tool, used in the main Route53Schema.

  export const Route53ActionEnum = z.enum(['list_zones', 'list_records', 'create_zone', 'create_record', 'delete_record', 'delete_zone']);
  export type Route53Action = z.infer<typeof Route53ActionEnum>;

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

  Shared helper function used by all AWS handlers (including route53Operations) to execute dynamically generated Ansible playbooks, handling temp files 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);
      }
    }
  }