Ara Records MCP Server

Instructions

Implementation Reference

• ara-server.js:207-229 (registration)

  Registration of the 'ara_query' tool in the getToolsList() function, including its name, description, and input schema. This list is returned by the ListToolsRequestSchema handler.
  { name: 'ara_query', description: 'Query Ara API endpoints with automatic pagination defaults (limit=3, order=-started)', inputSchema: { type: 'object', properties: { endpoint: { type: 'string', description: 'API endpoint path (e.g., /api/v1/playbooks, /api/v1/plays/1). Supports query parameters like ?limit=10&offset=20&order=-started. If no limit is specified, defaults to 3 results.', }, method: { type: 'string', enum: ['GET', 'POST'], default: 'GET', }, body: { type: 'object', description: 'Request body for POST requests', }, }, required: ['endpoint'], }, },
• ara-server.js:210-228 (schema)

  Input schema definition for the 'ara_query' tool, specifying parameters like endpoint, method, and body.
  inputSchema: { type: 'object', properties: { endpoint: { type: 'string', description: 'API endpoint path (e.g., /api/v1/playbooks, /api/v1/plays/1). Supports query parameters like ?limit=10&offset=20&order=-started. If no limit is specified, defaults to 3 results.', }, method: { type: 'string', enum: ['GET', 'POST'], default: 'GET', }, body: { type: 'object', description: 'Request body for POST requests', }, }, required: ['endpoint'], },
• ara-server.js:396-444 (handler)

  Handler logic for the 'ara_query' tool within the CallToolRequestSchema request handler. Performs HTTP request to the ARA API endpoint with authentication, pagination defaults, and returns JSON response or error.
  if (name === 'ara_query') { const { endpoint, method = 'GET', body } = args; // Apply pagination defaults to prevent token overflow const paginatedEndpoint = addPaginationDefaults(endpoint); const options = { method, headers: createAuthHeaders(), }; if (body && method === 'POST') { options.body = JSON.stringify(body); } try { const fullUrl = `${ARA_API_SERVER}${paginatedEndpoint}`; console.error(`[DEBUG] Fetching URL: ${fullUrl}`); console.error(`[DEBUG] Headers:`, JSON.stringify(options.headers, null, 2)); const response = await fetch(fullUrl, options); console.error(`[DEBUG] Response status: ${response.status}`); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText} - URL: ${fullUrl}`); } const data = await response.json(); return { content: [ { type: 'text', text: JSON.stringify(data, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error: ${error.message}`, }, ], }; } }
• ara-server.js:278-295 (helper)

  Helper function addPaginationDefaults used by ara_query to automatically add limit=3 and order=-started to API endpoints preventing token overflow.
  // Helper function to add pagination defaults to endpoints function addPaginationDefaults(endpoint) { const url = new URL(`${ARA_API_SERVER}${endpoint}`); // Add default pagination if not already present if (!url.searchParams.has('limit')) { url.searchParams.set('limit', '3'); } // Add default ordering by most recent if not present if (!url.searchParams.has('order') && (endpoint.includes('/playbooks') || endpoint.includes('/plays') || endpoint.includes('/tasks') || endpoint.includes('/results'))) { url.searchParams.set('order', '-started'); } return url.pathname + url.search; }
• ara-server.js:67-80 (helper)

  Helper function createAuthHeaders used by ara_query for HTTP authentication.
  function createAuthHeaders() { const headers = { 'Content-Type': 'application/json', 'User-Agent': 'ara-records-mcp/1.0', }; // Add basic authentication if credentials are provided if (ARA_USERNAME && ARA_PASSWORD) { const credentials = Buffer.from(`${ARA_USERNAME}:${ARA_PASSWORD}`).toString('base64'); headers['Authorization'] = `Basic ${credentials}`; } return headers; }