Ara Records MCP Server

Instructions

Implementation Reference

• ara-server.js:230-253 (registration)

  Registration of the 'watch_playbook' tool in getToolsList(), including name, description, and input schema.

  {
    name: 'watch_playbook',
    description: 'Monitor a playbook execution in real-time. Returns detailed progress including task completion, current status, and execution timeline. Call repeatedly to track progress.',
    inputSchema: {
      type: 'object',
      properties: {
        playbook_id: {
          type: 'number',
          description: 'The ID of the playbook to monitor',
        },
        include_tasks: {
          type: 'boolean',
          description: 'Include detailed task information (default: true)',
          default: true,
        },
        include_results: {
          type: 'boolean',
          description: 'Include task result details (default: false, can be verbose)',
          default: false,
        },
      },
      required: ['playbook_id'],
    },
  },

• ara-server.js:233-252 (schema)

  Input schema definition for the watch_playbook tool.

  inputSchema: {
    type: 'object',
    properties: {
      playbook_id: {
        type: 'number',
        description: 'The ID of the playbook to monitor',
      },
      include_tasks: {
        type: 'boolean',
        description: 'Include detailed task information (default: true)',
        default: true,
      },
      include_results: {
        type: 'boolean',
        description: 'Include task result details (default: false, can be verbose)',
        default: false,
      },
    },
    required: ['playbook_id'],
  },

• ara-server.js:446-470 (handler)

  Handler logic for executing the watch_playbook tool within the CallToolRequestSchema request handler. Extracts parameters and calls the fetchPlaybookDetails helper.

  if (name === 'watch_playbook') {
    const { playbook_id, include_tasks = true, include_results = false } = args;
  
    try {
      const details = await fetchPlaybookDetails(playbook_id, include_tasks, include_results);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(details, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error monitoring playbook ${playbook_id}: ${error.message}`,
          },
        ],
      };
    }
  }

• ara-server.js:298-390 (helper)

  Core helper function that implements the logic for fetching playbook details, progress calculation, and optional task/result data retrieval used by watch_playbook.

  async function fetchPlaybookDetails(playbookId, includeTasks = true, includeResults = false) {
    try {
      // Fetch playbook data
      const playbookResponse = await fetch(`${ARA_API_SERVER}${API_PATH}/playbooks/${playbookId}`, {
        headers: createAuthHeaders(),
      });
  
      if (!playbookResponse.ok) {
        throw new Error(`HTTP ${playbookResponse.status}: ${playbookResponse.statusText}`);
      }
  
      const playbook = await playbookResponse.json();
  
      // Calculate progress
      const totalTasks = playbook.items.tasks || 0;
      const totalResults = playbook.items.results || 0;
      const progressPercent = totalTasks > 0 ? Math.round((totalResults / totalTasks) * 100) : 0;
  
      const summary = {
        id: playbook.id,
        status: playbook.status,
        path: playbook.path,
        started: playbook.started,
        ended: playbook.ended,
        duration: playbook.duration,
        ansible_version: playbook.ansible_version,
        controller: playbook.controller,
        user: playbook.user,
        progress: {
          percent: progressPercent,
          tasks_total: totalTasks,
          tasks_completed: totalResults,
          plays: playbook.items.plays,
          hosts: playbook.items.hosts,
        },
        labels: playbook.labels,
      };
  
      // Optionally fetch task details
      if (includeTasks) {
        const tasksResponse = await fetch(
          `${ARA_API_SERVER}${API_PATH}/tasks?playbook=${playbookId}&limit=100&order=started`,
          {
            headers: createAuthHeaders(),
          }
        );
  
        if (tasksResponse.ok) {
          const tasksData = await tasksResponse.json();
          summary.tasks = tasksData.results.map(task => ({
            id: task.id,
            name: task.name,
            status: task.status,
            action: task.action,
            started: task.started,
            ended: task.ended,
            duration: task.duration,
            tags: task.tags,
          }));
          summary.tasks_count = tasksData.count;
        }
      }
  
      // Optionally fetch result details
      if (includeResults) {
        const resultsResponse = await fetch(
          `${ARA_API_SERVER}${API_PATH}/results?playbook=${playbookId}&limit=100&order=started`,
          {
            headers: createAuthHeaders(),
          }
        );
  
        if (resultsResponse.ok) {
          const resultsData = await resultsResponse.json();
          summary.results = resultsData.results.map(result => ({
            id: result.id,
            task: result.task,
            host: result.host,
            status: result.status,
            changed: result.changed,
            started: result.started,
            ended: result.ended,
            duration: result.duration,
          }));
          summary.results_count = resultsData.count;
        }
      }
  
      return summary;
    } catch (error) {
      throw new Error(`Failed to fetch playbook details: ${error.message}`);
    }
  }