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