Ansible MCP Server

Instructions

Implementation Reference

• src/sysoperator/operations/ad_hoc.ts:12-54 (handler)

  The main handler function that executes the Ansible ad-hoc command. It constructs the ansible CLI command from options and runs it using execAsync.

  export async function runAdHoc(options: RunAdHocOptions): Promise<string> {
    const inventoryPath = validateInventoryPath(options.inventory);
    
    // Build command
    let command = `ansible ${options.pattern}`;
    
    // Add module
    command += ` -m ${options.module}`;
    
    // Add module args if specified
    if (options.args) {
      command += ` -a "${options.args}"`;
    }
    
    // Add inventory if specified
    if (inventoryPath) {
      command += ` -i ${inventoryPath}`;
    }
    
    // Add become flag if needed
    if (options.become) {
      command += ' --become';
    }
    
    // Add extra vars if specified
    if (options.extra_vars && Object.keys(options.extra_vars).length > 0) {
      const extraVarsJson = JSON.stringify(options.extra_vars);
      command += ` --extra-vars '${extraVarsJson}'`;
    }
  
    try {
      // Execute command
      const { stdout, stderr } = await execAsync(command);
      return stdout || 'Command executed successfully (no output)';
    } catch (error) {
      // Handle exec error
      const execError = error as { stderr?: string; message: string };
      throw new AnsibleExecutionError(
        `Error running ad-hoc command: ${execError.message}`,
        execError.stderr
      );
    }
  }

• src/sysoperator/common/types.ts:211-218 (schema)

  Zod schema defining the input validation for the run_ad_hoc tool parameters.

  export const RunAdHocSchema = z.object({
    pattern: z.string().min(1, 'Host pattern is required'),
    module: z.string().default('shell'),
    args: z.string().optional(),
    inventory: z.string().optional(),
    become: z.boolean().optional(),
    extra_vars: z.record(z.any()).optional(),
  });

• src/sysoperator/index.ts:75-79 (registration)

  Registration of the 'run_ad_hoc' tool in the toolDefinitions object, specifying its description, input schema, and handler function.

  run_ad_hoc: {
    description: 'Run an Ansible ad-hoc command against specified hosts',
    schema: RunAdHocSchema,
    handler: adHoc.runAdHoc,
  },