Ansible MCP Server

Instructions

Implementation Reference

• src/sysoperator/operations/playbooks.ts:13-52 (handler)

  The handler function that runs an Ansible playbook by constructing and executing the ansible-playbook command with provided options like inventory, extra vars, tags, and limit.

  export async function runPlaybook(options: RunPlaybookOptions): Promise<string> {
    const playbookPath = validatePlaybookPath(options.playbook);
    const inventoryPath = validateInventoryPath(options.inventory);
    
    // Build command
    let command = `ansible-playbook ${playbookPath}`;
    
    // Add inventory if specified
    if (inventoryPath) {
      command += ` -i ${inventoryPath}`;
    }
    
    // Add extra vars if specified
    if (options.extraVars && Object.keys(options.extraVars).length > 0) {
      const extraVarsJson = JSON.stringify(options.extraVars);
      command += ` --extra-vars '${extraVarsJson}'`;
    }
    
    // Add tags if specified
    if (options.tags) {
      command += ` --tags "${options.tags}"`;
    }
    
    // Add limit if specified
    if (options.limit) {
      command += ` --limit "${options.limit}"`;
    }
  
    try {
      // Execute command
      const { stdout, stderr } = await execAsync(command);
      return stdout || 'Playbook executed successfully (no output)';
    } catch (error) {
      // Handle exec error
      const execError = error as { stderr?: string; message: string };
      throw new AnsibleExecutionError(
        `Error running playbook: ${execError.message}`,
        execError.stderr
      );
    }

• src/sysoperator/common/types.ts:241-249 (schema)

  Zod schema defining the input parameters for the run_playbook tool: playbook (required), extraVars, inventory, tags, limit.

  export const RunPlaybookSchema = z.object({
    playbook: z.string().min(1, 'Playbook path is required'),
    extraVars: z.record(z.any()).optional(),
    inventory: z.string().optional(),
    tags: z.string().optional(),
    limit: z.string().optional(),
  });
  
  export type RunPlaybookOptions = z.infer<typeof RunPlaybookSchema>;

• src/sysoperator/index.ts:55-59 (registration)

  Registration of the run_playbook tool in the toolDefinitions map, linking schema and handler.

  run_playbook: {
    description: 'Run an Ansible playbook',
    schema: RunPlaybookSchema,
    handler: playbooks.runPlaybook,
  },