Ara Records MCP Server

Instructions

Implementation Reference

• ara-server.js:472-507 (handler)

  Specific handler logic for the 'get_playbook_status' tool. Fetches playbook details without tasks or results and returns a concise status summary including progress, timing, and path.

  if (name === 'get_playbook_status') {
    const { playbook_id } = args;
  
    try {
      const details = await fetchPlaybookDetails(playbook_id, false, false);
  
      // Return just the summary without task details
      const status = {
        id: details.id,
        status: details.status,
        progress: details.progress,
        started: details.started,
        ended: details.ended,
        duration: details.duration,
        path: details.path,
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(status, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error checking playbook ${playbook_id} status: ${error.message}`,
          },
        ],
      };
    }
  }

• ara-server.js:257-266 (schema)

  Input schema for the 'get_playbook_status' tool, defining the required 'playbook_id' parameter.

  inputSchema: {
    type: 'object',
    properties: {
      playbook_id: {
        type: 'number',
        description: 'The ID of the playbook to check',
      },
    },
    required: ['playbook_id'],
  },

• ara-server.js:254-267 (registration)

  Registration of the 'get_playbook_status' tool in the list returned by ListToolsRequestHandler, including name, description, and input schema.

  {
    name: 'get_playbook_status',
    description: 'Get a quick summary of playbook execution status without detailed task information. Useful for checking if a playbook is complete or monitoring multiple playbooks.',
    inputSchema: {
      type: 'object',
      properties: {
        playbook_id: {
          type: 'number',
          description: 'The ID of the playbook to check',
        },
      },
      required: ['playbook_id'],
    },
  },

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

  Helper function fetchPlaybookDetails used by 'get_playbook_status' (and 'watch_playbook') to retrieve and summarize playbook data from the ARA API, with optional task and result details.

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