Ansible MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/sysoperator/index.ts:106-110 (registration)

  Registers the 'aws_cloudformation' tool in the toolDefinitions map, linking it to its description, input schema, and handler function.
  aws_cloudformation: { description: 'Manage AWS CloudFormation stacks', schema: aws.CloudFormationSchema, handler: aws.cloudFormationOperations, },
• src/sysoperator/operations/aws.ts:434-514 (handler)

  Handler function for 'aws_cloudformation' tool. Validates input, generates an Ansible playbook dynamically for actions like list/create/update/delete CloudFormation stacks, handles template files, and executes via Ansible.
  export async function cloudFormationOperations(args: CloudFormationOptions): Promise<string> { await verifyAwsCredentials(); const { action, region, stackName, templateBody, templateUrl, parameters, capabilities, tags } = args; const tempFiles: { filename: string, content: string }[] = []; let templateParam = ''; if (templateBody) { // Prepare template body to be written to a temp file tempFiles.push({ filename: 'template.cfn', content: templateBody }); templateParam = 'template: "template.cfn"'; // Reference the temp file name } else if (templateUrl) { templateParam = `template_url: "${templateUrl}"`; } else if (action === 'create' || action === 'update') { // Template is required for create/update throw new AnsibleError('Either templateBody or templateUrl must be provided for CloudFormation create/update actions.'); } let playbookContent = `--- - name: AWS CloudFormation ${action} operation hosts: localhost connection: local gather_facts: no tasks:`; switch (action) { case 'list': playbookContent += ` - name: List CloudFormation stacks amazon.aws.cloudformation_info: region: "${region}" register: cfn_info - name: Display stacks debug: var: cfn_info.stacks`; break; case 'create': case 'update': playbookContent += ` - name: ${action === 'create' ? 'Create' : 'Update'} CloudFormation stack amazon.aws.cloudformation: region: "${region}" stack_name: "${stackName}" state: present ${templateParam} # Use the determined template parameter ${formatYamlParams({ template_parameters: parameters, capabilities, tags })} register: cfn_result - name: Display stack outputs/result debug: var: cfn_result`; break; case 'delete': playbookContent += ` - name: Delete CloudFormation stack amazon.aws.cloudformation: region: "${region}" stack_name: "${stackName}" state: absent register: cfn_delete - name: Display deletion result debug: var: cfn_delete`; break; default: throw new AnsibleError(`Unsupported CloudFormation action: ${action}`); } // Execute the generated playbook, passing template body if needed return executeAwsPlaybook(`cloudformation-${action}`, playbookContent, '', tempFiles); }
• src/sysoperator/common/types.ts:17-100 (schema)

  Defines the input schema (CloudFormationSchema) and action enum for validating tool arguments, including required region and optional parameters for CloudFormation operations.
  export const CloudFormationActionEnum = z.enum(['list', 'create', 'update', 'delete']); export type CloudFormationAction = z.infer<typeof CloudFormationActionEnum>; export const IAMActionEnum = z.enum(['list_roles', 'list_policies', 'create_role', 'create_policy', 'delete_role', 'delete_policy']); export type IAMAction = z.infer<typeof IAMActionEnum>; 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>;
• src/sysoperator/operations/aws.ts:77-116 (helper)

  Helper function used by AWS tool handlers (including CloudFormation) to create temp directories, write playbooks/templates, execute ansible-playbook, and clean up.
  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); } } }