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